React 组件

UGForm 表单

组织字段语义、布局和状态，并通过跨框架规则完成同步或异步校验、提交与重置。

导入方式

按需从包入口导入组件，并在应用入口引入一次样式文件。

tsx

import {
  UGForm, UGFormField, UGFormItem, UGFormLabel,
  UGFormControl, UGFormDescription, UGFormMessage, useForm,
} from '@ug666/ui-react'

规则校验与提交

规则支持提交、变化和失焦触发；失焦只在离开整个字段区域时生效，异步校验期间暴露 loading 与 validating 状态。

布局

垂直布局适合常规表单；横向布局统一标签列；内联布局适合筛选和紧凑操作。

尺寸、禁用与字段状态

根表单统一配置控件密度与禁用状态；字段仍保留独立错误、成功和加载语义。

属性与方法

属性	类型	默认值	说明
UGForm size / disabled	ControlSize / boolean	ConfigProvider	统一表单内控件尺寸和禁用状态，单个控件仍可显式覆盖。
UGForm layout	'vertical' \| 'horizontal' \| 'inline'	'vertical'	控制字段标签与控件的排列方式。
UGForm labelWidth	string \| number	'8rem'	横向布局的标签列宽度。
UGForm labelPosition	'top' \| 'left' \| 'right'	由 layout 推导	统一控制标签位于控件上方或左右两侧，字段可单独覆盖。
UGForm labelSuffix	string	''	统一追加在标签内容后的字符。
UGForm showRequiredMark	boolean	true	统一控制字段必填标记是否可见。
UGForm requiredMarkPosition	'left' \| 'right'	'left'	控制必填标记位于标签文本哪一侧。
UGForm showMessage / inlineMessage	boolean / boolean	true / false	统一控制错误消息是否渲染以及是否使用行内布局。
UGForm controller	UseFormReturn	—	接入 useForm 后自动同步字段错误、校验状态、必填规则、失焦触发和字段 DOM 注册。
UGFormField name	string	必填	字段名，同时作为未显式传值时的原生控件 name。
UGFormField error	string	—	字段错误信息，并同步 ARIA 与消息状态。
UGFormField required / status	boolean / 'default' \| 'validating' \| 'success'	false / default	字段必填标记与无错误时的过程状态。
UGFormControl	ReactElement	必填	为实际控件注入 id、name、aria-describedby、aria-invalid、aria-required 和校验状态。
FormRules	Record<field, FormRule \| FormRule[]>	—	支持 required、类型、长度、范围、正则、触发时机和同步/异步自定义校验。
useForm validate / validateField	async method	—	主动校验全部或指定字段，返回是否通过。
useForm handleSubmit	(callback) => submitHandler	—	阻止默认刷新、执行校验，仅在通过后调用业务提交。
useForm reset / resetFields / clearValidate	method	—	重置全部或指定字段，以及清除指定字段校验结果。
useForm setInitialValues	(values) => void	—	更新后续 reset/resetFields 使用的基线值，不直接覆盖当前编辑内容。
useForm getField	(name) => HTMLElement \| undefined	—	取得已注册字段容器，供聚焦、测量和自定义定位使用。
useForm scrollToField / scrollToError	method	—	定位指定字段或首个错误字段，支持自定义 ScrollIntoViewOptions。
useForm state	touched / dirtyFields / validatingFields / isDirty / isValid / isValidating	—	提供表单交互、修改和逐字段校验状态。