CountDown 倒计时

17:06

说明

倒计时组件，按 timestamp（单位秒）从设定时长逐秒递减，自动拆分并展示天 / 时 / 分 / 秒。separator 可选英文冒号（colon）或中文「天 / 时 / 分 / 秒」（zh），各时间单元可用 show-days / show-hours / show-minutes / show-seconds 单独显隐；autoplay 为 false 时可通过 ref 调用 start / end 手动控制。

兼容性

平台	支持情况
App	✅ 支持（根节点为块级 flex，多个倒计时需自行包裹容器才能同行）
H5	✅ 支持
微信小程序	✅ 支持

示例

基础用法

默认以冒号分隔，自动开始倒计时，显示到秒。

查看源码

<template>
    <ux-count-down :timestamp="86399"></ux-count-down>
</template>

中文分隔符

separator 设为 zh 时，用"天/时/分/秒"中文分隔，separator-color 自定义分隔符颜色。

查看源码

<template>
    <ux-count-down :timestamp="86399" separator="zh"></ux-count-down>
    <view class="gap"></view>
    <ux-count-down :timestamp="86399" separator="zh" separator-color="#fa3534"></ux-count-down>
</template>

<style scoped>
.gap {
    height: 20px;
}
</style>

隐藏天

show-days 设为 false，天部分折算到小时中。

查看源码

<template>
    <ux-count-down :timestamp="86400" :show-days="false"></ux-count-down>
</template>

自定义样式

通过 font-size / color 自定义数字样式，separator-size 控制分隔符大小。

查看源码

<template>
    <ux-count-down :timestamp="3600" :font-size="20" color="#2979ff" :separator-size="15"></ux-count-down>
</template>

数字边框

show-border 显示数字边框，height 设置数字框尺寸，border-color 自定义边框颜色。

查看源码

<template>
    <ux-count-down :timestamp="7200" :show-border="true" :height="32" bg-color="#ecf5ff" color="#fb7299"></ux-count-down>
    <view class="gap"></view>
    <ux-count-down :timestamp="7200" :show-border="true" :height="32" border-color="#19be6b" bg-color="#f0f9eb" color="#67c23a"></ux-count-down>
</template>

<style scoped>
.gap {
    height: 20px;
}
</style>

显示单元控制

通过 show-hours / show-minutes / show-seconds 控制各时间单元的显隐。

查看源码

<template>
    <ux-count-down :timestamp="59" :show-days="false" :show-hours="false" :show-minutes="false"></ux-count-down>
    <view class="gap"></view>
    <ux-count-down :timestamp="7200" :show-seconds="false"></ux-count-down>
</template>

<style scoped>
.gap {
    height: 20px;
}
</style>

隐藏零天

hide-zero-day 为 true 时，"天"为 0 则隐藏该字段。

查看源码

<template>
    <ux-count-down :timestamp="3599" :hide-zero-day="false"></ux-count-down>
    <view class="gap"></view>
    <ux-count-down :timestamp="3599" :hide-zero-day="true"></ux-count-down>
</template>

<style scoped>
.gap {
    height: 20px;
}
</style>

毫秒刷新

millisecond 为 true 时按毫秒粒度刷新倒计时。

查看源码

<template>
    <ux-count-down :timestamp="5" :millisecond="true"></ux-count-down>
</template>

手动控制

autoplay 设为 false 时不自动开始，可手动调用 start / end 方法。

查看源码

<template>
    <ux-count-down ref="countDownRef" :timestamp="10" :autoplay="false"></ux-count-down>
    <view class="gap"></view>
    <view class="btn-row">
        <view class="btn" @click="startCountDown"><text class="btn-text">开始</text></view>
        <view class="btn" @click="endCountDown"><text class="btn-text">结束</text></view>
    </view>
</template>

<script setup lang="uts">
const countDownRef = ref<any>();

function startCountDown(): void {
    countDownRef.value?.start();
}

function endCountDown(): void {
    countDownRef.value?.end();
}
</script>

<style scoped>
.gap {
    height: 20px;
}
.btn-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 8px;
}
.btn {
    display: flex;
    flex-direction: row;
    align-items: center;
    justify-content: center;
    padding: 4px 12px;
    margin-right: 8px;
    margin-bottom: 8px;
    border-radius: 4px;
    background-color: #ecf5ff;
}
.btn-text {
    font-size: 13px;
    color: #2979ff;
}
</style>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	string | UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
timestamp	倒计时的时间，秒为单位	number | string	0	-
autoplay	是否自动开始倒计时	boolean	true	-
separator	分隔符，colon 为英文冒号，zh 为中文	string	'colon'	-
separatorSize	分隔符的字体大小，单位 px	number | string	DEFAULT_SEPARATOR_SIZE	-
separatorColor	分隔符的颜色	string	''	-
color	字体颜色	string	''	-
fontSize	字体大小，单位 px	number | string	DEFAULT_FONT_SIZE	-
bgColor	数字背景颜色	string	''	-
height	数字框高度（宽度等同此值），单位 px	number | string	'auto'	-
showBorder	是否显示数字框	boolean	false	-
borderColor	边框颜色	string	''	-
showSeconds	是否显示秒	boolean	true	-
showMinutes	是否显示分钟	boolean	true	-
showHours	是否显示小时	boolean	true	-
showDays	是否显示"天"	boolean	true	-
hideZeroDay	当"天"的部分为0时，不显示	boolean	false	-
millisecond	是否按毫秒粒度刷新	boolean	false	-

Events

事件名	说明	回调参数	版本
end	倒计时结束	-	-
change	每秒触发一次，回调为当前剩余的倒计秒数	value: number	-

Slots

ux-count-down 无插槽。

注意事项

1. timestamp 以秒为单位，变化时会重置并（autoplay 为 true 且大于 0 时）重新开始倒计时。
2. autoplay 为 true 但 timestamp 为 0 时不会启动（源码仅在 timestamp 大于 0 时自动开始）。
3. end() 会暂停倒计时并触发 end 事件；change 事件每秒触发一次，回调为剩余整秒数。
4. showDays 为 false 时「天」会折算进小时（小时数可能大于 24），并非丢弃天数。
5. separator 为 colon 时最后一个可见单元后不再显示冒号；为 zh 时各单元后显示中文单位（含「秒」）。
6. hideZeroDay 为 true 且「天」为 0 时，「天」及其后分隔符一并隐藏。
7. height 同时决定数字框的宽和高（宽等于高），配合 showBorder 使用。
8. millisecond 只改变刷新粒度（内部约每 30ms 轮询一次），显示仍只到秒；change 事件可用于毫秒级精度场景。
9. 数字与分隔符字号未显式传入时依次回退全局配置 componentProps['ux-count-down'] 与内建默认 15px。
10. App 端根节点为块级 flex，H5 / 微信小程序为 inline-flex；多个倒计时在 App 端同行显示需自行包裹容器。