File size: 13,568 Bytes
c9d0005 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 | ---
order: 0
mobile: false
group:
title: API
order: 4
---
# 表单属性
## Props
| <div style="width:200px">参数</div> | 说明 | 类型 | <div style="width:100px">默认值</div> |
| ---------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------ |
| schema | **必填**，描述表单的 schema，详见 [协议配置项](/form-render/api-schema) | <a target="_blank" href="https://github.com/alibaba/x-render/blob/e2feff8fdb3bef5537b92a2157dbbf40b9d4eb17/packages/form-render/src/type.ts#L32">SchemaBase</a> | - |
| form | **必填**，`useForm` 创建的表单实例，与 Form 一对一绑定，详见[Forminstance](#forminstance) | `FormInstance` | - |
| onFinish | 提交后的回调，执行 `form.submit()` 后触发 | `(data) => void` | - |
| beforeFinish | 在 onFinish 前触发，一般用于外部校验逻辑的回填 | `({ data, errors, schema, ...rest }) => Error[] \| Promise<Error[]>` | - |
| onMount | 表单首次加载时触发 | `() => void` | - |
| displayType | 表单元素与 label 同行 or 分两行展示, inline 则整个展示自然顺排 | `'column' \| 'row' \| 'inline'` | column |
| labelAlign | label 标签的文本对齐方式 | `'left' \| 'right'` | right |
| colon | 是否显示 label 后面的冒号 | `boolean` | true |
| globalConfig | 表单全局配置，详见 [GlobalConfig](/form-render/api-props#globalconfig) | `GlobalConfig` | true |
| globalProps | 全局属性，注入到 widget 的 `addons.globalProps` 中 | `Record<string, any>` | - |
| widgets | 自定义组件，当内置组件无法满足时使用，详见[自定义组件](/form-render/advanced-widget) | `Record<string, ReactNode>` | - |
| watch | 监听表单的数据变化，详见 [Watch 监听](/form-render/advanced-linkage#watch-监听) | `Record<string, (val: any) => void \| { handler:(val:any) => void,immediate?: boolean }>` | - |
| removeHiddenData | 提交数据的时候是否去掉已经被隐藏的元素的数据，默认隐藏 | `boolean` | true |
| readOnly | 只读模式，一般用于预览展示，全文 text 展示 | `boolean` | false |
| className | 顶层 className | `string` | - |
| style | 顶层 style | `CSSProperties` | - |
| column | 一行展示多少列 | `number` | 1 |
| disabled | 禁用全部表单项 | `boolean` | false |
|scrollToFirstError | 提交失败自动滚动到第一个错误字段，默认关闭 | `boolean \|` <a href="https://github.com/scroll-into-view/scroll-into-view-if-needed/tree/ece40bd9143f48caf4b99503425ecb16b0ad8249#options" target="_blank">ScrollOptions</a> | false
| locale | 展示语言，目前只支持中文、英文 | `'zh-CN' \| 'en-US'` | zh-CN |
| configProvider | antd 的 configProvider，配置透传 | <a href="https://ant-design.antgroup.com/components/config-provider-cn/#API" target="_blank">ConfigProviderProps</a> | - |
| validateMessages | 修改默认的校验提示信息，详见[ValidateMessages](/form-render/advanced-validate) | `Record<string, string>` | - |
| id | 表单的 id，一般用于标识一个表单的语义化名称 | `string \| number` | - |
| antdVersion | antd 的版本 | `v4 \| v5` | `v5` |
## FormInstance
| <div style="width:200px">参数</div> | 描述 | 类型 |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| submit | 触发提交流程，一般在提交按钮上使用 | `() => void` |
| resetFields | 清空表单（也会清空一些内置状态，例如校验） | `(fieldPath?: Path[]) => void` |
| setErrorFields | 外部手动修改 errorFields 校验信息，用于外部校验回填 | `(error: Error[]) => void` |
| setValues | 外部手动修改 formData，用于已填写的表单的数据回填 | `(formData: any) => void` |
| setValueByPath | 外部修改指定单个 field 的数据(原名 onItemChange) | `(path: Path, value: any) => void` |
| setSchemaByPath | 指定路径修改 schema | `(path: Path, schema: any) => void` |
| setSchema | 指定多个路径修改 schema，cover 传true将直接替换 schema | `({ path: value }, cover?: boolean) => void` |
| getValues | 获取表单内部维护的数据, 如果参数为空则返回当前所有数据 | `(nameList?: Path[], filterFunc?: (meta: { touched: boolean, validating: boolean }, notFilterUndefined?:boolean,notFilterHideData?:boolean) => boolean) => any` |
| getHiddenValues | 获取隐藏的表单数据 | `() => any` |
| getSchema | 获取表单的 schema | `()=> object` |
| removeErrorField | 外部手动删除某一个 path 下所有的校验信息 | `(path: Path) => void` | |
| isFieldTouched | 检查某个表单是否被用户操作过 | `(name: Path) => boolean` |
| isFieldsTouched | 检查一组字段 fields 是否被用户操作过, allTouched 为 true 是检查是否所有字段都被操作过 | `(nameList?: Path[], allTouched?: boolean) => boolean` |
| isFieldValidating | 检查对应字段 field 是否正在校验 | `(name: Path) => boolean` |
| scrollToPath | 滚动到 path 对应的位置 | `(name: Path , options?:` <a href="https://github.com/stipsan/scroll-into-view-if-needed/tree/ece40bd9143f48caf4b99503425ecb16b0ad8249#options" target="_blank">ScrollOptions</a>`) => boolean` | |
| getFieldError | 获取对应字段 field 的错误信息 | `(name: Path) => string[]` |
| getFieldsError | 获取一组字段 fields 对应的错误信息, 返回数组形式; 入参为空则获取所有字段对应的错误信息 | `(nameList: Path[]) => Error[]` |
| validateFields | 触发表单校验 | `(nameList?: Path[]) => Promise<any>` |
## GlobalConfig
| <div style="width:200px">参数</div> | 描述 | 类型 |
| ----------------- | ----------------------------------------------------------------------------------- | ----------------------------- |
| mustacheDisabled | 是否禁用表达式 | `boolean` |
| listOperate | 列表表单配置 | `ListOperate` |
### ListOperate
| <div style="width:200px">参数</div> | 描述 | 类型 |
| ----------------- | ----------------------------------------------------------------------------------- | ----------------------------- |
| btnType | 列表表单操作按钮样式 | `'icon'\|'text'` |
| hideMove | 是否隐藏移动按钮 | `boolean` |
|