时间 time

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

示例

基础用法

渲染成 <time datetime>：文本给人看，datetime 给机器读，两者取自同一个墙钟

2026-08-11 09:30:052026-08-11 00:00:002026-08-11 09:30:052026-08-11 09:30:05

<script setup lang="ts">
import { XhTime } from "@xihan-ui/vue";

// 三种写法都收：只写年月日的串按本地零点解读，不会掉到前一天去
const iso = "2026-08-11T09:30:05";
const dateOnly = "2026-08-11";
const stamp = new Date(2026, 7, 11, 9, 30, 5).getTime();
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px">
    <XhTime :value="iso" />
    <XhTime :value="dateOnly" />
    <XhTime :value="stamp" />
    <XhTime :value="new Date(2026, 7, 11, 9, 30, 5)" />
  </div>
</template>

呈现方式

date 只到日、datetime 到秒、relative 说成「几分钟前」；datetime 属性的精度跟着走

date2026-08-11datetime2026-08-11 09:30:05relative2 小时前

<script setup lang="ts">
import { XhTime } from "@xihan-ui/vue";

const value = "2026-08-11T09:30:05";
// 参照时刻写死，示例的产出才不随打开页面的时间变
const now = "2026-08-11T12:00:00";

const types = ["date", "datetime", "relative"] as const;
</script>

<template>
  <div style="display: grid; grid-template-columns: auto auto; gap: 8px 24px; justify-content: start">
    <template v-for="type in types" :key="type">
      <code>{{ type }}</code>
      <XhTime :value="value" :type="type" :now="now" />
    </template>
  </div>
</template>

自定义格式串

记号是 YYYY / YY / MM / M / DD / D / HH / H / mm / m / ss / s，只改看到的文本，datetime 不跟着变

YYYY-MM-DD HH:mm:ss2026-08-05 09:03:07

YYYY 年 M 月 D 日2026 年 8 月 5 日

M/D H:mm8/5 9:03

YY.MM.DD26.08.05

<script setup lang="ts">
import { XhTime } from "@xihan-ui/vue";

const value = "2026-08-05T09:03:07";

// 两位记号补零，一位记号不补；记号之外的字符原样留着
const patterns = [
  "YYYY-MM-DD HH:mm:ss",
  "YYYY 年 M 月 D 日",
  "M/D H:mm",
  "YY.MM.DD",
];
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 8px">
    <div v-for="pattern in patterns" :key="pattern">
      <code style="margin-inline-end: 12px">{{ pattern }}</code>
      <XhTime :value="value" :format="pattern" />
    </div>
  </div>
</template>

相对时间

刚刚 / n 分钟前 / n 小时前 / n 天前 四档，超过三十天退回绝对日期；locale 只换用词

刚刚just now30 分钟前30 minutes ago3 小时前3 hours ago2 天前2 days ago2026-01-0101/01/2026

<script setup lang="ts">
import { XhTime } from "@xihan-ui/vue";

// 参照时刻给定后产出完全确定，不给则取当前时刻
const now = "2026-08-11T12:00:00";

const moments = [
  "2026-08-11T11:59:40",
  "2026-08-11T11:30:00",
  "2026-08-11T09:00:00",
  "2026-08-09T12:00:00",
  // 超过三十天，四档都装不下，改报绝对日期
  "2026-01-01T00:00:00",
];
</script>

<template>
  <div style="display: grid; grid-template-columns: auto auto; gap: 8px 24px; justify-content: start">
    <template v-for="moment in moments" :key="moment">
      <XhTime :value="moment" type="relative" :now="now" />
      <XhTime :value="moment" type="relative" :now="now" locale="en" />
    </template>
  </div>
</template>

产物

层	值
自定义元素	<xh-time>
Vue 组件	XhTime
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/time.css

解剖

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

data-scope="time"：root

Props

属性	类型	必填	说明
format	string		自定义格式串，记号是 YYYY / YY / MM / M / DD / D / HH / H / mm / m / ss / s。 给了就顶掉该 locale 的缺省格式串；relative 型下只在退回绝对日期时用得上。
locale	TimeLocale		用词：zh-CN 或 en，缺省 zh-CN。它只换给人看的文本，datetime 恒是同一种写法。
now	TimeValue		算相对说法时的参照时刻，缺省取当前时刻。给定后整个组件的产出完全由入参决定。
type	TimeType		呈现方式：date 只到日、datetime 到秒、relative 说成「几分钟前」，缺省 datetime。
value	TimeValue		要显示的时刻。只写年月日的串按本地零点解读。

connect API

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

成员	类型	说明
date	Date | undefined	解析出的时刻；没给或认不出时为 undefined。
text	string	给人看的文本；没有可读时刻时是空串。
stamp	string | undefined	写进 datetime 的那个戳；没有可读时刻时为 undefined，此时根上不写这个属性。
state	TimeState	当前状态。
relative	boolean	这一次是不是真按相对说法念的。落在四档之外退回了绝对日期时为 false。
getRootProps	() => T['element']

键盘

规格出处：W3C APG

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