表单字段 field

数据录入组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

控件由自己写，Field 只把属性并上去：标题的 for、控件的 id 与描述链（aria-describedby）自动对齐

邮箱

用于接收账单与安全提醒

<script setup lang="ts">
import { XhFieldControl, XhFieldDescription, XhFieldLabel, XhFieldRoot } from "@xihan-ui/vue";
</script>

<template>
  <XhFieldRoot style="inline-size: 280px;">
    <XhFieldLabel>邮箱</XhFieldLabel>
    <XhFieldControl>
      <input type="email" placeholder="you@example.com" />
    </XhFieldControl>
    <XhFieldDescription>用于接收账单与安全提醒</XhFieldDescription>
  </XhFieldRoot>
</template>

无效与必填

invalid 一翻，错误文案接入描述链并显出，控件上同时落 aria-invalid；required 只落 aria-required，校验仍归宿主

邮箱

用于接收账单与安全提醒

邮箱格式不正确

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhFieldControl,
  XhFieldDescription,
  XhFieldErrorText,
  XhFieldLabel,
  XhFieldRoot,
} from "@xihan-ui/vue";

const email = ref("zhaifanhua");
// 无效与否由宿主判定，Field 只负责把这个结论铺成属性
const invalid = computed(() => email.value !== "" && !email.value.includes("@"));
</script>

<template>
  <XhFieldRoot :invalid="invalid" required style="inline-size: 280px;">
    <XhFieldLabel>邮箱</XhFieldLabel>
    <XhFieldControl>
      <input v-model="email" type="email" placeholder="you@example.com" />
    </XhFieldControl>
    <XhFieldDescription>用于接收账单与安全提醒</XhFieldDescription>
    <!-- 错误文案带 role=alert，翻转的那一刻读屏立即播报 -->
    <XhFieldErrorText>邮箱格式不正确</XhFieldErrorText>
  </XhFieldRoot>
</template>

禁用

Field 的 disabled 只把 data-disabled 铺到各部件上；真正改不动还得在自己的控件上落原生 disabled

登录账号

账号创建后不可更改

<script setup lang="ts">
import { XhFieldControl, XhFieldDescription, XhFieldLabel, XhFieldRoot } from "@xihan-ui/vue";
</script>

<template>
  <XhFieldRoot disabled style="inline-size: 280px;">
    <XhFieldLabel>登录账号</XhFieldLabel>
    <XhFieldControl>
      <input value="zhaifanhua" disabled />
    </XhFieldControl>
    <XhFieldDescription>账号创建后不可更改</XhFieldDescription>
  </XhFieldRoot>
</template>

标签左置

各部件都是独立节点，把根节点改成两列网格就能把标题挪到控件左边，说明与错误文案跟着对齐到控件那一列

端口

留空表示使用默认端口

端口只能是数字

<script setup lang="ts">
import {
  XhFieldControl,
  XhFieldDescription,
  XhFieldErrorText,
  XhFieldLabel,
  XhFieldRoot,
} from "@xihan-ui/vue";
</script>

<template>
  <!-- 第一列放标题，第二列放控件、说明与错误文案 -->
  <XhFieldRoot
    invalid
    style="display: grid; grid-template-columns: 72px 1fr; align-items: center; column-gap: 12px; row-gap: 4px; inline-size: 360px;"
  >
    <XhFieldLabel>端口</XhFieldLabel>
    <XhFieldControl>
      <input value="abc" />
    </XhFieldControl>
    <XhFieldDescription style="grid-column-start: 2;">留空表示使用默认端口</XhFieldDescription>
    <XhFieldErrorText style="grid-column-start: 2;">端口只能是数字</XhFieldErrorText>
  </XhFieldRoot>
</template>

字段横排

一行里摆多个字段：每个字段自成一块，谁跟谁排一行是外层容器的事

姓名

年龄

电话

<script setup lang="ts">
import { XhFieldControl, XhFieldLabel, XhFieldRoot } from "@xihan-ui/vue";
</script>

<template>
  <!-- 外层给一行的排布，宽度逐个字段自己定 -->
  <div style="display: flex; flex-wrap: wrap; align-items: flex-end; gap: 12px;">
    <XhFieldRoot style="inline-size: 160px;">
      <XhFieldLabel>姓名</XhFieldLabel>
      <XhFieldControl>
        <input placeholder="请输入姓名" />
      </XhFieldControl>
    </XhFieldRoot>

    <XhFieldRoot style="inline-size: 96px;">
      <XhFieldLabel>年龄</XhFieldLabel>
      <XhFieldControl>
        <input type="number" placeholder="18" />
      </XhFieldControl>
    </XhFieldRoot>

    <XhFieldRoot style="inline-size: 180px;">
      <XhFieldLabel>电话</XhFieldLabel>
      <XhFieldControl>
        <input type="tel" placeholder="请输入电话" />
      </XhFieldControl>
    </XhFieldRoot>
  </div>
</template>

提示、警告与错误

三档语气各归各的部件：提示与警告都写在描述里，控件的 aria-invalid 保持 false；只有真出错才翻 invalid、错误文案才接进描述链

项目名

创建之后还能改

实例规格

这个规格跑构建会偏紧，仍然可以保存

端口

可用范围 1 到 65535

端口超出可用范围

<script setup lang="ts">
import {
  XhFieldControl,
  XhFieldDescription,
  XhFieldErrorText,
  XhFieldLabel,
  XhFieldRoot,
} from "@xihan-ui/vue";

// 警告档只换配色：边框取语气层的强调色，描述取语气层的文字色
const warningStyle = {
  "--xh-field-control-border": "var(--xh-_tone-soft)",
  "--xh-field-description-fg": "var(--xh-_tone-fg)",
};
</script>

<template>
  <div style="display: grid; gap: 16px; inline-size: 280px;">
    <XhFieldRoot>
      <XhFieldLabel>项目名</XhFieldLabel>
      <XhFieldControl>
        <input value="xihan-ui" />
      </XhFieldControl>
      <XhFieldDescription>创建之后还能改</XhFieldDescription>
    </XhFieldRoot>

    <!-- 警告：值可疑但不算错，invalid 不翻，读屏经描述链念出这一句 -->
    <XhFieldRoot data-tone="warning" :style="warningStyle">
      <XhFieldLabel>实例规格</XhFieldLabel>
      <XhFieldControl>
        <input value="1 核 1G" />
      </XhFieldControl>
      <XhFieldDescription>这个规格跑构建会偏紧，仍然可以保存</XhFieldDescription>
    </XhFieldRoot>

    <XhFieldRoot invalid>
      <XhFieldLabel>端口</XhFieldLabel>
      <XhFieldControl>
        <input value="70000" />
      </XhFieldControl>
      <XhFieldDescription>可用范围 1 到 65535</XhFieldDescription>
      <XhFieldErrorText>端口超出可用范围</XhFieldErrorText>
    </XhFieldRoot>
  </div>
</template>

产物

层	值
自定义元素	<xh-field>
Vue 组件	XhFieldControl XhFieldDescription XhFieldErrorText XhFieldLabel XhFieldRoot
组合式函数	useField
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/field.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="field"：root · label · control · description · error-text

Props

属性	类型	必填	说明
controlId	string		控件 id；作者接管时以它为准。
disabled	boolean
invalid	boolean		校验失败态：控件上 aria-invalid=true，错误文案接入描述链并显出。
required	boolean		必填：控件上 aria-required=true。

connect API

useField 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
invalid	boolean
required	boolean
disabled	boolean
controlId	string	控件实际使用的 id，label 的 for 与它一致。
getRootProps	() => T['element']
getLabelProps	() => T['label']
getControlProps	() => T['element']	控件本身由作者渲染，这里只产出要合并上去的属性。
getDescriptionProps	() => T['element']
getErrorTextProps	() => T['element']

键盘

规格出处：W3C APG

无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。