文本输入 text-field

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

示例

基础用法

root 持有状态，label 与 input 各自向它取属性；不传 value 即为非受控，组件自己维护值

昵称

带初值

<script setup lang="ts">
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";
</script>

<template>
  <XhTextFieldRoot placeholder="请输入昵称">
    <XhTextFieldLabel>昵称</XhTextFieldLabel>
    <XhTextFieldInput style="inline-size: 200px" />
  </XhTextFieldRoot>

  <XhTextFieldRoot default-value="曦寒">
    <XhTextFieldLabel>带初值</XhTextFieldLabel>
    <XhTextFieldInput style="inline-size: 200px" />
  </XhTextFieldRoot>
</template>

受控

传了 value 就由宿主说了算，组件自己不再改状态；v-model:value 是它的语法糖

昵称

当前：曦寒

<script setup lang="ts">
import { ref } from "vue";
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";

const nickname = ref("曦寒");
</script>

<template>
  <XhTextFieldRoot v-model:value="nickname" placeholder="请输入昵称">
    <XhTextFieldLabel>昵称</XhTextFieldLabel>
    <XhTextFieldInput style="inline-size: 200px" />
  </XhTextFieldRoot>
  <span>当前：{{ nickname || "（空）" }}</span>
  <button type="button" @click="nickname = '曦寒'">重置</button>
</template>

可清空与字数上限

clearable 让清空按钮可用并把 Escape 接管过来，maxLength 同时落成原生 maxlength 与机器侧截断

昵称

2 / 10

<script setup lang="ts">
import {
  XhTextFieldClearTrigger,
  XhTextFieldInput,
  XhTextFieldLabel,
  XhTextFieldRoot,
} from "@xihan-ui/vue";
</script>

<template>
  <XhTextFieldRoot
    v-slot="{ value, atLimit }"
    default-value="曦寒"
    placeholder="最多 10 个字符"
    :max-length="10"
    clearable
  >
    <XhTextFieldLabel>昵称</XhTextFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhTextFieldInput style="inline-size: 200px" />
      <XhTextFieldClearTrigger>✕</XhTextFieldClearTrigger>
    </div>
    <span>{{ value.length }} / 10{{ atLimit ? "（已到上限）" : "" }}</span>
  </XhTextFieldRoot>
</template>

禁用与校验态

disabled 与 readOnly 都改不动值，invalid 只把 aria-invalid 标出来、不拦输入

禁用

只读

校验失败

<script setup lang="ts">
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";
</script>

<template>
  <XhTextFieldRoot default-value="改不动" disabled>
    <XhTextFieldLabel>禁用</XhTextFieldLabel>
    <XhTextFieldInput style="inline-size: 160px" />
  </XhTextFieldRoot>

  <XhTextFieldRoot default-value="只能看" read-only>
    <XhTextFieldLabel>只读</XhTextFieldLabel>
    <XhTextFieldInput style="inline-size: 160px" />
  </XhTextFieldRoot>

  <XhTextFieldRoot default-value="格式不对" invalid>
    <XhTextFieldLabel>校验失败</XhTextFieldLabel>
    <XhTextFieldInput style="inline-size: 160px" />
  </XhTextFieldRoot>
</template>

形态

variant 决定底与描边怎么画：描边、淡色填底、无框；输入框没有实心档

outline

subtle

ghost

<script setup lang="ts">
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";

const variants = ["outline", "subtle", "ghost"] as const;
</script>

<template>
  <!-- 无框档平时只看得见字，把指针移上去或聚焦才浮出边界 -->
  <XhTextFieldRoot
    v-for="v in variants"
    :key="v"
    :variant="v"
    placeholder="请输入内容"
  >
    <XhTextFieldLabel>{{ v }}</XhTextFieldLabel>
    <XhTextFieldInput style="inline-size: 180px" />
  </XhTextFieldRoot>
</template>

语气

tone 决定用哪族颜色，与 variant 正交；这里固定 subtle 形态，语气的底色差别不必聚焦就看得见

brand

neutral

success

warning

danger

info

<script setup lang="ts">
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";

const tones = ["brand", "neutral", "success", "warning", "danger", "info"] as const;
</script>

<template>
  <!-- 正文颜色不归语气管，语气只落在底色、悬停描边与聚焦环上 -->
  <XhTextFieldRoot
    v-for="t in tones"
    :key="t"
    variant="subtle"
    :tone="t"
    placeholder="点进来看聚焦环"
  >
    <XhTextFieldLabel>{{ t }}</XhTextFieldLabel>
    <XhTextFieldInput style="inline-size: 160px" />
  </XhTextFieldRoot>
</template>

尺寸

size 只改高度、内边距与字号，标签与清空按钮一起跟着换档；不写就是缺省档

sm

缺省

lg

<script setup lang="ts">
import {
  XhTextFieldClearTrigger,
  XhTextFieldInput,
  XhTextFieldLabel,
  XhTextFieldRoot,
} from "@xihan-ui/vue";
</script>

<template>
  <!-- 固定 outline 形态，只看档位的差别 -->
  <XhTextFieldRoot variant="outline" size="sm" default-value="小" clearable>
    <XhTextFieldLabel>sm</XhTextFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhTextFieldInput style="inline-size: 160px" />
      <XhTextFieldClearTrigger>✕</XhTextFieldClearTrigger>
    </div>
  </XhTextFieldRoot>

  <XhTextFieldRoot variant="outline" default-value="缺省" clearable>
    <XhTextFieldLabel>缺省</XhTextFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhTextFieldInput style="inline-size: 160px" />
      <XhTextFieldClearTrigger>✕</XhTextFieldClearTrigger>
    </div>
  </XhTextFieldRoot>

  <XhTextFieldRoot variant="outline" size="lg" default-value="大" clearable>
    <XhTextFieldLabel>lg</XhTextFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhTextFieldInput style="inline-size: 160px" />
      <XhTextFieldClearTrigger>✕</XhTextFieldClearTrigger>
    </div>
  </XhTextFieldRoot>
</template>

程序化改值

setValue 直接写值，只受禁用、只读与字数上限约束；clear 走清空意图，canClear 不成立时按兵不动

收货人

（空）

<script setup lang="ts">
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";
</script>

<template>
  <XhTextFieldRoot
    v-slot="{ value, empty, canClear, setValue, clear }"
    placeholder="等着被写入"
    :max-length="12"
    clearable
  >
    <XhTextFieldLabel>收货人</XhTextFieldLabel>
    <XhTextFieldInput style="inline-size: 200px" />
    <div style="display: flex; gap: 8px">
      <button type="button" @click="setValue('曦寒')">写入</button>
      <button type="button" @click="setValue(value + '·')">追加一个点</button>
      <button type="button" :disabled="!canClear" @click="clear()">清空</button>
    </div>
    <span>{{ empty ? "（空）" : value.length + " / 12" }}</span>
  </XhTextFieldRoot>
</template>

原生属性

写在 input 部件上的属性直接落到真正的输入框，自动填充与移动端键盘类型由它们决定

邮箱

手机号

<script setup lang="ts">
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";
</script>

<template>
  <XhTextFieldRoot placeholder="you@example.com">
    <XhTextFieldLabel>邮箱</XhTextFieldLabel>
    <XhTextFieldInput
      style="inline-size: 220px"
      autocomplete="email"
      inputmode="email"
      spellcheck="false"
    />
  </XhTextFieldRoot>

  <XhTextFieldRoot placeholder="11 位手机号" :max-length="11">
    <XhTextFieldLabel>手机号</XhTextFieldLabel>
    <XhTextFieldInput
      style="inline-size: 220px"
      autocomplete="tel"
      inputmode="numeric"
      enterkeyhint="done"
    />
  </XhTextFieldRoot>
</template>

事件

值的变化走 root 的 value-change，聚焦失焦这类原生事件直接写在 input 部件上

留言

还没有事件

<script setup lang="ts">
import { ref } from "vue";
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";

const log = ref<string[]>([]);

// 新的排在最前，只留最近三条
function push(text: string) {
  log.value = [text, ...log.value].slice(0, 3);
}

function onValueChange(details: { value: string }) {
  push("value-change：" + (details.value || "（空）"));
}
</script>

<template>
  <XhTextFieldRoot placeholder="随便敲几个字" clearable @value-change="onValueChange">
    <XhTextFieldLabel>留言</XhTextFieldLabel>
    <XhTextFieldInput
      style="inline-size: 220px"
      @focus="push('focus')"
      @blur="push('blur')"
    />
  </XhTextFieldRoot>

  <ol v-if="log.length" style="margin: 0; padding-inline-start: 20px">
    <li v-for="(item, i) in log" :key="i">{{ item }}</li>
  </ol>
  <span v-else>还没有事件</span>
</template>

框内前后缀

前后缀压在输入框上，输入框自己让出内边距，两者共用同一份边框与底色

金额

¥元

身高

cm

<script setup lang="ts">
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";

// 不吃指针事件，点在前后缀上仍然落到输入框里
const prefix =
  "position: absolute; inset-block: 0; inset-inline-start: 12px; display: flex; align-items: center; color: var(--xh-fg-muted); pointer-events: none";
const suffix =
  "position: absolute; inset-block: 0; inset-inline-end: 12px; display: flex; align-items: center; color: var(--xh-fg-muted); pointer-events: none";
</script>

<template>
  <XhTextFieldRoot placeholder="0.00">
    <XhTextFieldLabel>金额</XhTextFieldLabel>
    <!-- 这层包裹只提供定位参照，边框与底色仍长在输入框自己身上 -->
    <div style="position: relative; display: inline-flex">
      <XhTextFieldInput
        style="inline-size: 200px; padding-inline: 30px 44px"
        inputmode="decimal"
      />
      <span :style="prefix">¥</span>
      <span :style="suffix">元</span>
    </div>
  </XhTextFieldRoot>

  <XhTextFieldRoot placeholder="170">
    <XhTextFieldLabel>身高</XhTextFieldLabel>
    <div style="position: relative; display: inline-flex">
      <XhTextFieldInput
        style="inline-size: 160px; padding-inline-end: 40px"
        inputmode="numeric"
      />
      <span :style="suffix">cm</span>
    </div>
  </XhTextFieldRoot>
</template>

密码与明暗切换

写在 input 部件上的 type 盖过默认的 text，明暗由宿主的一个布尔翻转

密码

<script setup lang="ts">
import { ref } from "vue";
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";

const visible = ref(false);
</script>

<template>
  <XhTextFieldRoot placeholder="请输入密码" :max-length="20">
    <XhTextFieldLabel>密码</XhTextFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhTextFieldInput
        style="inline-size: 200px"
        :type="visible ? 'text' : 'password'"
        autocomplete="current-password"
      />
      <button type="button" :aria-pressed="visible" @click="visible = !visible">
        {{ visible ? "隐藏" : "显示" }}
      </button>
    </div>
  </XhTextFieldRoot>
</template>

限制可输入的字符

beforeinput 直接写在 input 部件上，非法字符进不了框，值与框里的内容始终一致

手机号

账号

<script setup lang="ts">
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";

// 这次要插入的文本：键入与输入法走 data，粘贴与拖入走 dataTransfer
function incoming(event: Event): string {
  const e = event as InputEvent;
  return e.data ?? e.dataTransfer?.getData("text/plain") ?? "";
}

function onlyDigits(event: Event) {
  const text = incoming(event);
  if (text !== "" && /\D/.test(text)) {
    event.preventDefault();
  }
}

function noSpace(event: Event) {
  if (/\s/.test(incoming(event))) {
    event.preventDefault();
  }
}
</script>

<template>
  <XhTextFieldRoot placeholder="只收数字" :max-length="11">
    <XhTextFieldLabel>手机号</XhTextFieldLabel>
    <XhTextFieldInput
      style="inline-size: 200px"
      inputmode="numeric"
      @beforeinput="onlyDigits"
    />
  </XhTextFieldRoot>

  <XhTextFieldRoot placeholder="空格进不来">
    <XhTextFieldLabel>账号</XhTextFieldLabel>
    <XhTextFieldInput style="inline-size: 200px" @beforeinput="noSpace" />
  </XhTextFieldRoot>
</template>

聚焦与选区

input 部件渲染出来就是一个 input，拿到它的节点就能聚焦、全选、把光标挪到末尾

标题

<script setup lang="ts">
import { ref } from "vue";
import { XhTextFieldInput, XhTextFieldLabel, XhTextFieldRoot } from "@xihan-ui/vue";

const input = ref<HTMLInputElement | null>(null);

// 组件只渲染一个 input，实例上的 $el 就是它
function bindInput(instance: unknown): void {
  input.value = (instance as { $el: HTMLInputElement } | null)?.$el ?? null;
}

function selectAll(): void {
  input.value?.focus();
  input.value?.select();
}

function caretToEnd(): void {
  const el = input.value;
  if (!el) return;
  el.focus();
  el.setSelectionRange(el.value.length, el.value.length);
}
</script>

<template>
  <XhTextFieldRoot default-value="曦寒组件库">
    <XhTextFieldLabel>标题</XhTextFieldLabel>
    <XhTextFieldInput :ref="bindInput" style="inline-size: 220px" />
    <div style="display: flex; gap: 8px">
      <button type="button" @click="input?.focus()">聚焦</button>
      <button type="button" @click="selectAll">全选</button>
      <button type="button" @click="caretToEnd">光标移到末尾</button>
      <button type="button" @click="input?.blur()">失焦</button>
    </div>
  </XhTextFieldRoot>
</template>

输入组

圆角槽换成只留外侧的一组值，中缝用负外边距叠掉一条描边，相邻控件拼成一体

站内搜索

域名

https://.com

<script setup lang="ts">
import {
  XhButton,
  XhTextFieldInput,
  XhTextFieldLabel,
  XhTextFieldRoot,
} from "@xihan-ui/vue";

const radius = "var(--xh-shape-control)";

// 输入框只留左侧圆角，右边一格外扣 1px 与按钮共用一条描边
const searchInput = `inline-size: 220px; margin-inline-end: -1px; --xh-text-field-input-radius: ${radius} 0 0 ${radius}`;
const searchButton = `--xh-button-radius: 0 ${radius} ${radius} 0`;

// 前后两块固定文本与输入框同高同描边，圆角各留一侧
const addonBase =
  "display: inline-flex; align-items: center; block-size: var(--xh-control-h-md); padding-inline: 12px; border: 1px solid var(--xh-border-default); background: var(--xh-bg-subtle); color: var(--xh-fg-muted); font-size: var(--xh-text-body-size)";
const addonStart = `${addonBase}; border-radius: ${radius} 0 0 ${radius}`;
const addonEnd = `${addonBase}; border-radius: 0 ${radius} ${radius} 0`;
const middleInput = "inline-size: 160px; margin-inline: -1px; --xh-text-field-input-radius: 0";
</script>

<template>
  <XhTextFieldRoot placeholder="搜索文档" clearable>
    <XhTextFieldLabel>站内搜索</XhTextFieldLabel>
    <div style="display: flex">
      <XhTextFieldInput :style="searchInput" />
      <XhButton :style="searchButton">搜索</XhButton>
    </div>
  </XhTextFieldRoot>

  <XhTextFieldRoot placeholder="xihanfun">
    <XhTextFieldLabel>域名</XhTextFieldLabel>
    <div style="display: flex">
      <span :style="addonStart">https://</span>
      <XhTextFieldInput :style="middleInput" />
      <span :style="addonEnd">.com</span>
    </div>
  </XhTextFieldRoot>
</template>

多行与自动长高

组合式函数把同一份状态交给作者自写的多行部件，高度在每次输入后按内容重新量

留言0 / 120

<script setup lang="ts">
import { computed, ref } from "vue";
import { useTextField } from "@xihan-ui/vue";

const { api } = useTextField({ placeholder: "说点什么", maxLength: 120 });

const rootProps = computed(() => api.value.getRootProps());
const labelProps = computed(() => api.value.getLabelProps());

// type 是给单行输入框的，多行部件不要它
const inputProps = computed(() => {
  const props = { ...(api.value.getInputProps() as Record<string, unknown>) };
  delete props.type;
  return props;
});

const count = computed(() => api.value.value.length);
const atLimit = computed(() => api.value.atLimit);

const height = ref("64px");

function autosize(event: Event) {
  const el = event.target as HTMLTextAreaElement;
  // 先收回自动高度再量，内容变少时才缩得回去
  el.style.blockSize = "auto";
  height.value = `${el.scrollHeight}px`;
}
</script>

<template>
  <div v-bind="rootProps">
    <label v-bind="labelProps">留言</label>
    <textarea
      v-bind="inputProps"
      :style="{
        inlineSize: '260px',
        blockSize: height,
        paddingBlock: '6px',
        lineHeight: '1.6',
        overflow: 'hidden',
        resize: 'none',
      }"
      @input="autosize"
    />
    <span>{{ count }} / 120{{ atLimit ? "（已到上限）" : "" }}</span>
  </div>
</template>

产物

层	值
自定义元素	<xh-text-field>
Vue 组件	XhTextFieldClearTrigger XhTextFieldInput XhTextFieldLabel XhTextFieldRoot
组合式函数	useTextField
状态机	textFieldMachine
皮肤	@xihan-ui/styles/text-field.css

解剖

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

data-scope="text-field"：root · label · input · clear-trigger

Props

属性	类型	必填	说明
value	string		受控值；给了就由宿主说了算，机器不自改。
defaultValue	string		非受控初值。
placeholder	string
disabled	boolean
readOnly	boolean
required	boolean
invalid	boolean
name	string		表单字段名；给了才参与提交。
maxLength	number		字符数上限。同时落成原生 maxlength 与机器侧的截断，两道都要。
clearable	boolean		开启清空能力：清空按钮可用、Escape 接管。关掉时按钮带 hidden 收起。
variant	ControlVariant		形态：outline / subtle / ghost，决定输入框的底与描边怎么画。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定聚焦强调用哪族颜色。
size	Size		尺寸：sm / md / lg，决定输入框与清空按钮的几何档位。
onValueChange	(details: TextFieldValueChangeDetails) => void

状态机

状态：idle

事件：VALUE.SET · VALUE.CLEAR · FORM.RESET

判据：canEdit · canClear

connect API

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

成员	类型	说明
value	string
empty	boolean	值为空串。作者据此显示占位说明一类的东西。
disabled	boolean
readOnly	boolean
invalid	boolean
clearable	boolean
atLimit	boolean	已顶到 maxLength：再敲也进不去，作者据此把字数提示标红。
canClear	boolean	清空按钮此刻是否可用（开了 clearable、可编辑、且有值）。
setValue	(next: string) => void	直接写值，只受 disabled/readOnly 与 maxLength 约束，与 clearable 无关。
clear	() => void	走清空意图，受 canClear 约束；无条件清空请用 setValue('')。
getRootProps	() => T['element']
getLabelProps	() => T['label']
getInputProps	() => T['input']
getClearTriggerProps	() => T['button']

键盘

规格出处：W3C APG

按键	生效条件	行为
Escape	focus in input, clearable 且值非空, not disabled/readOnly	清空值；三个条件缺一即不接管该键，交回给外层与浏览器