--- order: 1 toc: content title: API --- # 表单属性 ## Props |
参数
| 说明 | 类型 |
默认值
| | ----------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | schema | **必填**，描述表单的 schema，详见 [schema 规范](/docs/form-render/api-schema.md) | SchemaBase | - | | beforeFinish | 在 onFinish 前触发，一般用于外部校验逻辑的回填 | `({ data, errors, schema, ...rest }) => Error[] \| Promise` | - | | configProvider | antd 的 configProvider，配置透传 | ConfigProviderProps | - | | 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 | 自定义组件，当内置组件无法满足时使用，详见 Widgets | `Record` | - | | watch | 监听表单的数据变化，详见 Watch | `Record 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 | 修改默认的校验提示信息，详见 ValidateMessages | `Record` | - | | validateTrigger | 统一设置字段触发验证的时机 | `string \| string[]` | `'onChange'` | | id | 表单的 id，一般用于标识一个表单的语义化名称 | `string \| number` | - | ## FormInstance |
参数
| 描述 | 类型 | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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` |