外观
useCountDown - 倒计时
约 1320 字大约 4 分钟
2025-11-06
useCountDown 是一个用于倒计时的组合式函数,支持毫秒精度、状态持久化和回调函数。
快速开始
1. 导入 useCountDown
<script setup lang="uts">
import { useCountDown } from '@/uni_modules/uview-unix'
const { start, pause, resume, reset, current } = useCountDown({
time: 60000,
millisecond: true
})
</script>2. 使用倒计时
<template>
<view>
<text>{{current.minutes}}分</text>
<text>{{current.seconds}}秒</text>
<text>{{current.milliseconds}}毫秒</text>
<button @click="start">开始</button>
<button @click="pause">暂停</button>
<button @click="resume">继续</button>
<button @click="reset">重置</button>
</view>
</template>API 参考
useCountDown(options: UnCountDownOptions)
创建倒计时实例。
参数
| 参数 | 说明 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| time | 倒计时总时长(毫秒) | number | 是 | - |
| millisecond | 是否开启毫秒级显示 | boolean | 否 | false |
| autoStart | 是否自动开始倒计时 | boolean | 否 | false |
| keepRunning | 是否持久化状态,应用意外关闭后恢复 | boolean | 否 | false |
| uniqueKey | 存储的唯一标识,用于区分多个倒计时 | string | 否 | UVIEW_COUNT_DOWN |
| padZero | 是否在天、小时、分钟、秒数前补零 | boolean | 否 | false |
| onStart | 倒计时开始时的回调 | Function | 否 | - |
| onChange | 倒计时变化时的回调 | Function | 否 | - |
| onEnd | 倒计时结束时的回调 | Function | 否 | - |
返回值
返回一个 UnUseCountDown 对象,包含以下属性和方法:
| 属性/方法 | 说明 | 类型 |
|---|---|---|
| start | 开始倒计时 | Function |
| pause | 暂停倒计时 | Function |
| resume | 继续倒计时 | Function |
| reset | 重置倒计时 | Function |
| current | 当前倒计时状态 | UnCurrentTime |
UnCurrentTime
当前倒计时状态对象。
| 属性 | 说明 | 类型 |
|---|---|---|
| total | 剩余总毫秒数 | number |
| days | 剩余天数 | number | string |
| hours | 剩余小时数(0-23) | number | string |
| minutes | 剩余分钟数(0-59) | number | string |
| seconds | 剩余秒数(0-59) | number | string |
| milliseconds | 剩余毫秒数(0-999) | number | string |
示例
基础倒计时
<template>
<view>
<text>{{current.seconds}}秒</text>
<button @click="start">开始</button>
<button @click="pause">暂停</button>
<button @click="resume">继续</button>
<button @click="reset">重置</button>
</view>
</template>
<script setup lang="uts">
import { useCountDown } from '@/uni_modules/uview-unix'
const { start, pause, resume, reset, current } = useCountDown({
time: 60000
})
</script>毫秒级倒计时
<template>
<view>
<text>{{current.minutes}}:</text>
<text>{{current.seconds}}:</text>
<text>{{current.milliseconds}}</text>
</view>
</template>
<script setup lang="uts">
import { useCountDown } from '@/uni_modules/uview-unix'
const { start, current } = useCountDown({
time: 60000,
millisecond: true
})
start()
</script>带回调的倒计时
<script setup lang="uts">
import { useCountDown, type UnCurrentTime } from '@/uni_modules/uview-unix'
const { start, current } = useCountDown({
time: 60000,
millisecond: true,
onStart: () => {
console.log('倒计时开始')
},
onChange: (value: UnCurrentTime) => {
console.log('倒计时变化', value)
},
onEnd: () => {
console.log('倒计时结束')
}
})
start()
</script>状态持久化
<script setup lang="uts">
import { useCountDown } from '@/uni_modules/uview-unix'
const { start, current } = useCountDown({
time: 60000,
keepRunning: true,
uniqueKey: 'MY_COUNT_DOWN'
})
// 应用意外关闭后,下次打开会自动恢复状态
start()
</script>完整示例
<template>
<un-page>
<card>
<view class="countdown-container">
<view class="countdown-display">
<view class="countdown-display__item">
<text class="countdown-display__number">{{current.minutes}}</text>
<text class="countdown-display__label">分</text>
</view>
<text class="countdown-display__separator">:</text>
<view class="countdown-display__item">
<text class="countdown-display__number">{{current.seconds}}</text>
<text class="countdown-display__label">秒</text>
</view>
<text class="countdown-display__separator">:</text>
<view class="countdown-display__item">
<text class="countdown-display__number">{{current.milliseconds}}</text>
<text class="countdown-display__label">毫秒</text>
</view>
</view>
</view>
<un-grid :border="true" col="4">
<un-grid-item>
<view class="count-down__grid-item" @click="reset">
<un-icon name="reload" :size="22"></un-icon>
<text class="count-down__grid-item__grid-text">重置</text>
</view>
</un-grid-item>
<un-grid-item>
<view class="count-down__grid-item" @click="start">
<view class="count-down__grid-item__circle">
<un-icon color="#fff" name="play-right-fill" :size="22"></un-icon>
</view>
<text class="count-down__grid-item__grid-text">开始</text>
</view>
</un-grid-item>
<un-grid-item>
<view class="count-down__grid-item" @click="pause">
<un-icon name="pause-circle" :size="22"></un-icon>
<text class="count-down__grid-item__grid-text">暂停</text>
</view>
</un-grid-item>
<un-grid-item>
<view class="count-down__grid-item" @click="resume">
<un-icon name="play-circle" :size="22"></un-icon>
<text class="count-down__grid-item__grid-text">继续</text>
</view>
</un-grid-item>
</un-grid>
</card>
</un-page>
</template>
<script setup lang="uts">
import { useCountDown, type UnCurrentTime } from '@/uni_modules/uview-unix'
const { start, pause, resume, reset, current } = useCountDown({
time: 60000,
millisecond: true,
keepRunning: true,
onStart: () => {
console.log('onStart')
},
onChange: (value: UnCurrentTime) => {
console.log('onChange', value)
},
onEnd: () => {
console.log('onEnd')
}
})
</script>
<style lang="scss" scoped>
.countdown-container {
padding: 30px 0;
margin-bottom: 10px;
}
.countdown-display {
display: flex;
flex-direction: row;
justify-content: center;
align-items: center;
&__item {
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
padding: 10px 15px;
width: 80px;
background: #e8e6e6;
border-radius: 10px;
}
&__number {
font-size: 28px;
font-weight: bold;
color: #1677FF;
line-height: 1;
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}
&__label {
font-size: 12px;
color: #909399;
margin-top: 6px;
}
&__separator {
font-size: 48px;
font-weight: bold;
color: #323233;
margin: 0 8px;
line-height: 1;
}
}
.count-down {
&__grid-item {
width: 70px;
height: 70px;
display: flex;
flex-direction: row;
justify-content: center;
align-items: center;
&__circle {
width: 32px;
height: 32px;
border-radius: 32px;
background-color: #3c9cff;
display: flex;
justify-content: center;
align-items: center;
box-shadow: 1px 1px 4px rgba(155, 191, 255, .7);
}
&__grid-text {
font-size: 14px;
color: #909399;
box-sizing: border-box;
margin-left: 6px;
}
}
}
</style>数据类型
/**
* 倒计时选项类型
* 用于配置倒计时的参数
*/
type UnCountDownOptions = {
time: number; // 倒计时总时长(毫秒)
millisecond?: boolean; // 是否开启毫秒级显示
keepRunning?: boolean; // 是否持久化状态
uniqueKey?: string; // 存储的唯一标识
onStart?: () => void; // 开始回调
onChange?: (value: UnCurrentTime) => void; // 变化回调
onEnd?: () => void; // 结束回调
}
/**
* 当前时间类型
* 用于表示倒计时的当前状态,补零后为字符串类型,不补0时为数字类型
*/
type UnCurrentTime = {
total: number; // 剩余总毫秒数
days: number | string; // 剩余天数
hours: number | string; // 剩余小时数(0-23)
minutes: number | string; // 剩余分钟数(0-59)
seconds: number | string; // 剩余秒数(0-59)
milliseconds: number | string; // 剩余毫秒数(0-999)
}注意事项
- 唯一标识:当页面有多个倒计时实例时,建议设置不同的
uniqueKey以避免状态冲突 - 组件卸载:组件卸载时会自动暂停倒计时,无需手动处理
