Countdown 倒计时

倒计时组件，常配合 Statistic 使用。支持自定义格式、暂停/恢复/重置等操作。

基础用法

通过 value 设置目标时间（时间戳或倒计时毫秒数），format 设置显示格式。

WARNING

value 为相对毫秒数时（< 1e10），从组件挂载时开始倒计时；为绝对时间戳时（≥ 1e10），倒计时到该时间点结束。

距离活动开始

00:29:59

<template>
  <ZcCountdown :value="Date.now() + 1000 * 60 * 30" title="距离活动开始" />
</template>

自定义格式

format 支持 DD、HH、mm、ss、SSS 等占位符。

HH:mm:ss

02:00:00

DD天 HH:mm:ss

01天 02:00:00

中文格式

01天01小时59分59秒

<template>
  <div style="display: flex; flex-direction: column; gap: 16px;">
    <ZcCountdown :value="Date.now() + 1000 * 60 * 60 * 26" format="HH:mm:ss" title="HH:mm:ss" />
    <ZcCountdown :value="Date.now() + 1000 * 60 * 60 * 26" format="DD天 HH:mm:ss" title="DD天 HH:mm:ss" />
    <ZcCountdown :value="Date.now() + 1000 * 60 * 60 * 26" format="DD天HH小时mm分ss秒" title="中文格式" />
  </div>
</template>

前缀与后缀

通过 prefix、suffix 属性或同名插槽设置。

限时优惠

⏰01:00:00后结束

<template>
  <ZcCountdown :value="Date.now() + 1000 * 60 * 60" title="限时优惠" prefix="⏰" suffix="后结束" />
</template>

自定义数值样式

通过 valueStyle 设置数值区域的样式。

倒计时

00:10:00

<template>
  <ZcCountdown
    :value="Date.now() + 1000 * 60 * 10"
    title="倒计时"
    :value-style="{ color: '#f5222d', fontSize: '32px', fontWeight: '700' }"
  />
</template>

暂停 / 恢复 / 重置

通过 ref 调用 pause()、resume()、reset() 方法。

可控制倒计时

00:05:00

<script setup>
import { ref } from 'vue'

const countdownRef = ref()

const value = Date.now() + 1000 * 60 * 5

function handlePause() {
  countdownRef.value?.pause()
}
function handleResume() {
  countdownRef.value?.resume()
}
function handleReset() {
  countdownRef.value?.reset()
}
function onFinish() {
  console.log('倒计时结束')
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 16px; align-items: flex-start;">
    <ZcCountdown ref="countdownRef" :value="value" title="可控制倒计时" @finish="onFinish" />
    <div style="display: flex; gap: 8px;">
      <ZcButton size="small" @click="handlePause">暂停</ZcButton>
      <ZcButton size="small" @click="handleResume">恢复</ZcButton>
      <ZcButton size="small" @click="handleReset">重置</ZcButton>
    </div>
  </div>
</template>

配合 Statistic 使用

ZcStatistic.Countdown 是 ZcCountdown 的别名，可用于 Statistic 命名空间下。

Statistic.Countdown 模式

00:15:00

<script setup>
import { ZcStatistic } from '@zc-ui/components'
</script>

<template>
  <component :is="ZcStatistic.Countdown" :value="Date.now() + 1000 * 60 * 15" title="Statistic.Countdown 模式" />
</template>

Countdown API

Props

参数	说明	类型	默认值
value	目标时间（时间戳 ≥ 1e10 或倒计时毫秒数）	number	0
format	显示格式（支持 YYYY MM DD HH mm ss SSS S）	string	'HH:mm:ss'
title	标题	string	''
prefix	前缀	string	''
suffix	后缀	string	''
valueStyle	数值自定义样式	Record<string, string>	{}
interval	更新间隔(ms)，默认根据 format 自动判断	number	1000 | 50

Events

事件名	说明	回调参数
change	每次更新时触发
finish	倒计时结束时触发

Methods (via ref)

方法名	说明	参数
pause()	暂停倒计时
resume()	恢复倒计时
reset()	重置到初始值并重新开始

Slots

插槽名	说明
default	自定义数值显示（作用域插槽：displayValue）
title	自定义标题
prefix	自定义前缀
suffix	自定义后缀