倒计时 countdown

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

示例

基础用法

给一个剩余毫秒就开始往下走，缺省模板是 HH:mm:ss；走到 0 就停住不再往下

距离结束：01:00:00

本次答题剩余：00:02:00

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

const oneHour = 3600 * 1000;
const twoMinutes = 120 * 1000;
</script>

<template>
  <p>距离结束：<XhCountdown :value="oneHour" /></p>
  <p>本次答题剩余：<XhCountdown :value="twoMinutes" /></p>
</template>

模板与精度

format 里 H 时 m 分 s 秒 S 毫秒，重复字母的个数即最少位数；precision 决定读到的数有多细

中文单位：1 时 2 分 3 秒

只看分秒：02:03

写了 SSS 但精度是秒：03.000

精度提到毫秒：03.456

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

const value = 3723 * 1000 + 456;
</script>

<template>
  <!-- 模板里非记号的字符原样留下，所以中文单位直接写在里面就行 -->
  <p>中文单位：<XhCountdown :value="value" format="H 时 m 分 s 秒" /></p>
  <p>只看分秒：<XhCountdown :value="value" format="mm:ss" /></p>

  <!-- 精度缺省是整秒，所以这一行的毫秒段一直是 000 -->
  <p>写了 SSS 但精度是秒：<XhCountdown :value="value" format="ss.SSS" /></p>
  <!-- 想显示毫秒得把精度提上去，模板与精度是两件事 -->
  <p>精度提到毫秒：<XhCountdown :value="value" format="ss.SSS" :precision="3" /></p>
</template>

自己排版每一段

默认插槽给出拆好的时、分、秒、毫秒，想把每段装进独立的格子就自己写

01时02分03秒

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

const value = 3723 * 1000;
</script>

<template>
  <XhCountdown v-slot="{ hours, minutes, seconds }" :value="value">
    <b>{{ String(hours).padStart(2, "0") }}</b>
    <span>时</span>
    <b>{{ String(minutes).padStart(2, "0") }}</b>
    <span>分</span>
    <b>{{ String(seconds).padStart(2, "0") }}</b>
    <span>秒</span>
  </XhCountdown>
</template>

暂停、继续与到点

active 翻假即停在当前剩余量，翻真从那里接着走；改 value 就是重新计时，到点派一次 finish

5.0 秒

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

// 两个时长交替：value 变了组件才重新计时，同一个值再写一遍不算换了一轮
const rounds = [5000, 8000];
const at = ref(0);
const running = ref(true);
const done = ref(false);

function restart(): void {
  at.value = (at.value + 1) % rounds.length;
  done.value = false;
  running.value = true;
}
</script>

<template>
  <XhCountdown
    :value="rounds[at]"
    :active="running"
    :precision="1"
    format="s.S"
    @finish="done = true"
  />
  <span> 秒</span>

  <XhButton variant="outline" @click="running = !running">
    {{ running ? "暂停" : "继续" }}
  </XhButton>
  <XhButton variant="solid" @click="restart">重新计时（5 秒 / 8 秒 交替）</XhButton>
  <span v-if="done">到点了</span>
</template>

产物

层	值
自定义元素	<xh-countdown>
Vue 组件	XhCountdown
状态机	countdownMachine
皮肤	@xihan-ui/styles/countdown.css

解剖

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

data-scope="countdown"：root

Props

属性	类型	必填	说明
value	number		剩余毫秒，缺省 0。改写它即把剩余量落到新值并从那里重新计时。
format	string		模板，缺省 HH:mm:ss。H 时、m 分、s 秒、S 毫秒，重复字母的个数即最少位数。
active	boolean		是否在走，缺省 true。翻假即停在当前剩余量，翻真从那里接着走。
precision	number		取值粒度：0 到秒、1 到十分之一秒、2 到百分之一秒、3 到毫秒。缺省 0。
live	CountdownLive		读屏播报档位，缺省 off。
onFinish	(details: CountdownFinishDetails) => void		走到 0 时通知一次。中途被停掉不通知。

状态机

状态：idle · running

事件：RUN.START · RUN.STOP · RUN.SYNC · FRAME

判据：isSettled · isActive

connect API

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

成员	类型	说明
phase	CountdownPhase
value	number	按精度量化后的剩余毫秒，也是拆分与铺字的输入。
text	string	按模板铺好的文本，也就是根里该显示的字。
parts	CountdownParts	拆开的时、分、秒、毫秒，给要自己排版每一段的作者用。
running	boolean	是否还在走。
finished	boolean	剩余量是否已经归零。
getRootProps	() => T['element']

键盘

规格出处：W3C APG

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