# 设置UI引擎前端页面表单组件属性
表单组件由表单容器组件（form）、表单项容器组件（form-item）及各类表单元素（输入框、下拉框、日期选择器等）嵌套组合而成。该组件广泛用于数据收集、验证与提交场景，例如设备参数配置、生产计划录入等。支持表单全局禁用、布局自定义、多规则校验、异步校验等核心功能，可结合业务规则实现数据的标准化录入，保障生产、设备、物料等核心数据的准确性与合规性。
#### 前提条件
已在当前页面添加"表单"组件，具体操作请参见[为UI引擎前端页面添加物料组件](https://support.huaweicloud.com/usermanual-idme/idme_ui_0016.html)。
#### 配置入口
1. 在页面设计器的中心画布区，单击选中"表单"组件。
2. 在右侧设置面板中，单击![](https://support.huaweicloud.com/usermanual-idme/figure/zh-cn_image_0000002509683124.png)，即可展开"属性"设置面板。
 
#### Form组件-基础属性
| 属性名称   | 说明                                                                                                                    | 是否支持变量绑定 |
|:---|:---|:---|
| 添加表单项  | 用于在表单容器中插入表单元素。插入位置为默认按钮元素之前，仅支持设计器可视化操作，不可通过变量绑定动态调整。具体配置请参见[表1]。 | 否        |
| 禁用     | 是否禁用整个表单。 如果设置为"true"，则表单下的所有表单元素都会被禁用。                                 | 是        |
| 行内布局   | 是否启用行内布局模式，多个表单项会在一行展示。                                                                                               | 是        |
| 必填标识占位 | 是否隐藏必填字段标签旁边的红色星号。                                                                                                    | 是        |
| 标签溢出隐藏 | 标签超长时是否以"tooltip"形式展示完整文本。                                                                                            | 是        |
| 标签宽度   | 表单中标签的占位宽度，单位为像素或百分比。                                                                                                 | 是        |
| 标签后缀   | 为所有的标签添加统一的后缀。                                                                                                        | 是        |
| 标签位置   | 标签的位置，可选值："right"（右对齐）、"left"（左对齐）、"top"（标签单独一行然后左对齐）。默认为"top"。                                                       | 是        |
   
 表1添加表单项属性 
| 属性名称 | 说明                                                                                                                               | 是否支持变量绑定 |
|:---|:---|:---|
| 标签   | 表单项展示的标签名称，如"设备编号"、"运行温度"。                                                                                                       | 否        |
| 校验字段 | 对应表单域"model"字段。 如需使用表单校验，该属性为必填项。                                                | 否        |
| 表单元素 | 选择需嵌入当前表单项的表单组件，可选值：插槽、输入框、单选框组、复选框、下拉框、日期选择器、时间选择器、开关。 选择"插槽"时，需手动从"物料"面板中拖入目标组件。 | 否        |
   
 #### Form组件-校验属性
| 属性名称   | 说明                                                                                                                                                                                                                                                                                                                                                                                                             | 是否支持变量绑定 |
|:---|:---|:---|
| 数据对象   | 表单数据存储对象，格式为键值对。示例： ``` {equipmentNo: '', temperature: 0, productionDate: ''} ``` 每个键对应一个表单项的校验字段。                                                                                                                                                                                                                                                               | 是        |
| 校验规则   | 表单验证规则配置对象，数据结构定义如下： ``` { [prop: string]: FormRuleItem[] } ``` 其中，"prop"为表单项的校验字段，对应值为该字段的校验规则数组，具体配置请参见[表2]。                                                                                                                                                                                              | 是        |
| 校验提示类型 | 校验失败时错误提示的展示方式，默认为"tip"。 - tip：以"tooltip"形式悬浮展示（节省空间，适配紧凑型表单）。  - text：在"form-item"下方展示（清晰醒目，适配大屏/重要数据表单）。   | 是        |
   
 表2FormRuleItem（校验规则对象属性说明） 
| 属性名称           | 类型                                                                                  | 是否必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                                         |
|:---|:---|:---|:---|
| required       | Boolean                                                                             | 否    | 标识当前表单项是否为必填项。 设置为"true"时，空值将触发校验失败。                                                                                                                                                                                                                                                                                                                                      |
| message        | String                                                                              | 否    | 校验失败时展示给用户的提示文案（如"请输入设备编号"）。                                                                                                                                                                                                                                                                                                                                                                                               |
| type           | Enum                                                                                | 否    | 内置的校验类型，可选值：date、dateTime、float、array、number、url、time、email、object、boolean。                                                                                                                                                                                                                                                                                                                                                |
| trigger        | String \| Array\<String\>                                                           | 否    | 校验触发时机，默认为"\["change", "blur"\]"。 仅需主动校验时可设置为空数组"\[\]"。                                                                                                                                                                                                                                                                                                                     |
| validator      | (rule, value, callback: (err?: Error) =\> void, data?, options?) =\> void           | 否    | 自定义同步校验函数。 内置校验不满足需求时使用，通过"callback"函数回调标识校验结果： - 传入"Error"实例：校验成功。  - 不传参：校验成功。   |
| asyncValidator | (rule, value, callback: (err?: Error) =\> void, data?, options?) =\> Promise\<any\> | 否    | 自定义异步校验函数。通过"Promise"状态标识校验结果： - resolve：表示校验成功。  - reject：表示校验失败。                                                           |
   
#### 其他
如下属性适用于UI引擎所有组件，用于精细化控制。
| 属性名称   | 说明                                                                                                                                 | 是否支持变量绑定 |
|:---|:---|:---|
| 元素id值  | 对应HTML标签的"id"属性，同一页面内必须唯一。                                                                                                         | 是        |
| 样式类    | 对应HTML标签的"class"属性，为空格分隔的类名列表，用于自定义组件样式。默认为"component-base-style"。                                                                 | 是        |
| ref引用类 | 对应Vue的"ref"属性，用于注册模板引用以访问组件实例方法。 如果为"数据源表单"组件，会自动填充默认值。 | 是        |
   
#### Form组件-组件事件
| 事件名称     | 类型定义                                                              | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|:---|:---|:---|
| validate | ``` (prop: string, isValid: boolean, message: string) => void ``` | 任一表单项被校验后触发。 - prop：触发校验的表单项字段名称。  - isValid：校验是否通过。  - message：校验失败时的提示文案。   |
   
#### Form组件-组件实例方法
| 方法名称          | 类型定义                                                                               | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
|:---|:---|:---|
| clearValidate | ``` (prop: string | string[]) => void ```                                          | 移除表单项校验结果。 - 传入"prop"：重置指定字段校验状态。  - 不传参：清空整表校验状态。                                                                                                                                                                                                                                                                                                                          |
| resetFields   | ``` () => void ```                                                                 | 对整个表单进行重置，将所有字段值重置为初始值并移除校验结果。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| validate      | ``` (callback: (isValid: boolean, fields?: Array<Object>)) => Promise<boolean> ``` | 校验整个表单。 - "callback"回调函数参数： - isValid：整表校验是否通过。  - fields：未通过校验的字段列表。    - 返回"Promise"："resolve"表示校验通过，"reject"表示校验失败。   |
| validateField | ``` (field: string, callback: (msg: string, field: Object ) => void) => void ```   | 校验指定表单字段。 - field：单个字段名称或字段名数组。  - "callback"回调函数：每个字段校验完成后依次调用，返回该字段的校验提示文案和字段对象。                                                                                                                                                                                                                                                                                          |
   
访问组件实例使用方法：
```
// 调用表单校验方法（其他方法调用方式类似）
this.$('ref引用类').validate((isValid, fields) => {
  if (isValid) {
    console.log('表单校验通过，可提交数据');
  } else {
    console.log('表单校验失败，失败字段：', fields);
  }
});
```
![](https://support.huaweicloud.com/usermanual-idme/public_sys-resources/caution_3.0-zh-cn.png)
组件实例只能在JS面板中访问。
#### FormItem组件-基础属性
FormItem组件用于包裹表单元素（输入框、下拉框等），是实现表单校验的必要容器，需与"Form"组件配合使用。
| 属性名称 | 说明                                                                                                             | 是否支持变量绑定 |
|:---|:---|:---|
| 标签文本 | 表单项对应的标签文本。                                                                                                    | 是        |
| 校验字段 | 对应[Form组件-校验属性]中"数据对象"的属性名称，必须与"Form"校验规则中的字段一致，确保校验功能生效。 | 是        |
| 必填   | 标识表单项是否为必填项，优先级高于[Form组件-校验属性]中的"required"属性。             | 是        |
   
#### FormItem组件-插槽信息
| 插槽名称 | 说明                                                                                                   |
|:---|:---|
| 标签名  | 用于自定义表单项标签内容。 配置式标签仅支持纯文本，如需在标签后添加图标、链接等额外内容，需通过该插槽实现。 |