一个 React 表单字段容器，采用 Liquid Glass 标签、说明与校验信息，用于包裹单个表单控件。
Field 为一个 Base UI 表单控件提供可见标签、辅助说明与校验信息。它负责标签和有效性的关联，子控件则保留自己的玻璃表面与交互。
使用 Field 为 Input 提供可见标签、说明与校验信息。已经内置标签的控件，例如 Checkbox、Select、CheckboxGroup、RadioGroup 与 Switch，继续使用自己的 label 属性。多个字段需要共享标题时，请使用 Fieldset。
通过 children 传入控件。Field 会渲染真实的 <label> 并与控件关联，因此输入框不需要再单独添加标签。children 必须是单个 Base UI 控件；原生 <input> 不会自动接入字段上下文。
validate 接收当前值；值有效时返回空，值无效时返回一个字符串或字符串数组。validationMode 决定校验时机：默认 onSubmit，也可使用 onBlur 或 onChange 提前反馈。validationDebounceTime 可以延迟输入过程中的 onChange 校验。
由于子控件是真实的表单元素，required、minLength、pattern、type 等原生约束会自动参与校验。
设置 error 可以显示由外部状态控制的错误信息。字符串会直接渲染为错误信息。error 为真值时会标记字段无效，并在清除前优先于内置校验。错误信息通过 aria-describedby 关联到控件，控件同时会收到 aria-invalid。
将 React 元素传给 error 可以完全接管错误内容。外层消息元素仍持有 id 与 aria-describedby 关联，因此自定义内容依然具备可访问性。
支持 xs / sm / md / lg / xl，默认 md。请为控件传入相同的 size，让标签、信息与控件行保持对齐。
Field 渲染真实的 <label> 并与控件关联。description 与 error 会把各自的 id 注册到控件的 aria-describedby；出现错误时，控件还会带有 aria-invalid。
键盘行为由被包裹的控件负责。请使用 label 而不是占位符作为可访问名称，确保在缩放、翻译与语音控制下仍然有效。分组控件继续使用自己的 label；共享标题请使用 Fieldset。字段禁用时，标签与信息会淡出，控件也会通过共享的字段状态被禁用。表单模式见可访问性指南。
Field
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
children | ReactElement | — | 由字段提供标签与校验的单个 Base UI 控件。必填。 |
label | ReactNode | — | 与控件关联的可见标签。 |
description | ReactNode | — | 控件下方的辅助说明，通过 aria-describedby 关联。 |
error | ReactNode | — | 错误信息。字符串直接渲染；React 元素会替换整个错误内容。为真值时将字段标记为无效。 |
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 标签、信息与间距尺寸。 |
validate | (value, formValues) => string | string[] | null | void | Promise<...> | — | 自定义校验。值无效时返回一条或多条信息。 |
validationMode | "onSubmit" | "onBlur" | "onChange" | "onSubmit" | 字段执行校验的时机。 |
validationDebounceTime | number | 0 | onChange 模式下两次 validate 调用之间的延迟，单位为毫秒。 |
invalid | boolean | — | 由外部状态标记字段无效。 |
disabled | boolean | false | 通过字段禁用控件，并淡化标签与信息。 |
name | string | — | 字段注册的表单字段名。 |
dirty | boolean | — | 由外部状态标记字段已修改。 |
touched | boolean | — | 由外部状态标记字段已触碰。 |
actionsRef | RefObject<Field.Root.Actions | null> | — | 命令式操作。调用 validate 可立即校验字段。 |
className | string | — | 合并到字段根元素的 Tailwind 类名。 |
style | CSSProperties | — | 内联样式，合并到与 className 相同的元素。 |
ui | { root?: ClassValue; label?: ClassValue; error?: ClassValue; description?: ClassValue } | — | 按 data-slot 组织的内部槽位类名。 |
render | ReactElement | ((props, state) => ReactElement) | — | 替换字段根元素。 |
其余 Base UI Field.Root 属性会透传，包括 id。子控件仍可接收自己的属性；required、disabled 与原生约束应在属于该元素时设置到控件上。
| 属性 | 说明 |
|---|---|
data-disabled | 字段禁用时存在。 |
data-valid | 字段有效时存在。 |
data-invalid | 字段无效时存在。 |
data-dirty | 字段值发生变化时存在。 |
data-touched | 字段被触碰后存在。 |
data-filled | 控件有值时存在。 |
data-focused | 控件聚焦时存在。 |
data-slot | 标记内部结构（root、label、error、description）以便样式覆盖。 |
Field 本身没有玻璃表面，而是继承子控件的材质。可以通过共享的 --ui-drop-shadow-label token 调整标签投影，通过 --ui-field-gap、--ui-field-label-size 与 --ui-field-message-size 调整间距和字号，并使用 ui 按 data-slot 覆盖内部槽位。错误信息在浅色主题下使用 text-red-700，在暗色主题下使用 ui-dark:text-red-400；可通过 ui.error 覆盖。自定义 error 节点会直接渲染在 ui.error 内。组件级数值位于 src/theme/field.ts。Token 分层与预设见主题指南。
Field 的标准文本输入框。