时间输入 time-field

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

示例

基础用法

默认 24 小时制，上下键在段区间里回绕，缺一段整份值就退回空串

开始时间

--:--

当前值：（未填齐）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTimeFieldControl,
  XhTimeFieldHiddenInput,
  XhTimeFieldLabel,
  XhTimeFieldRoot,
  XhTimeFieldSegment,
} from "@xihan-ui/vue";

const value = ref("");
</script>

<template>
  <XhTimeFieldRoot v-model:value="value" name="start">
    <XhTimeFieldLabel>开始时间</XhTimeFieldLabel>
    <XhTimeFieldControl>
      <!-- 段的身份由作者声明；中间的「:」是普通节点，换段时不会被当成一站 -->
      <XhTimeFieldSegment segment="hour" />
      <span>:</span>
      <XhTimeFieldSegment segment="minute" />
    </XhTimeFieldControl>
    <!-- 表单出口：缺段时它就是空的 -->
    <XhTimeFieldHiddenInput />
  </XhTimeFieldRoot>

  <span style="font-size: 13px">当前值：{{ value || "（未填齐）" }}</span>
</template>

12 小时制

hour-cycle=12 多出一个上午/下午段，值本身仍是 24 小时的串

会议时间

01:45 PM

当前值：13:45

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTimeFieldControl,
  XhTimeFieldLabel,
  XhTimeFieldRoot,
  XhTimeFieldSegment,
} from "@xihan-ui/vue";

const value = ref("13:45");
</script>

<template>
  <XhTimeFieldRoot v-model:value="value" :hour-cycle="12">
    <XhTimeFieldLabel>会议时间</XhTimeFieldLabel>
    <XhTimeFieldControl>
      <XhTimeFieldSegment segment="hour" />
      <span>:</span>
      <XhTimeFieldSegment segment="minute" />
      <span>&nbsp;</span>
      <!-- 在这一段上按 a / p 直接指定上下午，翻面只改值不改数字 -->
      <XhTimeFieldSegment segment="dayPeriod" />
    </XhTimeFieldControl>
  </XhTimeFieldRoot>

  <span style="font-size: 13px">当前值：{{ value || "（未填齐）" }}</span>
</template>

精度到秒

granularity=second 让秒段显出来并参与值，空段按上下键从该段边界起步

定时

--:--:--

当前值：（未填齐）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTimeFieldControl,
  XhTimeFieldLabel,
  XhTimeFieldRoot,
  XhTimeFieldSegment,
} from "@xihan-ui/vue";

const value = ref("");
</script>

<template>
  <XhTimeFieldRoot v-model:value="value" granularity="second">
    <XhTimeFieldLabel>定时</XhTimeFieldLabel>
    <XhTimeFieldControl>
      <XhTimeFieldSegment segment="hour" />
      <span>:</span>
      <XhTimeFieldSegment segment="minute" />
      <span>:</span>
      <XhTimeFieldSegment segment="second" />
    </XhTimeFieldControl>
  </XhTimeFieldRoot>

  <span style="font-size: 13px">当前值：{{ value || "（未填齐）" }}</span>
</template>

禁用与越界

禁用整组退出 Tab 序；越界只做标注，08:00 原样留着不被改写

禁用

13:45

越界（09:00 – 18:00）

08:00

<script setup lang="ts">
import {
  XhTimeFieldControl,
  XhTimeFieldLabel,
  XhTimeFieldRoot,
  XhTimeFieldSegment,
} from "@xihan-ui/vue";
</script>

<template>
  <div style="display: grid; gap: 16px">
    <XhTimeFieldRoot default-value="13:45" disabled>
      <XhTimeFieldLabel>禁用</XhTimeFieldLabel>
      <XhTimeFieldControl>
        <XhTimeFieldSegment segment="hour" />
        <span>:</span>
        <XhTimeFieldSegment segment="minute" />
      </XhTimeFieldControl>
    </XhTimeFieldRoot>

    <XhTimeFieldRoot default-value="08:00" min="09:00" max="18:00">
      <XhTimeFieldLabel>越界（09:00 – 18:00）</XhTimeFieldLabel>
      <XhTimeFieldControl>
        <XhTimeFieldSegment segment="hour" />
        <span>:</span>
        <XhTimeFieldSegment segment="minute" />
      </XhTimeFieldControl>
    </XhTimeFieldRoot>
  </div>
</template>

形态

variant 只改分段框的底色与描边用法，分段结构与键盘行为都不变

outline

09:30

subtle

09:30

ghost

09:30

<script setup lang="ts">
import {
  XhTimeFieldControl,
  XhTimeFieldLabel,
  XhTimeFieldRoot,
  XhTimeFieldSegment,
} from "@xihan-ui/vue";

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

<template>
  <div style="display: grid; gap: 16px; justify-items: start">
    <XhTimeFieldRoot v-for="v in variants" :key="v" :variant="v" default-value="09:30">
      <XhTimeFieldLabel>{{ v }}</XhTimeFieldLabel>
      <XhTimeFieldControl>
        <XhTimeFieldSegment segment="hour" />
        <span>:</span>
        <XhTimeFieldSegment segment="minute" />
      </XhTimeFieldControl>
    </XhTimeFieldRoot>
  </div>
</template>

语气

tone 决定用哪族颜色，与 variant 正交；这里固定 subtle 形态，只看语气这一轴

brand

09:30

neutral

09:30

success

09:30

warning

09:30

danger

09:30

info

09:30

<script setup lang="ts">
import {
  XhTimeFieldControl,
  XhTimeFieldLabel,
  XhTimeFieldRoot,
  XhTimeFieldSegment,
} 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">
    <XhTimeFieldRoot v-for="t in tones" :key="t" variant="subtle" :tone="t" default-value="09:30">
      <XhTimeFieldLabel>{{ t }}</XhTimeFieldLabel>
      <XhTimeFieldControl>
        <XhTimeFieldSegment segment="hour" />
        <span>:</span>
        <XhTimeFieldSegment segment="minute" />
      </XhTimeFieldControl>
    </XhTimeFieldRoot>
  </div>
</template>

尺寸

不传 size 即默认档；行高、内边距与字号一起换档，标题也跟着变

sm

09:30

默认

09:30

lg

09:30

<script setup lang="ts">
import {
  XhTimeFieldControl,
  XhTimeFieldLabel,
  XhTimeFieldRoot,
  XhTimeFieldSegment,
} from "@xihan-ui/vue";

const sizes = [
  { size: "sm", label: "sm" },
  { size: undefined, label: "默认" },
  { size: "lg", label: "lg" },
];
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; align-items: flex-end; gap: 16px">
    <XhTimeFieldRoot v-for="s in sizes" :key="s.label" :size="s.size" default-value="09:30">
      <XhTimeFieldLabel>{{ s.label }}</XhTimeFieldLabel>
      <XhTimeFieldControl>
        <XhTimeFieldSegment segment="hour" />
        <span>:</span>
        <XhTimeFieldSegment segment="minute" />
      </XhTimeFieldControl>
    </XhTimeFieldRoot>
  </div>
</template>

外部写值与清空

根插槽给出 setValue / clear 与空、越界两个判据，按钮照它们摆

上门时间

--:--

未填齐

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhTimeFieldControl,
  XhTimeFieldLabel,
  XhTimeFieldRoot,
  XhTimeFieldSegment,
} from "@xihan-ui/vue";

const value = ref("");

// 此刻的时分，两位补零
function now() {
  const d = new Date();
  const h = `${d.getHours()}`.padStart(2, "0");
  const m = `${d.getMinutes()}`.padStart(2, "0");
  return `${h}:${m}`;
}
</script>

<template>
  <XhTimeFieldRoot
    v-slot="{ empty, outOfRange, setValue, clear }"
    v-model:value="value"
    min="09:00"
    max="18:00"
  >
    <XhTimeFieldLabel>上门时间</XhTimeFieldLabel>
    <XhTimeFieldControl>
      <XhTimeFieldSegment segment="hour" />
      <span>:</span>
      <XhTimeFieldSegment segment="minute" />
    </XhTimeFieldControl>

    <div style="display: flex; gap: 8px">
      <XhButton size="sm" variant="outline" @click="setValue(now())">此刻</XhButton>
      <XhButton size="sm" variant="outline" @click="setValue('09:00')">
        开门时间
      </XhButton>
      <!-- 一段都没填时这颗按钮按不动 -->
      <XhButton size="sm" variant="ghost" :disabled="empty" @click="clear()">
        清空
      </XhButton>
    </div>

    <span style="font-size: 13px">
      {{ empty ? "未填齐" : outOfRange ? "不在营业时段（09:00 – 18:00）" : "可上门" }}
    </span>
  </XhTimeFieldRoot>
</template>

可选值白名单

值交给宿主持有，写回来的时间被吸附到清单里的一格，上下键与数字键因此都落在清单上

发车时刻

08:00

只收 08:00 / 12:00 / 18:00，当前值：08:00

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTimeFieldControl,
  XhTimeFieldLabel,
  XhTimeFieldRoot,
  XhTimeFieldSegment,
} from "@xihan-ui/vue";

const allowed = ["08:00", "12:00", "18:00"];

const value = ref(allowed[0]);

// 比原值大就取清单里的下一格，比原值小就取上一格，走到头回绕
function snap(next: string) {
  if (next === "" || allowed.includes(next)) return next;
  const forward = next > value.value;
  const hit = forward
    ? allowed.find((t) => t > next)
    : [...allowed].reverse().find((t) => t < next);
  return hit ?? (forward ? allowed[0] : allowed[allowed.length - 1]);
}
</script>

<template>
  <!-- 受控写法：值不交给组件自己存，写入意图先过一遍 snap -->
  <XhTimeFieldRoot :value="value" @update:value="value = snap($event)">
    <XhTimeFieldLabel>发车时刻</XhTimeFieldLabel>
    <XhTimeFieldControl>
      <XhTimeFieldSegment segment="hour" />
      <span>:</span>
      <XhTimeFieldSegment segment="minute" />
    </XhTimeFieldControl>
  </XhTimeFieldRoot>

  <span style="font-size: 13px">
    只收 {{ allowed.join(" / ") }}，当前值：{{ value || "（空）" }}
  </span>
</template>

产物

层	值
自定义元素	<xh-time-field>
Vue 组件	XhTimeFieldControl XhTimeFieldHiddenInput XhTimeFieldLabel XhTimeFieldRoot XhTimeFieldSegment
组合式函数	useTimeField
状态机	timeFieldMachine
皮肤	@xihan-ui/styles/time-field.css

解剖

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

data-scope="time-field"：root · label · control · segment · hidden-input

Props

属性	类型	必填	说明
value	string		受控值，ISO 时间串。给定即受控：cell 直读 prop，写只发 onValueChange 不落内部值。
defaultValue	string
min	string		下界（含）。只用来标注越界，不改写用户填进去的东西。
max	string		上界（含）。同上。
locale	string		BCP 47 语言标记。决定上午/下午的文字，以及未显式给 hourCycle 时的小时制。
hourCycle	TimeHourCycle		小时制。不给则按 locale 推断，locale 也没有时用 24。
granularity	TimeGranularity		值精确到哪一段，默认 minute。
disabled	boolean		禁用：段整体退出 Tab 序列、键盘一概不响应，隐藏输入不参与提交。
readOnly	boolean		只读：仍可聚焦、可用左右键在段间走，但改不动值。
invalid	boolean		校验失败标注。
required	boolean		必填标注（落到每段的 aria-required 上）。
name	string		表单字段名；给了隐藏输入才带 name，值随表单一并提交。
placeholder	string		空段的占位字符（单字符），按段宽重复，默认 '-'。
variant	ControlVariant		形态：outline / subtle / ghost，决定描边与底色怎么用。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定聚焦与强调用哪族颜色。
size	Size		尺寸：sm / md / lg。
onValueChange	(details: TimeFieldValueChangeDetails) => void		value 变化意图回调；受控时是唯一出口，非受控随内部写入一并通知。

状态机

状态：idle

事件：VALUE.SET · VALUE.CLEAR · SEGMENT.STEP · SEGMENT.DIGIT · SEGMENT.CLEAR · SEGMENT.PERIOD · SEGMENT.FOCUS · SEGMENT.BLUR · FORM.RESET

判据：canEdit

connect API

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

成员	类型	说明
value	string	ISO 时间串；任一必填段为空时是空串。
empty	boolean	值为空串（还没填全）。作者据此点亮提交按钮或显示提示。
outOfRange	boolean	已填全但落在 min/max 之外。只是标注，不改写值。
disabled	boolean
readOnly	boolean
invalid	boolean
hourCycle	TimeHourCycle	实际生效的小时制（prop 没给时由 locale 推出来的那个）。
granularity	TimeGranularity
segments	TimeSegmentType[]	此刻参与显示的段，文档序。未列入的段由 connect 打上 hidden 收起。
focusedSegment	TimeSegmentType | null	焦点所在段；焦点在组外时为 null。
getSegmentText	(props: TimeFieldSegmentProps) => string	某一段该显示的文字（空段是占位串）。两个适配器都拿它填文本，保证同构。
setValue	(next: string) => void
clear	() => void
getRootProps	() => T['element']
getLabelProps	() => T['label']
getControlProps	() => T['element']
getSegmentProps	(props: TimeFieldSegmentProps) => T['element']
getHiddenInputProps	() => T['input']	表单出口：一份 type=hidden 的原生输入，随表单提交 ISO 串。

键盘

规格出处：W3C APG

按键	生效条件	行为
ArrowUp	focus in a segment, not disabled/readOnly	本段加一格，到头回绕；空段落到该段下界
ArrowDown	focus in a segment, not disabled/readOnly	本段减一格，到头回绕；空段落到该段上界
ArrowRight	focus in a segment, not disabled	焦点移到下一段；已在末段则不动，不回绕
ArrowLeft	focus in a segment, not disabled	焦点移到上一段；已在首段则不动，不回绕
Home	focus in a segment, not disabled	焦点移到首段
End	focus in a segment, not disabled	焦点移到末段
0-9	focus in a 数字段, not disabled/readOnly	把数字并进本段；本段再吃不下第二位时自动跳到下一段
Backspace / Delete	focus in a segment, not disabled/readOnly	清掉本段；小时被清时上下午段仍保留原来的上午/下午
a / p	focus in 上下午段, 12 小时制, not disabled/readOnly	a 取上午、p 取下午（不区分大小写）