> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eorion.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 表单通用设置项
> 表单组件的通用属性设置方法和代表的含义
本节介绍 ORION Formio组件中可配置的通用属性，包括其设置方法及具体含义。用户可以通过这些属性控制组件的显示样式、交互逻辑和数据行为，以满足不同业务场景的需求。
## 通用设置项
ORION Formio 组件支持多种通用设置项，涵盖：
* **显示**：控制组件的样式与外观。
* **数据**：定义组件与数据源的交互方式。
* **校验**：配置输入验证规则。
* **集成**：设置与外部系统或 API 的对接（尤其是用ORION引擎中变量的关系）。
* **条件**：根据条件动态调整组件的显示或行为。
* **逻辑**：实现更复杂的业务逻辑与交互控制。
接下来，我们将逐一介绍这些设置项的功能与配置方法。
显示设置用于控制组件在表单中的外观与呈现方式，包括标签位置、占位提示、描述信息、样式以及输入显示形式等。通过这些设置，可以优化表单的布局和用户体验。
* `标签`
组件在前端显示的名称。默认情况下，标签位于字段的左上角。
* `标签位置`
定义标签在组件中的显示位置。默认是“顶部”。可选项：顶部 / 左（左对齐）/ 左（右对齐）/ 右（左对齐）/ 右（右对齐）/ 底部。
* `标签宽度和边距`
当选择“左”或“右”标签位置时，可配置标签的宽度和边距，用于控制标签与输入区域之间的间距。宽度和边距值基于字段在表单中所占列宽的百分比。
* `占位符`
在字段为空时显示的简短提示文字，用于说明用户需要输入的内容。占位符不会随表单数据一同提交。
* `描述`
在字段下方显示的说明文字。常用于提供比占位符更详细的说明，或作为占位符的补充。
* `工具提示`
在字段标签旁添加一个问号图标，用户将鼠标悬停其上时，会显示设置的说明文字。适合提供简短的帮助提示，而不占用表单空间。
* `前缀`
在输入字段前显示的文本或符号，例如 \$ 表示金额字段。
* `后缀`
在输入字段后显示的文本或符号，例如 % 表示百分比。
* `自定义 CSS 类`
为组件添加自定义样式类，便于结合现有 UI 框架（如 Bootstrap：bg-info）。
* `标签索引（Tabindex）`
设置 HTML 元素的 tabindex 属性，用于控制键盘 Tab 键的聚焦顺序。详情参见 [MDN tabindex](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/tabindex)。
* `自动完成（Autocomplete）`
控制输入字段是否启用浏览器的自动完成功能。默认开启，浏览器会根据历史输入自动填充。可设置为 off 来禁用。详情参见 [MDN autocomplete](https://developer.mozilla.org/docs/Web/HTML/Attributes/autocomplete)。
* `隐藏`
隐藏组件，使其在表单界面上不可见，但仍保留在表单 JSON 和提交数据中。适合存放计算值或辅助数据。
* `隐藏标签`
隐藏字段的标签，仅显示输入框。常与占位符或描述配合使用，以节省空间。
* `隐藏输入`
将用户输入以掩码形式显示（例如用圆点 ● 替代），类似密码字段。适合处理敏感信息（如税号、身份证号）。
* `初始焦点`
表单加载时自动聚焦到该组件。如果多个组件都勾选了“初始焦点”，则表单 JSON 中最后一个勾选的组件生效。
* `禁用`
将组件设为不可编辑状态，用户无法输入或修改。常用于显示计算值或填充值，避免被修改。
* `表视图`
勾选后，该字段会在表单的 submission JSON 中以表格形式显示数据，适合列表化展示。
* `模态编辑`
启用后，组件在表单中显示为一个按钮。点击按钮会弹出模态窗口（Modal Window），在窗口中输入或编辑字段数据。
数据设置用于定义最终用户输入的数据，以及这些数据在表单中的交互方式和存储方式。通过数据设置，可以实现 **设置默认值**、**计算值**、**数据保护** 等功能。
* `多个值（Multiple Values）`
启用后，该组件的数据将以数组形式存储。常用于复选框、多选下拉框等需要返回多个值的场景。
* `默认值（Default Value）`
定义字段在表单初始加载时显示的默认内容。如果用户未修改，默认值会随表单一并提交。
* `截断空格（Trim Whitespace）`
自动清理字段值中多余的空格，确保数据整洁。
* `刷新组件数据（Refresh On）`
当依赖的其他组件值发生变化时，刷新当前组件的数据，常用于「级联选择」场景。
* `组件隐藏时清空值（Clear Value When Hidden）`
控制当组件隐藏时，是否清空其值，以及提交时是否包含该字段。
* `自定义默认值（Custom Default Value）`
使用 JavaScript/JSON 表达式为组件动态生成默认值。
* `计算值（Calculated Value）`
使用 JavaScript/JSON 表达式定义组件的计算值，可基于其他字段动态生成。
* `允许手工输入覆盖计算值（Allow Manual Override）`
启用后，如果用户手动修改了字段值，则不再应用计算逻辑。
“校验”设置用于确保用户输入的数据符合预期的规则和格式，从而提升表单的可靠性和安全性。
* `校验触发点 (Validation Trigger)`
确定校验的触发时机。
* *Change*：组件值发生变化时立即触发校验。
* *Blur*：组件失去焦点时触发校验。
* `必填 (Required)`
设置为必填后，组件的标签会显示必填标记。如果用户未填写该字段，表单将无法提交。
* `最小/最大长度 (Min/Max Length)`
限制字段值的范围。
* 字符串：检查输入的字符长度。
* 数字：检查输入的数值大小。
* 数组：检查数组的元素个数。
* `正则表达式模式 (Regular Expression Pattern)`
设置一个正则表达式模式。输入字符串必须与模式匹配才能通过校验。
* `错误标签 (Error Label)`
自定义错误消息中显示的字段名称，而非组件的 label 本身。
* `自定义错误消息 (Custom Error Message)`
定义一条自定义提示，覆盖默认的前端校验错误消息。适用于统一提示场景。
* `自定义校验 (Custom Validation)`
在“自定义验证”选项中编写 JavaScript 或 JSON 逻辑，实现个性化的校验规则。
* `JSONLogic 校验`
使用 JSONLogic 表达式直接定义校验规则，适用于无代码/低代码的逻辑配置。
* `自定义错误 (Custom Errors)`
可为不同的校验规则配置多条错误提示。例如：必填错误提示为“此字段不能为空”，最小字符数错误提示为“至少需要输入 5 个字符”。
“集成”设置用于为组件配置标识和扩展属性，便于在表单运行时或自定义逻辑中引用和操作。
* `表单字段 ID (Property Name / Key)`
指定组件数据在表单 JSON 中对应的字段 ID。
同一个表单中每个组件的字段 ID 必须唯一，否则会导致数据覆盖或提交冲突。
* `字段 Tags (Field Tags)`
为组件添加一个或多个标签，便于在逻辑规则、自定义脚本或查询中对组件进行分组或引用。
* `自定义属性 (Custom Properties)`
为组件添加任意键值对形式的属性，这些属性不会影响组件的基本功能，但可在前端逻辑或 API 调用时使用，适合扩展场景（例如：为某些组件标记元数据）。
“条件”设置用于控制组件在表单中的显示与隐藏逻辑，使表单能够根据用户的输入动态调整。
* `简易快速条件`
通过简单配置即可控制当前组件的显示或隐藏。例如，可以设置“当字段 A 的值为 X 时，显示字段 B”。
* `高级条件设置`
使用 **JavaScript 或 JSON 逻辑**编写条件表达式，控制组件的显示或隐藏。适合复杂场景，如多字段组合判断或基于动态计算结果的条件显示。
逻辑”功能提供了一个强大的规则引擎，可用于根据条件动态控制组件行为、数据值及自定义事件。逻辑按字段应用，每个字段可添加多个逻辑实例，实现灵活的控制。
使用逻辑功能，可以实现以下操作：
* 有条件地 **显示或隐藏组件**。
* 根据其他字段或计算结果 **设置组件值**。
* 修改或扩展组件的 **JSON 架构**，实现复杂表单布局或行为。
* 执行 **自定义事件或操作**，满足特定业务需求。
逻辑功能结合条件和数据设置使用，可大幅提升表单的智能化和动态交互能力。