Field 表单字段
为表单控件提供标签、说明、错误信息和状态关联。
用法
为控件添加标签与说明
用于接收账单与安全提醒
组件结构
加粗的是必需部件。
data-scope="field"：root · label · control · description · error-text
示例
必填与校验
显示字段错误
用于接收账单与安全提醒
邮箱格式不正确
禁用
禁止编辑字段
账号创建后不可更改
标签左置
将标签放在控件左侧
留空表示使用默认端口
端口只能是数字
设计指引
何时使用
- 表单控件需要可见标签、说明或错误信息。
- 需要统一管理必填、禁用、只读和无效状态。
何时不用
- 不需要可见标签的紧凑控件直接提供
aria-label。 - 需要管理整张表单的值和提交时，使用表单。
特性
- 自动关联标签、说明、错误信息与控件。
disabled、readOnly、invalid和required可传递给内部控件。- 说明和错误信息可以同时显示。
- 控件的名字链与描述链只引用实际渲染了的标题、说明与错误文案：没写的部件、读不出一句话的说明（没有文字，或只有对读屏隐藏的内容，判断同
hasNamingContent）不留 id，引用不会落空；部件后补进来、说明补上内容时跟着接上。 FieldControl默认将属性合并到唯一子节点。- 点标题把焦点交给控件；控件是弹出式触发钮（选择器、日期选择器等）时只聚焦、不开合，与原生 select 一致，浮层展开时点标题即收起。
- 库内控件直接放进字段时，点标题按文档顺序找第一个此刻落得了焦的接线节点；被藏起的跳过（日期、时间选择器有值且指针落在盒上时清空钮顶替日历钮，触屏上有值即顶替），都落不了焦时交给控件里第一个可 Tab 的节点。
- 字段的标签、说明、状态与控件 id 沿组件树（Web Components 沿 DOM 祖先链）交给子树里的库内控件。组合控件内嵌的输入（图标选择器里的搜索框、筛选框）不该被读成外层字段的名字时，包进
XhFieldBoundary（Web Components 为display: contents的<xh-field-boundary>）：边界后面的控件不再继承外层字段与表单字段组。浮层内容经 Portal 搬到落点后已自动断开，放在弹出层、对话框里的输入框不归外层字段管。 - 字段族控件（文本框、下拉、日期、数字等）放进字段即铺满字段宽，跟着表单的列走，不必再在根上写
inline-size: 100%；单独摆放时仍是 16rem 缺省宽。横排一行流（layout="inline"）的表单里字段按内容收，那一档仍取缺省宽。 - 不写结构时按标准结构铺（Vue 不写默认插槽、React 不给 children、Web Components 不写部件或只写
root），三端出自同一个结构函数：次序是标题、控件、说明、错误文案。控件原样放在标题之后，外面不包部件（Vue 是control插槽，React 是control属性，Web Components 是宿主直接子节点上的slot="control"）；标题、说明、错误文案取label、description、errorText的文字，给了才铺，也可由同名插槽接管。errorText给空串时照样铺错误文案并常挂，表单里由字段自取该项的错误。原生控件要标成control部件时手写结构。
组合
- 包裹任何单一控件：文本字段、选择器、开关等会把字段状态接到实际控件上。
- 组类控件同样直接放进来：单选组、复选框组、色板选择、切换按钮组、评分、滑块、分格输入把字段的标题并进组名（滑块落在拇指上）、说明进描述链；校验、必填与只读按字段状态由组件自己投影。
- Web Components 的库内控件放进
<xh-field>时同样如此：提示与错误由字段的description、error-text接到控件真正可聚焦的部件（输入框、触发钮、组根、拇指）上，字段标题并进它的名字链；控件移出字段或字段断开时收回。库内控件直接放进字段即可，不必另写control部件。控件自己也带描述（密码框的大写锁定提示）时两段都念，字段的在前。 - 多个字段一起提交与校验时放入表单；一组相关字段使用字段集分区。
最佳实践
- 使用持续可见的明确标签。
- 把
control标在真控件（<input>、<textarea>、<select>）上：描边式视觉盒按这个节点画，包一层再放真控件会在真控件外再套一层壳。 - 说明文字简短且补充必要信息。
- 错误信息应说明如何修正。
反模式
- 用占位符代替标签。
- 同时手写并覆盖组件生成的 ARIA 关联。
- 给
control再写一套边框、底色与阴影：静息描边、悬停、聚焦、无效、只读与禁用各态由字段外壳统一给。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-field> |
| Vue 组件 | XhFieldBoundary XhFieldControl XhFieldDescription XhFieldErrorText XhFieldLabel XhFieldRoot |
| 组合式函数 | useField |
| 状态机 | 无，connect 直接由 props 算属性 |
| 皮肤 | @xihan-ui/styles/field.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
controlId | string | 控件 id；作者接管时以它为准。 | |
disabled | boolean | ||
invalid | boolean | 校验失败态：控件上 aria-invalid=true，错误文案接入描述链并显示。 | |
parts | FieldRenderedParts | 作者实际渲染了哪些部件，由适配器统计；省略即按都在场处理（服务端直出与挂载前）。 不在场的部件不进控件的名字链与描述链：指向不存在的 id 会被判为无效引用。 description 渲染了但读不出一句话（判断同 hasNamingContent）也按不在场处理。 control 不在场（库内控件直接放进字段）时 label 不写 for，点 label 由字段聚焦控件的焦点宿主。 | |
readOnly | boolean | 只读：控件上 aria-readonly=true。与 disabled 不同，只读仍可聚焦、仍参与提交。 | |
required | boolean | 必填：控件上 aria-required=true。 |
插槽
仅列出带载荷的插槽。
| Vue 组件 | 插槽 | 载荷 | 说明 |
|---|---|---|---|
XhFieldControl | default | FieldControlSlotProps | |
XhFieldRoot | default | — | |
XhFieldRoot | label | — | |
XhFieldRoot | control | — | |
XhFieldRoot | description | — | |
XhFieldRoot | errorText | — |
React 适配器 props
只列各组件自己声明的那些：继承自 ComponentPropsWithRef 的 DOM 属性不在其中，根组件上与上面 Props 表同名的也不重复列。Vue 的对应物是上面的插槽表。
| React 组件 | 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
XhFieldBoundary | children | ReactNode | ||
XhFieldControl | asChild | boolean | 把接线属性合并到唯一的子节点上，默认开启。 子节点是薄封装（根不是可聚焦元素）时关闭它：属性只经函数式 children 交出， 由封装内部调用 useFieldControl 绑定到真实控件上。 | |
XhFieldControl | children | SlotChildren<FieldControlSlotProps> | ||
XhFieldRoot | label | ReactNode | 标题。不给 children 时铺 label 部件。 | |
XhFieldRoot | control | ReactNode | 字段里的控件。不给 children 时原样放在标题之后，外面不包部件。 | |
XhFieldRoot | description | ReactNode | 说明。不给 children 时铺说明部件。 | |
XhFieldRoot | errorText | ReactNode | 错误文案。不给 children 时给了（空串也算）就铺错误文案部件，空串时在表单里自取该项的错误。 |
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
invalid | boolean | |
required | boolean | |
disabled | boolean | |
readOnly | boolean | |
controlId | string | 控件实际使用的 id，label 的 for 与它一致。 |
labelId | string | 标签节点的 id。复合控件把它并入自身的名字链，字段的标签才能被朗读。 |
getRootProps | () => T['element'] | |
getLabelProps | () => T['label'] | |
getControlProps | () => T['element'] | 控件本身由作者渲染，这里只产出需要合并的属性。 |
getDescriptionProps | () => T['element'] | |
getErrorTextProps | () => T['element'] |
无障碍
键盘
规格出处：W3C APG
无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。
ARIA
以下属性由 connect 生成。
| 部件 | 属性 | 值 |
|---|---|---|
control | aria-describedby | [ rendered?.description === false ? null : ids.descri… |
control | aria-invalid | 'true' | 'false' |
control | aria-labelledby | undefined | label 部件的 id |
control | aria-readonly | 'true' | 'false' |
control | aria-required | 'true' | 'false' |
error-text | aria-atomic | 'true' |
error-text | aria-live | 'polite' |
error-text | role | 'status' |
样式参考
皮肤
@xihan-ui/styles/field.css 按 [data-scope="field"][data-part="root"] 部件选择器书写，发布产物以挂载类 .xh-scope-field 代替其中的 data-scope（特异性相同），位于 xihan.components 层。覆盖样式使用 xihan.overrides，部件选择器照常可用。
数据属性
由 connect 生成；条件不成立时不输出无值属性。
| 部件 | 属性 | 值 |
|---|---|---|
root | data-disabled | ''（条件成立时才出现） |
root | data-invalid | ''（条件成立时才出现） |
root | data-readonly | ''（条件成立时才出现） |
root | data-required | ''（条件成立时才出现） |
label | data-disabled | ''（条件成立时才出现） |
label | data-invalid | ''（条件成立时才出现） |
label | data-readonly | ''（条件成立时才出现） |
label | data-required | ''（条件成立时才出现） |
control | data-disabled | ''（条件成立时才出现） |
control | data-invalid | ''（条件成立时才出现） |
control | data-readonly | ''（条件成立时才出现） |
control | data-variant | 'outline' |
control | data-xh-field-chrome | '' |
control | data-xh-field-size | 'md' |
description | data-disabled | ''（条件成立时才出现） |
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-field-border-invalid | jumper | border-color | user-invalid | --xh-_field-variant-border-invalid | field 的 jumper 部件 border-color 覆盖槽。 |
--xh-field-control-bg | control | background-color | xh-field-chrome | --xh-_field-variant-bg-rest | field 的 control 部件 background-color 覆盖槽。 |
--xh-field-control-bg-disabled | control | background-color | disabledxh-field-chrome | --xh-_field-variant-bg-disabled | field 的 control 部件 background-color 覆盖槽。 |
--xh-field-control-bg-hover | control | background-color | disabledhoverinvalidloadingnot(:focus-within)not([data-disabled])not([data-invalid])not([data-loading])not([data-readonly])readonlyxh-field-chrome | --xh-_field-variant-bg-hover | field 的 control 部件 background-color 覆盖槽。 |
--xh-field-control-bg-readonly | control | background-color | readonlyxh-field-chrome | --xh-_field-variant-bg-read-only | field 的 control 部件 background-color 覆盖槽。 |
--xh-field-control-border | control | border | xh-field-chrome | --xh-_field-variant-border-rest | field 的 control 部件 border 覆盖槽。 |
--xh-field-control-border-focus | control | border-colorbox-shadow | disabledfocus-withinnot([data-disabled])xh-field-chrome | --xh-_field-variant-border-focus | field 的 control 部件 border-color、box-shadow 覆盖槽。 |
--xh-field-control-border-hover | control | border-color | disabledhoverinvalidloadingnot(:focus-within)not([data-disabled])not([data-invalid])not([data-loading])not([data-readonly])readonlyxh-field-chrome | --xh-_field-variant-border-hover | field 的 control 部件 border-color 覆盖槽。 |
--xh-field-control-border-invalid | control | border-color | invalidxh-field-chrome | --xh-_field-variant-border-invalid | field 的 control 部件 border-color 覆盖槽。 |
--xh-field-control-fg | control | color | xh-field-chrome | --xh-fg-default | field 的 control 部件 color 覆盖槽。 |
--xh-field-control-font-size | control | font-size | default | --xh-text-body-size | field 的 control 部件 font-size 覆盖槽。 |
--xh-field-control-h | controllabelroot | block-sizemin-block-sizepadding-block | has([data-xh-field-input][data-xh-field-layout='multi-tag'])has([data-xh-field-input][data-xh-field-layout='single-line'])has([data-xh-field-input][data-xh-field-layout='textarea'])layout=horizontalxh-field-chromexh-field-inputxh-field-layout=multi-tagxh-field-layout=single-linexh-field-layout=textarea | --xh-_field-size-control-height--xh-control-h-md | field 的 control、label、root 部件 block-size、min-block-size、padding-block 覆盖槽。 |
--xh-field-control-px | control | padding-inline | xh-field-chrome | --xh-_field-size-padding-inline | field 的 control 部件 padding-inline 覆盖槽。 |
--xh-field-control-radius | control | border-radius | default | --xh-shape-control | field 的 control 部件 border-radius 覆盖槽。 |
--xh-field-control-shadow | control | box-shadow | xh-field-chrome | none | field 的 control 部件 box-shadow 覆盖槽。 |
--xh-field-description-fg | description | color | default | --xh-fg-subtle | field 的 description 部件 color 覆盖槽。 |
--xh-field-description-fg-disabled | description | color | disabled | --xh-fg-subtle | field 的 description 部件 color 覆盖槽。 |
--xh-field-description-font-size | description | font-size | default | --xh-text-caption-size | field 的 description 部件 font-size 覆盖槽。 |
--xh-field-error-fg | error-text | color | default | --xh-fg-danger | field 的 error-text 部件 color 覆盖槽。 |
--xh-field-error-font-size | error-textroot | block-sizefont-sizemargin-block-endpadding-block-end | defaulthas(> [data-scope='field'][data-part='error-text'][hidden])not(:has(> [data-scope='field'][data-part='description']:not([hidden]) | --xh-text-caption-size | field 的 error-text、root 部件 block-size、font-size、margin-block-end、padding-block-end 覆盖槽。 |
--xh-field-gap | labelroot | gapmargin-block-end | default | --xh-space-0 | field 的 label、root 部件 gap、margin-block-end 覆盖槽。 |
--xh-field-label-fg | label | color | default | --xh-fg-muted | field 的 label 部件 color 覆盖槽。 |
--xh-field-label-fg-disabled | label | color | disabled | --xh-fg-muted | field 的 label 部件 color 覆盖槽。 |
--xh-field-label-fg-invalid | label | color | invalid | --xh-fg-danger | field 的 label 部件 color 覆盖槽。 |
--xh-field-label-font-size | labelroot | font-sizepadding-block | defaultlayout=horizontal | --xh-text-label-size | field 的 label、root 部件 font-size、padding-block 覆盖槽。 |
--xh-field-label-font-weight | label | font-weight | default | --xh-text-label-weight | field 的 label 部件 font-weight 覆盖槽。 |
--xh-field-label-gap | root | column-gap | layout=horizontal | --xh-space-4 | field 的 root 部件 column-gap 覆盖槽。 |
--xh-field-label-gap-block | label | margin-block-end | default | --xh-space-2 | field 的 label 部件 margin-block-end 覆盖槽。 |
--xh-field-label-leading | labelroot | line-heightpadding-block | layout=horizontal | --xh-leading-normal | field 的 label、root 部件 line-height、padding-block 覆盖槽。 |
--xh-field-label-star | label | color | required | --xh-fg-danger | field 的 label 部件 color 覆盖槽。 |
动效
动效角色：状态 · 出现（见动效规范）。
color · opacity · visibility 走 transition 过渡。时长与缓动读动效令牌，改令牌即改全局节奏。
系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。
RTL
皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像。