File size: 14,939 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 | ---
order: 1
toc: content
title: API
---
# 表单属性
## Props
| <div style="width:150px">参数</div> | 说明 | 类型 | <div style="width:100px">默认值</div> |
| ----------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| schema | **必填**，描述表单的 schema，详见 [schema 规范](/docs/form-render/api-schema.md) | <a target="_blank" href="https://github.com/alibaba/x-render/blob/e2feff8fdb3bef5537b92a2157dbbf40b9d4eb17/packages/form-render/src/type.ts#L32">SchemaBase</a> | - |
| beforeFinish | 在 onFinish 前触发，一般用于外部校验逻辑的回填 | `({ data, errors, schema, ...rest }) => Error[] \| Promise<Error[]>` | - |
| configProvider | antd 的 configProvider，配置透传 | <a href="https://ant-design.antgroup.com/components/config-provider-cn/#API" target="_blank">ConfigProviderProps</a> | - |
| className | 顶层 className | `string` | - |
| displayType | 表单元素与 label 同行 or 分两行展示, inline 则整个展示自然顺排 | `'column' \| 'row'` | `'column'` |
| disabled | 是否禁用 | `boolean` | `false` | column |
| form | **必填**，`useForm` 创建的表单实例，与 Form 一对一绑定，详见 [FormInstance](#forminstance) | `FormInstance` | - |
| footer | 表单尾部的内容，常常用来放置提交按钮 | `ReactNode` | - |
| hasFeedback | 是否展示错误反馈 | `boolean` | `true` |
| initialValues | 表单默认值，只有初始化以及重置时生效 | `object` | - |
| widgets | 自定义组件，当内置组件无法满足时使用，详见 <a href="/docs/form-render/advanced-widget.md" target="_blank">Widgets</a> | `Record<string, ReactNode>` | - |
| watch | 监听表单的数据变化，详见 <a href="/docs/form-render/advanced-linkage.md#watch-监听" target="_blank">Watch</a> | `Record<string, (val: any) => void \| { handler:(val:any) => void,immediate?: boolean }>` | - |
| removeHiddenData | 提交数据的时候是否去掉已经被隐藏的元素的数据，默认隐藏 | `boolean` | `true` |
| readOnly | 只读模式，一般用于预览展示，全文 text 展示 | `boolean` | `false` |
| style | 顶层 style | `CSSProperties` | - |
| mode | 支持默认和卡片两种模式 | `'default' \| 'card'` | `'default'` |
| onMount | 表单首次加载时触发 | `(changedFields, allFields) => void` | - |
| onFinish | 提交后的回调，执行 `form.submit()` 后触发 | `(data, errors: Error[]) => void` | - |
| onFinishFailed | 提交表单且数据验证失败后触发 | `({ values, errorFields, outOfDate }) => void` | - |
| requiredMarkStyle | 必填选填的标记样式 | `'asterisk' \| 'text-required' \| 'text-optional' \|'none'` | `'asterisk'` |
| locale | 展示语言，目前只支持中文、英文 | `'zh-CN' \| 'en-US'` | `'zh-CN'` |
| validateMessages | 修改默认的校验提示信息，详见 <a href="/docs/form-render/advanced-validate.md" target="_blank">ValidateMessages</a> | `Record<string, string>` | - |
| validateTrigger | 统一设置字段触发验证的时机 | `string \| string[]` | `'onChange'` |
| id | 表单的 id，一般用于标识一个表单的语义化名称 | `string \| number` | - |
## FormInstance
| <div style="width:150px">参数</div> | 描述 | 类型 |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| submit | 触发提交流程，一般在提交按钮上使用 | `() => void` |
| resetFields | 清空表单（也会清空一些内置状态，例如校验） | `({formData?: any, submitData?: any, errorFields?: Error[], touchedKeys?: string[], allTouched?: boolean}) => void` |
| setErrorFields | 外部手动修改 errorFields 校验信息，用于外部校验回填 | `(error: Error[]) => void` |
| setValues | 外部手动修改 formData，用于已填写的表单的数据回填 | `(formData: any) => void` |
| setValueByPath | 外部修改指定单个 field 的数据(原名 onItemChange) | `(path: Path, value: any) => void` |
| setSchemaByPath | 指定路径修改 schema | `(path: Path, value: any) => void` |
| setSchema | 指定多个路径修改 schema | `({ path: value }) => void` |
| getValues | 获取表单内部维护的数据, 如果参数为空则返回当前所有数据 | `(nameList?: Path[], filterFunc?: (meta: { touched: boolean, validating: boolean }) => boolean) => any` |
| getHiddenValues | 获取隐藏的表单数据 | `() => any` |
| removeErrorField | 外部手动删除某一个 path 下所有的校验信息 | `(path: Path) => void` | |
| isFieldTouched | 检查某个表单是否被用户操作过 | `(name: Path) => boolean` |
| isFieldsTouched | 检查一组字段 fields 是否被用户操作过, allTouched 为 true 是检查是否所有字段都被操作过 | `(nameList?: Path[], allTouched?: boolean) => boolean` |
| isFieldValidating | 检查对应字段 field 是否正在校验 | `(name: Path) => boolean` |
| getFieldError | 获取对应字段 field 的错误信息 | `(name: Path) => string[]` |
| getFieldsError | 获取一组字段 fields 对应的错误信息, 返回数组形式; 入参为空则获取所有字段对应的错误信息, 返回错误信息 | `(nameList: Path[]) => Error[]` |
| setFields | 设置一组字段状态 | `(nameList: Field[]) => void` |
| validateFields | 触发表单验证 | `(nameList?: Path[]) => Promise` |
|