表单 Form

高性能、易扩展的表单解决方案，支持数据录入、校验和提交功能。

何时使用

• 需要进行数据录入和校验的场景
• 构建登录、注册、设置等表单页面
• 需要复杂表单交互和状态管理的应用

示例

基础表单

最简单的表单使用方式，包含基本的字段和提交功能。

表单布局

支持三种不同的表单布局：垂直（默认）、水平和内联。

浮动标签

使用浮动标签模式，节省空间并提升用户体验。

表单验证

支持多种验证规则，包括必填、长度、正则表达式、邮箱、URL等。

使用 useForm Hook

通过 useForm Hook 获取表单实例，实现更复杂的表单操作。

初始值

为表单设置初始值，并监听值的变化。

API

Form

参数	说明	类型	默认值
form	表单实例	FormInstance	-
initialValues	初始值	Partial<T>	-
layout	表单布局	'horizontal' | 'vertical' | 'inline'	'vertical'
floatingLabel	是否使用浮动标签	boolean	false
labelWidth	标签宽度（horizontal 布局时有效）	number | string	-
labelAlign	标签对齐方式	'left' | 'right'	'right'
disabled	是否禁用整个表单	boolean	false
onFinish	表单提交回调	(values: T) => void	-
onFinishFailed	表单提交失败回调	(errors: Record<string, string>) => void	-
onValuesChange	字段值改变回调	(changedValues: Partial<T>, allValues: T) => void	-
children	子元素	ReactNode	-

FormItem

参数	说明	类型	默认值
name	字段名	string	-
label	标签文本	ReactNode	-
required	是否必填（显示红色星号）	boolean	false
rules	验证规则	ValidationRule[]	[]
floatingLabel	是否使用浮动标签（覆盖 Form 级别设置）	boolean	-
help	帮助文本	ReactNode	-
extra	额外提示	ReactNode	-
noLabel	是否隐藏标签	boolean	false
className	自定义类名	string	-
children	子元素	ReactNode	-
labelWidth	标签宽度（覆盖 Form 级别设置）	number | string	-
valuePropName	值属性名	string	'value'
trigger	触发方式	string	'onChange'
validateTrigger	值收集触发方式	string | string[]	'onBlur'

useForm

获取表单实例的 Hook。

const [form] = useForm();

:::

FormInstance

方法	说明	类型
getFieldValue	获取字段值	(name: keyof T) => unknown
getFieldsValue	获取所有字段值	() => T
setFieldValue	设置字段值	(name: keyof T, value: unknown) => void
setFieldsValue	设置多个字段值	(values: Partial<T>) => void
resetFields	重置字段	() => void
validateFields	验证所有字段	() => Promise<T>
validateField	验证单个字段	(name: keyof T) => Promise<unknown>
getFieldError	获取字段错误	(name: keyof T) => string | undefined
getFieldsError	获取所有字段错误	() => Record<keyof T, string | undefined>
isFieldTouched	字段是否被触摸过	(name: keyof T) => boolean
isFieldValidating	字段是否正在验证	(name: keyof T) => boolean
submit	提交表单	() => void

ValidationRule

参数	说明	类型
required	是否必填	boolean
message	错误信息	string
min	最小长度	number
max	最大长度	number
pattern	正则表达式	RegExp
validator	自定义验证器	(value: unknown) => Promise<void> | void
type	类型验证	'string' | 'number' | 'email' | 'url'