日期输入 date-field

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

示例

基础用法

三段各是一个可加减的数，整组只占一个 Tab 位，三段填齐才第一次报出值

截止日期

yyyy

年

mm

月

dd

日

当前值：（未填齐）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhDateFieldControl,
  XhDateFieldHiddenInput,
  XhDateFieldLabel,
  XhDateFieldRoot,
  XhDateFieldSegment,
} from "@xihan-ui/vue";

const value = ref<string | null>(null);
</script>

<template>
  <XhDateFieldRoot v-model:value="value" locale="zh-CN" name="due">
    <XhDateFieldLabel>截止日期</XhDateFieldLabel>
    <XhDateFieldControl>
      <!-- 段只声明下标，是年是月由 locale 算出；中间的「年 / 月 / 日」是普通节点 -->
      <XhDateFieldSegment :index="0" />
      <span>年</span>
      <XhDateFieldSegment :index="1" />
      <span>月</span>
      <XhDateFieldSegment :index="2" />
      <span>日</span>
    </XhDateFieldControl>
    <!-- 表单出口：值是 ISO 串，没填齐时它就是空的 -->
    <XhDateFieldHiddenInput />
  </XhDateFieldRoot>

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

段序随 locale

同一份标记，locale 换成 en-US 后段序自动排成月日年

zh-CN

2026

年

07

月

28

日

en-US

07

/

28

/

2026

两份值都是 ISO 串：2026-07-28 · 2026-07-28

<script setup lang="ts">
import { ref } from "vue";
import {
  XhDateFieldControl,
  XhDateFieldLabel,
  XhDateFieldRoot,
  XhDateFieldSegment,
} from "@xihan-ui/vue";

const zh = ref<string | null>("2026-07-28");
const us = ref<string | null>("2026-07-28");
</script>

<template>
  <div style="display: grid; gap: 16px">
    <XhDateFieldRoot v-model:value="zh" locale="zh-CN">
      <XhDateFieldLabel>zh-CN</XhDateFieldLabel>
      <XhDateFieldControl>
        <XhDateFieldSegment :index="0" />
        <span>年</span>
        <XhDateFieldSegment :index="1" />
        <span>月</span>
        <XhDateFieldSegment :index="2" />
        <span>日</span>
      </XhDateFieldControl>
    </XhDateFieldRoot>

    <XhDateFieldRoot v-model:value="us" locale="en-US">
      <XhDateFieldLabel>en-US</XhDateFieldLabel>
      <XhDateFieldControl>
        <XhDateFieldSegment :index="0" />
        <span>/</span>
        <XhDateFieldSegment :index="1" />
        <span>/</span>
        <XhDateFieldSegment :index="2" />
      </XhDateFieldControl>
    </XhDateFieldRoot>

    <p style="margin: 0; font-size: 13px">
      两份值都是 ISO 串：{{ zh ?? "（空）" }} · {{ us ?? "（空）" }}
    </p>
  </div>
</template>

可填区间

min / max 收窄各段的加减范围，越界的初值只做标注、不被改写

在区间内（2020 – 2030）

2026

年

07

月

28

日

越界（min 2020-01-01）

2019

年

05

月

01

日

<script setup lang="ts">
import {
  XhDateFieldControl,
  XhDateFieldLabel,
  XhDateFieldRoot,
  XhDateFieldSegment,
} from "@xihan-ui/vue";
</script>

<template>
  <div style="display: grid; gap: 16px">
    <XhDateFieldRoot
      default-value="2026-07-28"
      locale="zh-CN"
      min="2020-01-01"
      max="2030-12-31"
    >
      <XhDateFieldLabel>在区间内（2020 – 2030）</XhDateFieldLabel>
      <XhDateFieldControl>
        <XhDateFieldSegment :index="0" />
        <span>年</span>
        <XhDateFieldSegment :index="1" />
        <span>月</span>
        <XhDateFieldSegment :index="2" />
        <span>日</span>
      </XhDateFieldControl>
    </XhDateFieldRoot>

    <!-- 初值早于 min：root 挂上 data-out-of-range，值本身原样留着 -->
    <XhDateFieldRoot default-value="2019-05-01" locale="zh-CN" min="2020-01-01">
      <XhDateFieldLabel>越界（min 2020-01-01）</XhDateFieldLabel>
      <XhDateFieldControl>
        <XhDateFieldSegment :index="0" />
        <span>年</span>
        <XhDateFieldSegment :index="1" />
        <span>月</span>
        <XhDateFieldSegment :index="2" />
        <span>日</span>
      </XhDateFieldControl>
    </XhDateFieldRoot>
  </div>
</template>

禁用与非法

禁用整组退出 Tab 序、隐藏输入不再提交；invalid 只改观感与 aria，不动值

禁用

2026

年

07

月

28

日

只读

2026

年

07

月

28

日

invalid

2026

年

07

月

28

日

<script setup lang="ts">
import {
  XhDateFieldControl,
  XhDateFieldLabel,
  XhDateFieldRoot,
  XhDateFieldSegment,
} from "@xihan-ui/vue";
</script>

<template>
  <div style="display: grid; gap: 16px">
    <XhDateFieldRoot default-value="2026-07-28" locale="zh-CN" disabled>
      <XhDateFieldLabel>禁用</XhDateFieldLabel>
      <XhDateFieldControl>
        <XhDateFieldSegment :index="0" />
        <span>年</span>
        <XhDateFieldSegment :index="1" />
        <span>月</span>
        <XhDateFieldSegment :index="2" />
        <span>日</span>
      </XhDateFieldControl>
    </XhDateFieldRoot>

    <XhDateFieldRoot default-value="2026-07-28" locale="zh-CN" read-only>
      <XhDateFieldLabel>只读</XhDateFieldLabel>
      <XhDateFieldControl>
        <XhDateFieldSegment :index="0" />
        <span>年</span>
        <XhDateFieldSegment :index="1" />
        <span>月</span>
        <XhDateFieldSegment :index="2" />
        <span>日</span>
      </XhDateFieldControl>
    </XhDateFieldRoot>

    <XhDateFieldRoot default-value="2026-07-28" locale="zh-CN" invalid>
      <XhDateFieldLabel>invalid</XhDateFieldLabel>
      <XhDateFieldControl>
        <XhDateFieldSegment :index="0" />
        <span>年</span>
        <XhDateFieldSegment :index="1" />
        <span>月</span>
        <XhDateFieldSegment :index="2" />
        <span>日</span>
      </XhDateFieldControl>
    </XhDateFieldRoot>
  </div>
</template>

形态

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

outline

2026

年

07

月

28

日

subtle

2026

年

07

月

28

日

ghost

2026

年

07

月

28

日

<script setup lang="ts">
import {
  XhDateFieldControl,
  XhDateFieldLabel,
  XhDateFieldRoot,
  XhDateFieldSegment,
} from "@xihan-ui/vue";

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

<template>
  <div style="display: grid; gap: 16px; justify-items: start">
    <XhDateFieldRoot
      v-for="v in variants"
      :key="v"
      :variant="v"
      default-value="2026-07-28"
      locale="zh-CN"
    >
      <XhDateFieldLabel>{{ v }}</XhDateFieldLabel>
      <XhDateFieldControl>
        <XhDateFieldSegment :index="0" />
        <span>年</span>
        <XhDateFieldSegment :index="1" />
        <span>月</span>
        <XhDateFieldSegment :index="2" />
        <span>日</span>
      </XhDateFieldControl>
    </XhDateFieldRoot>
  </div>
</template>

语气

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

brand

2026

年

07

月

28

日

neutral

2026

年

07

月

28

日

success

2026

年

07

月

28

日

warning

2026

年

07

月

28

日

danger

2026

年

07

月

28

日

info

2026

年

07

月

28

日

<script setup lang="ts">
import {
  XhDateFieldControl,
  XhDateFieldLabel,
  XhDateFieldRoot,
  XhDateFieldSegment,
} 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">
    <XhDateFieldRoot
      v-for="t in tones"
      :key="t"
      variant="subtle"
      :tone="t"
      default-value="2026-07-28"
      locale="zh-CN"
    >
      <XhDateFieldLabel>{{ t }}</XhDateFieldLabel>
      <XhDateFieldControl>
        <XhDateFieldSegment :index="0" />
        <span>年</span>
        <XhDateFieldSegment :index="1" />
        <span>月</span>
        <XhDateFieldSegment :index="2" />
        <span>日</span>
      </XhDateFieldControl>
    </XhDateFieldRoot>
  </div>
</template>

尺寸

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

sm

2026

年

07

月

28

日

默认

2026

年

07

月

28

日

lg

2026

年

07

月

28

日

<script setup lang="ts">
import {
  XhDateFieldControl,
  XhDateFieldLabel,
  XhDateFieldRoot,
  XhDateFieldSegment,
} 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">
    <XhDateFieldRoot
      v-for="s in sizes"
      :key="s.label"
      :size="s.size"
      default-value="2026-07-28"
      locale="zh-CN"
    >
      <XhDateFieldLabel>{{ s.label }}</XhDateFieldLabel>
      <XhDateFieldControl>
        <XhDateFieldSegment :index="0" />
        <span>年</span>
        <XhDateFieldSegment :index="1" />
        <span>月</span>
        <XhDateFieldSegment :index="2" />
        <span>日</span>
      </XhDateFieldControl>
    </XhDateFieldRoot>
  </div>
</template>

精确到分

granularity=minute 在年月日后面接出时、分两段，值随之带上 T 与时间位

发布时间

2026

年

07

月

28

日 

13

:

45

当前值：2026-07-28T13:45

<script setup lang="ts">
import { ref } from "vue";
import {
  XhDateFieldControl,
  XhDateFieldLabel,
  XhDateFieldRoot,
  XhDateFieldSegment,
} from "@xihan-ui/vue";

const value = ref<string | null>("2026-07-28T13:45");
</script>

<template>
  <XhDateFieldRoot v-model:value="value" locale="zh-CN" granularity="minute">
    <XhDateFieldLabel>发布时间</XhDateFieldLabel>
    <XhDateFieldControl>
      <!-- 段序仍由 locale 排：前三段是年月日，时分按精度追加在后面 -->
      <XhDateFieldSegment :index="0" />
      <span>年</span>
      <XhDateFieldSegment :index="1" />
      <span>月</span>
      <XhDateFieldSegment :index="2" />
      <span>日</span>
      <span>&nbsp;</span>
      <XhDateFieldSegment :index="3" />
      <span>:</span>
      <XhDateFieldSegment :index="4" />
    </XhDateFieldControl>
  </XhDateFieldRoot>

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

外部写值与清空

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

取件日期

yyyy

年

mm

月

dd

日

未填齐

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhDateFieldControl,
  XhDateFieldLabel,
  XhDateFieldRoot,
  XhDateFieldSegment,
} from "@xihan-ui/vue";

const value = ref<string | null>(null);

// 相对今天偏移若干天的 ISO 串
function shift(days: number) {
  const d = new Date();
  d.setDate(d.getDate() + days);
  const month = `${d.getMonth() + 1}`.padStart(2, "0");
  const day = `${d.getDate()}`.padStart(2, "0");
  return `${d.getFullYear()}-${month}-${day}`;
}

const today = shift(0);
const nextWeek = shift(7);
</script>

<template>
  <XhDateFieldRoot
    v-slot="{ empty, complete, outOfRange, setValue, clear }"
    v-model:value="value"
    :min="today"
    locale="zh-CN"
  >
    <XhDateFieldLabel>取件日期</XhDateFieldLabel>
    <XhDateFieldControl>
      <XhDateFieldSegment :index="0" />
      <span>年</span>
      <XhDateFieldSegment :index="1" />
      <span>月</span>
      <XhDateFieldSegment :index="2" />
      <span>日</span>
    </XhDateFieldControl>

    <div style="display: flex; gap: 8px">
      <XhButton size="sm" variant="outline" @click="setValue(today)">今天</XhButton>
      <XhButton size="sm" variant="outline" @click="setValue(nextWeek)">
        七天后
      </XhButton>
      <!-- 一段都没填时这颗按钮按不动 -->
      <XhButton size="sm" variant="ghost" :disabled="empty" @click="clear()">
        清空
      </XhButton>
    </div>

    <span style="font-size: 13px">
      {{ complete ? (outOfRange ? "早于今天，收不了件" : "可取件") : "未填齐" }}
    </span>
  </XhDateFieldRoot>
</template>

值变化事件

value-change 每次带上整份 ISO 串，段位被清掉时它是 null

改一改再看下面

2026

年

07

月

28

日

最近变化：（还没动过）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhDateFieldControl,
  XhDateFieldLabel,
  XhDateFieldRoot,
  XhDateFieldSegment,
} from "@xihan-ui/vue";

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

// 只留最近三条，新的排在前面
function onValueChange(details: { value: string | null }) {
  log.value = [details.value ?? "null", ...log.value].slice(0, 3);
}
</script>

<template>
  <XhDateFieldRoot
    default-value="2026-07-28"
    locale="zh-CN"
    @value-change="onValueChange"
  >
    <XhDateFieldLabel>改一改再看下面</XhDateFieldLabel>
    <XhDateFieldControl>
      <XhDateFieldSegment :index="0" />
      <span>年</span>
      <XhDateFieldSegment :index="1" />
      <span>月</span>
      <XhDateFieldSegment :index="2" />
      <span>日</span>
    </XhDateFieldControl>
  </XhDateFieldRoot>

  <span style="font-size: 13px">
    最近变化：{{ log.length ? log.join(" ← ") : "（还没动过）" }}
  </span>
</template>

段位自定义文本

段位插槽给出这一段的类型、取值与焦点状态，离焦后年份只留两位、月份换成中文名

发布日期

26

年

七月

28

日

值仍是 ISO 串：2026-07-28

<script setup lang="ts">
import { ref } from "vue";
import {
  XhDateFieldControl,
  XhDateFieldLabel,
  XhDateFieldRoot,
  XhDateFieldSegment,
} from "@xihan-ui/vue";

const value = ref<string | null>("2026-07-28");

const MONTH_NAMES = [
  "一月",
  "二月",
  "三月",
  "四月",
  "五月",
  "六月",
  "七月",
  "八月",
  "九月",
  "十月",
  "十一月",
  "十二月",
];

// 插槽交出来的这一段
interface Segment {
  type: string;
  value: number | null;
  text: string;
  empty: boolean;
  focused: boolean;
}

// 空段与正在编辑的段照原样显示，其余按自己的写法渲染
function display(segment: Segment) {
  if (segment.empty || segment.focused) return segment.text;
  if (segment.type === "year") return segment.text.slice(-2);
  if (segment.type === "month") return MONTH_NAMES[(segment.value ?? 1) - 1];
  return segment.text;
}
</script>

<template>
  <XhDateFieldRoot v-model:value="value" locale="zh-CN">
    <XhDateFieldLabel>发布日期</XhDateFieldLabel>
    <XhDateFieldControl>
      <XhDateFieldSegment v-slot="{ segment }" :index="0">
        {{ display(segment) }}
      </XhDateFieldSegment>
      <span>年</span>
      <XhDateFieldSegment v-slot="{ segment }" :index="1">
        {{ display(segment) }}
      </XhDateFieldSegment>
      <XhDateFieldSegment v-slot="{ segment }" :index="2">
        {{ display(segment) }}
      </XhDateFieldSegment>
      <span>日</span>
    </XhDateFieldControl>
  </XhDateFieldRoot>

  <span style="font-size: 13px">值仍是 ISO 串：{{ value ?? "（未填齐）" }}</span>
</template>

对外值换个写法

组件读写的恒是 ISO 串，宿主用一个双向 computed 换成自己的格式，表单也提交这一份

结算日期

2026

年

07

月

28

日

随表单提交的是：2026/07/28 · 组件里的值是：2026-07-28

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

// 宿主与后端约定的写法
const stored = ref("2026/07/28");

// 读时换成 ISO 交给组件，写回时换回宿主的写法
const iso = computed<string | null>({
  get: () => (stored.value ? stored.value.split("/").join("-") : null),
  set: (next) => {
    stored.value = next ? next.split("-").join("/") : "";
  },
});
</script>

<template>
  <XhDateFieldRoot v-model:value="iso" locale="zh-CN">
    <XhDateFieldLabel>结算日期</XhDateFieldLabel>
    <XhDateFieldControl>
      <XhDateFieldSegment :index="0" />
      <span>年</span>
      <XhDateFieldSegment :index="1" />
      <span>月</span>
      <XhDateFieldSegment :index="2" />
      <span>日</span>
    </XhDateFieldControl>
    <!-- 不用内建的隐藏输入，自己写一份提交宿主格式 -->
    <input type="hidden" name="settle" :value="stored" />
  </XhDateFieldRoot>

  <span style="font-size: 13px">
    随表单提交的是：{{ stored || "（未填齐）" }} · 组件里的值是：{{ iso ?? "null" }}
  </span>
</template>

产物

层	值
自定义元素	<xh-date-field>
Vue 组件	XhDateFieldControl XhDateFieldHiddenInput XhDateFieldLabel XhDateFieldRoot XhDateFieldSegment
组合式函数	useDateField
状态机	dateFieldMachine
皮肤	@xihan-ui/styles/date-field.css

解剖

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

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

Props

属性	类型	必填	说明
value	string | null		受控值，ISO 串（'2026-07-28' / '2026-07-28T13:45'）；null 表示空。给定即受控。
defaultValue	string | null		非受控初值，同样是 ISO 串。
min	string		下界，ISO 串。参与各段区间的收窄，并决定 outOfRange。
max	string		上界，ISO 串。
locale	string		BCP 47 语言标记，决定年月日三段的先后。不给按 en-US（月日年）排。
timeZone	string		IANA 时区名，只用来取「今天」：空段上按上下键时从今天的对应位起步。
granularity	DateGranularity		精度，默认 day（只有年月日三段）。
disabled	boolean
readOnly	boolean
invalid	boolean
required	boolean
name	string		表单字段名；给了隐藏输入才带 name，ISO 串随表单一并提交。
placeholder	{ readonly [K in DateSegmentType]?: string }		各段未填时显示的占位串，逐段覆盖内置默认（yyyy / mm / dd / hh / mm / ss）。
translations	{ readonly [K in DateSegmentType]?: string }		各段的读屏名字，逐段覆盖内置默认。段是 spinbutton，没有名字读屏只念得出一串数字。
variant	ControlVariant		形态：outline / subtle / ghost，决定描边与底色怎么用。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定聚焦与强调用哪族颜色。
size	Size		尺寸：sm / md / lg。
onValueChange	(details: DateFieldValueChangeDetails) => void

状态机

状态：idle

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

判据：canEdit

connect API

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

成员	类型	说明
value	string | null	ISO 串；段位没填齐时是 null。
valueAsDate	Date | null	同一个值的原生 Date；空值或算不出来时为 null。按 timeZone 换算。
segments	DateFieldSegmentState[]	逐段投影，文档序即 locale 决定的段序。
complete	boolean	段位填齐了（value 非 null）。
empty	boolean	一段都没填。
outOfRange	boolean	填齐了但落在 min/max 之外。
disabled	boolean
readOnly	boolean
invalid	boolean
focusedSegment	DateSegmentType | null	焦点落在哪一段；焦点在组外时为 null。
locale	string
granularity	DateGranularity
setValue	(next: string | null) => void	直接写整份值；传 null 等于清空。
clear	() => void
getRootProps	() => T['element']
getLabelProps	() => T['element']	标题不是原生 label（段位是 div，不可被 label 标注），点它由连接层代为把焦点送进首段。
getControlProps	() => T['element']	role=group 的分段容器。
getSegmentProps	(props: DateFieldSegmentProps) => 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	焦点移到末段
Backspace	focus in a segment, not disabled/readOnly	清掉本段，焦点不动；整份值随之变成 null
0 / 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9	focus in a segment, not disabled/readOnly	往本段补一位数字；补满（再补一位必溢出或位数用尽）即自动跳下一段