组件 · 数据录入
Form 表单
布局/标签/说明/错误与 a11y 关联的表单组合壳；无内置值收集与校验引擎。可用 FormGroup/FormFieldSet 分组。
使用建议
- 避免：假设 Form 内置校验引擎或值收集
- 避免：杜撰 FilterBar 组件
- 限制：组合壳；校验与提交逻辑由应用自管
引入
import {
Field,
FieldContent,
FieldDescription,
FieldError,
FieldGroup,
FieldLabel,
// …共 27 个导出
} from '@selrux/ui/form';演练场
调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。
代码演示
基础用法
FormItem 提供标签、说明与错误信息，并把 id / aria 关联到内部控件。
布局
layout 为 vertical / horizontal / inline；horizontal 时可设 labelWidth。
必填标记与禁用
requiredMark="optional" 改为标注可选项；disabled 禁用整组控件。
表单级设置
size 尺寸；labelAlign 标签对齐；colon 标签后冒号；FormItem 的 orientation（horizontal / vertical / responsive）与 errors 错误列表。
字段与分组
Field 的 label / description / error / errors / invalid / orientation；FieldError 的 errors；FieldLegend 与 FormLegend 的 variant（legend / label）；FormMessage 的 errors。
API
属性覆盖：示例用到 23 / 23 个自有属性（100%）
由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。
Field
FormItem 的 ui-main 别名。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
orientation | - | "horizontal" | "vertical" | "responsive" | - |
label | - | ReactNode | - |
description | - | ReactNode | - |
error | - | ReactNode | - |
errors | - | FormErrorItem[] | - |
invalid | - | boolean | - |
另有 281 项原生属性与事件继承自 HTMLAttributes，原样透传。
FieldContent
FormContent 的 ui-main 别名。
无自有属性；其余 280 项原生属性继承自 HTMLAttributes。
FieldDescription
FormDescription 的 ui-main 别名。
无自有属性；其余 280 项原生属性继承自 HTMLAttributes。
FieldError
FormMessage 的 ui-main 别名。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
errors | - | FormErrorItem[] | - |
另有 280 项原生属性与事件继承自 HTMLAttributes，原样透传。
FieldGroup
FormGroup 的 ui-main 别名。
无自有属性；其余 280 项原生属性继承自 HTMLAttributes。
FieldLabel
FormLabel 的 ui-main 别名。
无自有属性；其余 283 项原生属性继承自 HTMLAttributes / LabelHTMLAttributes。
FieldLegend
FormLegend 的 ui-main 别名。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
variant | - | "label" | "legend" | - |
另有 280 项原生属性与事件继承自 HTMLAttributes，原样透传。
FieldSeparator
FormSeparator 的 ui-main 别名。
无自有属性；其余 280 项原生属性继承自 HTMLAttributes。
FieldSet
FormFieldSet 的 ui-main 别名。
无自有属性；其余 283 项原生属性继承自 FieldsetHTMLAttributes / HTMLAttributes。
FieldTitle
FormTitle 的 ui-main 别名。
无自有属性；其余 280 项原生属性继承自 HTMLAttributes。
Form
复合导出：声明式根 + Form.useForm 门面。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
size | - | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | - |
layout | 表单布局。默认 vertical。 | "inline" | "horizontal" | "vertical" | vertical |
disabled | 表单级禁用提示；FormControl 会尝试合并到子控件。 | boolean | - |
requiredMark | 必填星号策略。默认 true。 | false | true | "optional" | true |
labelAlign | 标签对齐。默认 right（horizontal 时常见）。 | "left" | "right" | - |
labelWidth | horizontal 时标签宽度；写入 CSS 变量。 | string | number | - |
colon | horizontal 时标签后是否显示冒号。默认 true。 | boolean | true |
另有 288 项原生属性与事件继承自 FormHTMLAttributes / HTMLAttributes，原样透传。
FormContent
主题化内容列。
无自有属性；其余 280 项原生属性继承自 HTMLAttributes。
FormControl
主题化控件关联包装。
无自有属性；其余 3 项原生属性继承自 。
FormDescription
主题化帮助说明。
无自有属性；其余 280 项原生属性继承自 HTMLAttributes。
FormFieldSet
主题化 fieldset。
无自有属性；其余 283 项原生属性继承自 FieldsetHTMLAttributes / HTMLAttributes。
FormGroup
主题化表单项组。
无自有属性；其余 280 项原生属性继承自 HTMLAttributes。
FormItem
主题化表单项。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
orientation | - | "horizontal" | "vertical" | "responsive" | - |
label | - | ReactNode | - |
description | - | ReactNode | - |
error | - | ReactNode | - |
errors | - | FormErrorItem[] | - |
invalid | - | boolean | - |
另有 281 项原生属性与事件继承自 HTMLAttributes，原样透传。
FormLabel
主题化标签。
无自有属性；其余 283 项原生属性继承自 HTMLAttributes / LabelHTMLAttributes。
FormLegend
主题化 legend。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
variant | - | "label" | "legend" | - |
另有 280 项原生属性与事件继承自 HTMLAttributes，原样透传。
FormMessage
主题化错误消息。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
errors | - | FormErrorItem[] | - |
另有 280 项原生属性与事件继承自 HTMLAttributes，原样透传。
FormSeparator
主题化分隔。
无自有属性；其余 280 项原生属性继承自 HTMLAttributes。
FormTitle
主题化标题行。
无自有属性；其余 280 项原生属性继承自 HTMLAttributes。
导出类型：FormContentProps、FormControlProps、FormDescriptionProps、FormErrorItem、FormFieldSetProps、FormGroupProps、FormInstance、FormItemControlState、FormItemOrientation、FormItemProps、FormLabelAlign、FormLabelProps、FormLayout、FormLegendProps、FormMessageProps、FormNamePath、FormProps、FormRequiredMark、FormRule、FormSeparatorProps、FormSize、FormTitleProps、FormValidateError
函数与常量
| 名称 | 说明 | 签名 / 类型 |
|---|---|---|
createFormInstance | 创建独立 FormInstance（不依赖 React）。 | <Values = Record<string, unknown>>(initialValues?: Partial<Values>) => FormInstance<Values> |
FormValidateException | validateFields 拒绝时的聚合错误。 | typeof FormValidateException |
useForm | 命令式表单实例 hook（对齐 antd Form.useForm）。 | <Values = Record<string, unknown>>() => [FormInstance<Values>] |
useFormItem | 重导出 headless 关联 hook。 | () => FormItemControlState |
useFormSize | 读取当前 Form 尺寸。 | () => FormSize |
无障碍
摘自源码 JSDoc。
Form.labelAlign：标签对齐。Form.labelWidth：horizontal 时标签宽度；写入 CSS 变量。