数字输入 number-field

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

示例

基础用法

加减按钮与输入框共用一份状态；值是原始输入串，不传 value 即为非受控

数量

<script setup lang="ts">
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";
</script>

<template>
  <XhNumberFieldRoot default-value="1">
    <XhNumberFieldLabel>数量</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
      <XhNumberFieldInput style="inline-size: 80px; text-align: center" />
      <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
    </div>
  </XhNumberFieldRoot>
</template>

区间与步长

方向键走 step，PageUp 与 PageDown 走 largeStep，Home 与 End 取端点；贴到边界时对应按钮转灰

数量（0 – 20，每档 2）

数值：10 · 可加：是 · 可减：是

<script setup lang="ts">
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";
</script>

<template>
  <XhNumberFieldRoot
    v-slot="{ valueAsNumber, canIncrement, canDecrement }"
    default-value="10"
    :min="0"
    :max="20"
    :step="2"
    :large-step="10"
  >
    <XhNumberFieldLabel>数量（0 – 20，每档 2）</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
      <XhNumberFieldInput style="inline-size: 80px; text-align: center" />
      <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
    </div>
    <span>
      数值：{{ Number.isNaN(valueAsNumber) ? "（空）" : valueAsNumber }} ·
      可加：{{ canIncrement ? "是" : "否" }} · 可减：{{ canDecrement ? "是" : "否" }}
    </span>
  </XhNumberFieldRoot>
</template>

受控

传了 value 就由宿主说了算；value-change 除了原始串还带一份 valueAsNumber

数量

输入串：3 · 数值：3

<script setup lang="ts">
import { ref } from "vue";
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";

const qty = ref("3");
const asNumber = ref(3);
</script>

<template>
  <XhNumberFieldRoot
    v-model:value="qty"
    :min="0"
    :max="99"
    @value-change="asNumber = $event.valueAsNumber"
  >
    <XhNumberFieldLabel>数量</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
      <XhNumberFieldInput style="inline-size: 80px; text-align: center" />
      <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
    </div>
  </XhNumberFieldRoot>
  <span>输入串：{{ qty === "" ? "（空）" : qty }} · 数值：{{ asNumber }}</span>
</template>

禁用与只读

两者都改不动值，禁用还会把加减按钮一并关掉、值也不再随表单提交

禁用

只读

<script setup lang="ts">
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";
</script>

<template>
  <XhNumberFieldRoot default-value="5" disabled>
    <XhNumberFieldLabel>禁用</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
      <XhNumberFieldInput style="inline-size: 80px; text-align: center" />
      <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
    </div>
  </XhNumberFieldRoot>

  <XhNumberFieldRoot default-value="5" read-only>
    <XhNumberFieldLabel>只读</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
      <XhNumberFieldInput style="inline-size: 80px; text-align: center" />
      <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
    </div>
  </XhNumberFieldRoot>
</template>

形态

variant 只改皮肤怎么用颜色，加减与键盘行为三档完全一致

outline

subtle

ghost

<script setup lang="ts">
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";

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

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <XhNumberFieldRoot v-for="v in variants" :key="v" :variant="v" default-value="1">
      <XhNumberFieldLabel>{{ v }}</XhNumberFieldLabel>
      <div style="display: flex; gap: 4px">
        <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
        <XhNumberFieldInput style="inline-size: 72px; text-align: center" />
        <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
      </div>
    </XhNumberFieldRoot>
  </div>
</template>

语气

tone 决定用哪族颜色，与 variant 正交；这里固定 outline 只看语气的差别

brand

neutral

success

warning

danger

info

<script setup lang="ts">
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";

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

<template>
  <div style="display: flex; flex-wrap: wrap; gap: 16px">
    <XhNumberFieldRoot v-for="t in tones" :key="t" variant="outline" :tone="t" default-value="1">
      <XhNumberFieldLabel>{{ t }}</XhNumberFieldLabel>
      <div style="display: flex; gap: 4px">
        <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
        <XhNumberFieldInput style="inline-size: 72px; text-align: center" />
        <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
      </div>
    </XhNumberFieldRoot>
  </div>
</template>

尺寸

输入框高度与加减按钮一起换档，不传 size 即默认档

小

默认

大

<script setup lang="ts">
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";

// 中间一档不写 size，用 undefined 表达
const sizes = [
  { size: "sm", label: "小" },
  { size: undefined, label: "默认" },
  { size: "lg", label: "大" },
] as const;
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; align-items: flex-end; gap: 16px">
    <XhNumberFieldRoot v-for="s in sizes" :key="s.label" :size="s.size" default-value="1">
      <XhNumberFieldLabel>{{ s.label }}</XhNumberFieldLabel>
      <div style="display: flex; gap: 4px">
        <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
        <XhNumberFieldInput style="inline-size: 72px; text-align: center" />
        <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
      </div>
    </XhNumberFieldRoot>
  </div>
</template>

只用输入框

加减钮是可选部件，不渲染它照样能改值：方向键走 step，PageUp 与 PageDown 走 largeStep

音量（0 – 100，每档 5）点进框里按上下键：60

<script setup lang="ts">
import { XhNumberFieldInput, XhNumberFieldLabel, XhNumberFieldRoot } from "@xihan-ui/vue";
</script>

<template>
  <XhNumberFieldRoot
    v-slot="{ value }"
    default-value="60"
    :min="0"
    :max="100"
    :step="5"
    :large-step="25"
  >
    <XhNumberFieldLabel>音量（0 – 100，每档 5）</XhNumberFieldLabel>
    <XhNumberFieldInput style="inline-size: 96px; text-align: center" />
    <span>点进框里按上下键：{{ value === "" ? "（空）" : value }}</span>
  </XhNumberFieldRoot>
</template>

加减钮排布

两个触发器摆在哪儿由作者写模板决定，钮里放什么字符也一样；行为不随位置变

分列两端

并到右侧

<script setup lang="ts">
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";
</script>

<template>
  <XhNumberFieldRoot default-value="1" :min="0" :max="9">
    <XhNumberFieldLabel>分列两端</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
      <XhNumberFieldInput style="inline-size: 80px; text-align: center" />
      <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
    </div>
  </XhNumberFieldRoot>

  <XhNumberFieldRoot default-value="1" :min="0" :max="9">
    <XhNumberFieldLabel>并到右侧</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldInput style="inline-size: 80px; text-align: center" />
      <XhNumberFieldDecrementTrigger>▾</XhNumberFieldDecrementTrigger>
      <XhNumberFieldIncrementTrigger>▴</XhNumberFieldIncrementTrigger>
    </div>
  </XhNumberFieldRoot>
</template>

校验态

invalid 由宿主自己判定，不必挂在表单上；标出来之后值照样能改、加减钮照样能按

购买数量

库存只有 5 件

<script setup lang="ts">
import { ref } from "vue";
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";

const stock = 5;
const qty = ref(8);

function onValueChange(details: { valueAsNumber: number }) {
  qty.value = details.valueAsNumber;
}
</script>

<template>
  <XhNumberFieldRoot
    default-value="8"
    :min="1"
    :max="99"
    :invalid="qty > stock"
    @value-change="onValueChange"
  >
    <XhNumberFieldLabel>购买数量</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
      <XhNumberFieldInput style="inline-size: 80px; text-align: center" />
      <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
    </div>
    <span>{{ qty > stock ? "库存只有 " + stock + " 件" : "库存充足" }}</span>
  </XhNumberFieldRoot>
</template>

框内单位与货币符号

前后缀压在输入框上，输入框自己让出内边距；加减钮照旧摆在包裹层里

单价

¥元

重量

g

<script setup lang="ts">
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";

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

<template>
  <XhNumberFieldRoot default-value="99" :min="0" :max="9999">
    <XhNumberFieldLabel>单价</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
      <!-- 这层包裹只提供定位参照，边框与底色仍长在输入框自己身上 -->
      <div style="position: relative; display: inline-flex">
        <XhNumberFieldInput
          style="inline-size: 120px; padding-inline: 26px 38px; text-align: center"
        />
        <span :style="prefix">¥</span>
        <span :style="suffix">元</span>
      </div>
      <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
    </div>
  </XhNumberFieldRoot>

  <XhNumberFieldRoot default-value="500" :min="0" :max="5000" :step="50">
    <XhNumberFieldLabel>重量</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
      <div style="position: relative; display: inline-flex">
        <XhNumberFieldInput
          style="inline-size: 110px; padding-inline-end: 32px; text-align: center"
        />
        <span :style="suffix">g</span>
      </div>
      <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
    </div>
  </XhNumberFieldRoot>
</template>

固定小数位

步进本身带定点规整，宿主在离开输入框与松开加减钮时把值补齐到两位小数

单价（每档 0.1）

当前：12.50

<script setup lang="ts">
import { ref } from "vue";
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";

const price = ref("12.50");

// 补齐两位小数；空值与非法值一律留空
function pad() {
  const n = Number(price.value);
  price.value = price.value === "" || !Number.isFinite(n) ? "" : n.toFixed(2);
}
</script>

<template>
  <XhNumberFieldRoot v-model:value="price" :min="0" :max="999" :step="0.1">
    <XhNumberFieldLabel>单价（每档 0.1）</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldDecrementTrigger @pointerup="pad">−</XhNumberFieldDecrementTrigger>
      <XhNumberFieldInput style="inline-size: 96px; text-align: center" @blur="pad" />
      <XhNumberFieldIncrementTrigger @pointerup="pad">+</XhNumberFieldIncrementTrigger>
    </div>
    <span>当前：{{ price || "（空）" }}</span>
  </XhNumberFieldRoot>
</template>

提交时机

输入途中只动草稿，失焦或回车才把值交给业务模型；不合法就退回上一次提交的值

数量

草稿：3 · 已提交：3

<script setup lang="ts">
import { ref } from "vue";
import {
  XhNumberFieldDecrementTrigger,
  XhNumberFieldIncrementTrigger,
  XhNumberFieldInput,
  XhNumberFieldLabel,
  XhNumberFieldRoot,
} from "@xihan-ui/vue";

// 草稿绑在组件上，模型只在提交那一刻更新
const draft = ref("3");
const model = ref(3);

function commit() {
  const n = Number(draft.value);
  if (draft.value === "" || !Number.isFinite(n)) {
    draft.value = String(model.value);
    return;
  }
  model.value = n;
  draft.value = String(n);
}
</script>

<template>
  <XhNumberFieldRoot v-model:value="draft" :min="1" :max="99">
    <XhNumberFieldLabel>数量</XhNumberFieldLabel>
    <div style="display: flex; gap: 4px">
      <XhNumberFieldDecrementTrigger>−</XhNumberFieldDecrementTrigger>
      <XhNumberFieldInput
        style="inline-size: 80px; text-align: center"
        @blur="commit"
        @keydown.enter="commit"
      />
      <XhNumberFieldIncrementTrigger>+</XhNumberFieldIncrementTrigger>
    </div>
    <span>草稿：{{ draft || "（空）" }} · 已提交：{{ model }}</span>
  </XhNumberFieldRoot>
</template>

产物

层	值
自定义元素	<xh-number-field>
Vue 组件	XhNumberFieldDecrementTrigger XhNumberFieldIncrementTrigger XhNumberFieldInput XhNumberFieldLabel XhNumberFieldRoot
组合式函数	useNumberField
状态机	numberFieldMachine
皮肤	@xihan-ui/styles/number-field.css

解剖

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

data-scope="number-field"：root · label · input · increment-trigger · decrement-trigger

Props

属性	类型	必填	说明
value	string
defaultValue	string
min	number
max	number
step	number		方向键与加减按钮的步长，默认 1。
largeStep	number		PageUp / PageDown 的步长，默认 10 倍 step。
disabled	boolean
readOnly	boolean
required	boolean
invalid	boolean
name	string		表单字段名；给了才参与提交。
changeDelay	number		按住加减按钮多久开始连发，默认 300ms。
changeInterval	number		连发间隔，默认 50ms。
variant	ControlVariant		形态：outline / subtle / ghost，决定输入框与加减钮的底与描边怎么画。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定聚焦强调用哪族颜色。
size	Size		尺寸：sm / md / lg，决定输入框与加减钮的几何档位。
onValueChange	(details: NumberFieldValueChangeDetails) => void

状态机

状态：idle · spinning

事件：VALUE.SET · VALUE.STEP · VALUE.TO_MIN · VALUE.TO_MAX · INPUT.BLUR · PRESS.START · PRESS.END · after.changeInterval · FORM.RESET

判据：canStep

connect API

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

成员	类型	说明
value	string
valueAsNumber	number
empty	boolean	值为空或非法。
disabled	boolean
readOnly	boolean
invalid	boolean
canIncrement	boolean
canDecrement	boolean
setValue	(next: string) => void
increment	() => void
decrement	() => void
getRootProps	() => T['element']
getLabelProps	() => T['label']
getInputProps	() => T['input']
getIncrementTriggerProps	() => T['button']
getDecrementTriggerProps	() => T['button']

键盘

规格出处：W3C APG

按键	生效条件	行为
ArrowUp	focus in input, not disabled/readOnly	按 step 递增，越界则停在 max
ArrowDown	focus in input, not disabled/readOnly	按 step 递减，越界则停在 min
PageUp	focus in input, not disabled/readOnly	按 largeStep 递增（默认 10 倍 step）
PageDown	focus in input, not disabled/readOnly	按 largeStep 递减
Home	focus in input, 指定了 min	取 min；未指定 min 时不动
End	focus in input, 指定了 max	取 max；未指定 max 时不动