CountDown 倒计时

用于实时展示倒计时数值，支持毫秒精度。

引入

通过 easycom 自动引入，无需手动注册。

代码演示

基础用法

通过 time 属性设置倒计时总时长，单位为毫秒。

<zq-count-down :time="30 * 60 * 60 * 1000" />

自定义格式

通过 format 属性设置时间格式。

<!-- 默认格式 HH:mm:ss -->
<zq-count-down :time="30 * 60 * 1000" />

<!-- 包含天数 -->
<zq-count-down :time="2 * 24 * 60 * 60 * 1000" format="DD 天 HH 时 mm 分 ss 秒" />

<!-- 仅显示分秒 -->
<zq-count-down :time="5 * 60 * 1000" format="mm:ss" />

支持的格式化占位符：

占位符	说明
DD	天数（两位补零）
HH	小时（两位补零）
mm	分钟（两位补零）
ss	秒数（两位补零）
SSS	毫秒（三位补零）

毫秒级渲染

通过 millisecond 属性开启毫秒级渲染。

<zq-count-down :time="30 * 60 * 1000" format="HH:mm:ss:SSS" millisecond />

手动控制

通过 ref 获取组件实例，调用 start、stop、reset 方法手动控制。

<zq-count-down ref="countDownRef" :time="60000" :auto-start="false" />
<zq-button text="开始" @click="countDownRef.start()" />
<zq-button text="暂停" @click="countDownRef.stop()" />
<zq-button text="重置" @click="countDownRef.reset()" />

const countDownRef = ref(null)

自定义样式

通过作用域插槽自定义倒计时样式。

<zq-count-down :time="30 * 60 * 1000">
  <template #default="{ time }">
    <text class="block">{{ String(time.hours).padStart(2, '0') }}</text>
    <text class="colon">:</text>
    <text class="block">{{ String(time.minutes).padStart(2, '0') }}</text>
    <text class="colon">:</text>
    <text class="block">{{ String(time.seconds).padStart(2, '0') }}</text>
  </template>
</zq-count-down>

监听事件

<zq-count-down :time="5000" @change="onChange" @finish="onFinish" />

function onChange(timeData) {
  console.log('剩余时间:', timeData.total)
}

function onFinish() {
  console.log('倒计时结束')
}

API

Props

参数	说明	类型	默认值
time	倒计时总时长，单位毫秒	number	0
format	时间格式	string	'HH:mm:ss'
auto-start	是否自动开始倒计时	boolean	true
millisecond	是否开启毫秒级渲染	boolean	false

Events

事件名	说明	回调参数
change	倒计时变化时触发	timeData: TimeData
finish	倒计时结束时触发	-

TimeData 数据结构

键名	说明	类型
days	剩余天数	number
hours	剩余小时	number
minutes	剩余分钟	number
seconds	剩余秒数	number
milliseconds	剩余毫秒	number
total	剩余总毫秒数	number

Methods

通过 ref 获取组件实例后可调用以下方法：

方法名	说明	参数
start	开始倒计时	-
stop	暂停倒计时	-
reset	重置倒计时，若 auto-start 为 true，重置后会自动开始	-

Slots

名称	说明	参数
default	自定义倒计时内容	{ time: TimeData }

注意事项

• 非毫秒模式下，倒计时间隔为 1000ms；毫秒模式下间隔为 30ms。
• time 属性变化时会自动重置倒计时。
• 组件销毁时会自动清除定时器。

主题定制

变量名	说明
--color-text-primary	默认文字颜色