| --- |
| 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` | |
|
|
