useCountDown 倒计时
17:43说明
useCountDown 以结束时间戳计时,避免定时器递减造成的漂移;暴露剩余的响应式对象与开始 / 暂停 / 重置方法,支持按秒或按毫秒刷新以及结束回调。
示例
按秒倒计时
60 秒倒计时在 onMounted 时调用 start,current 按秒刷新剩余天 / 时 / 分 / 秒与毫秒。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in basicRows"
:key="index"
:title="item.desc"
:value="item.result"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { $u, useCountDown } from '@/uni_modules/uview-pro-x';
// 解构方式使用:const { current, start } = useCountDown({ time })
const basic = useCountDown({ time: 60000 });
type Row = {
desc: string;
result: string;
last: boolean;
};
const basicRows = computed((): Row[] => {
const current = basic.current.value;
return [
{ desc: '剩余天数', result: current.days.toString(), last: false },
{ desc: '剩余小时', result: $u.padZero(current.hours), last: false },
{ desc: '剩余分钟', result: $u.padZero(current.minutes), last: false },
{ desc: '剩余秒数', result: $u.padZero(current.seconds), last: false },
{ desc: '剩余毫秒', result: current.remainTime.toString(), last: true }
];
});
onMounted((): void => {
basic.start();
});
</script>开始 / 暂停 / 重置
分别调用 start、pause、reset,onChange 在归零时把状态复位,reset(null) 只重置数值不会自动开始。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item title="当前状态" :value="controlStatus" :arrow="false" :border-bottom="true" />
<ux-cell-item title="剩余毫秒" :value="control.current.value.remainTime.toString()" :arrow="false" :border-bottom="false" />
</ux-cell-group>
<ux-gap :height="12" />
<ux-row :gutter="10">
<ux-col :span="4">
<ux-button size="small" type="primary" block :text="startText" @click="handleStart()" />
</ux-col>
<ux-col :span="4">
<ux-button size="small" type="warning" block text="暂停" @click="handlePause()" />
</ux-col>
<ux-col :span="4">
<ux-button size="small" type="info" block text="重置" @click="handleReset()" />
</ux-col>
</ux-row>
</template>
<script setup lang="ts">
import { useCountDown, type CountDownTime } from '@/uni_modules/uview-pro-x';
const hasStarted = ref(false);
const running = ref(false);
const control = useCountDown({
time: 20000,
onChange: (current: CountDownTime): void => {
if (current.remainTime == 0) {
running.value = false;
hasStarted.value = false;
}
}
});
const controlStatus = computed((): string => {
if (running.value) return '进行中';
if (!hasStarted.value) return '未开始';
return '已暂停';
});
const startText = computed((): string => (hasStarted.value ? '继续' : '开始'));
function handleStart(): void {
hasStarted.value = true;
running.value = true;
control.start();
}
function handlePause(): void {
running.value = false;
control.pause();
}
// reset 只重置数值,不会自动开始
function handleReset(): void {
running.value = false;
hasStarted.value = false;
control.reset(null);
}
</script>结束回调
10 秒倒计时归零时触发 onFinish,每次开始前先调用 reset(null) 回到初始时长。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item title="剩余时间:" :value="quickRemainText" :arrow="false" :border-bottom="true" />
<ux-cell-item title="结束标记:" :arrow="false" :border-bottom="false">
<ux-tag size="mini" :type="finished ? 'success' : 'info'" :text="finished ? '已完成' : '未开始'" />
</ux-cell-item>
</ux-cell-group>
<ux-gap :height="12" />
<ux-button size="small" type="primary" block text="开始 10 秒倒计时" @click="handleQuickStart()" />
</template>
<script setup lang="ts">
import { useCountDown } from '@/uni_modules/uview-pro-x';
const finished = ref(false);
const quick = useCountDown({
time: 10000,
onFinish: (): void => {
finished.value = true;
}
});
const quickRemainText = computed((): string => (quick.current.value.remainTime / 1000).toFixed(1) + 's');
function handleQuickStart(): void {
finished.value = false;
quick.reset(null);
quick.start();
}
</script>使用说明
以提示条说明内部按结束时间计时、onUnmounted 自动清理定时器、reset 后需再次调用 start。
查看源码
vue
<template>
<ux-alert-tips type="primary" :show-icon="true" title="const { current, start, pause, reset } = useCountDown({ time: 60000 })" />
<ux-gap :height="8" />
<ux-alert-tips type="primary" :show-icon="true" title="内部以结束时间计时,长时间运行不漂移" />
<ux-gap :height="8" />
<ux-alert-tips type="primary" :show-icon="true" title="onUnmounted 自动清理定时器,无需手动清除" />
<ux-gap :height="8" />
<ux-alert-tips type="primary" :show-icon="true" title="reset 后需再次调用 start 才会继续倒数" />
</template>
<script setup lang="ts">
import { useCountDown } from '@/uni_modules/uview-pro-x';
const { current, start, pause, reset } = useCountDown({ time: 60000 });
</script>API
参数
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| options.time | 倒计时总时长(ms),必填 | number | - | - |
| options.millisecond | 是否按毫秒粒度刷新,默认按秒刷新 | boolean | false | - |
| options.onChange | 每次刷新时回调,参数为当前剩余时间 | (current: CountDownTime) => void | null | - |
| options.onFinish | 倒计时结束时的回调 | () => void | null | - |
返回值
| 字段 | 说明 | 类型 |
|---|---|---|
| current | 当前剩余时间,含 days / hours / minutes / seconds / milliseconds / remainTime | ComputedRef<CountDownTime> |
| start | 开始倒计时;运行中调用不会重新计时 | () => void |
| pause | 暂停倒计时并清除定时器 | () => void |
| reset | 重置剩余时间;totalTime 传 null 时使用初始 time,重置后不会自动开始 | (totalTime?: number | null) => void |
注意事项
- 内部用 30ms 的
setTimeout轮询,按秒模式只在整秒变化时更新current;millisecond为true时每次轮询都会刷新。 reset会先暂停再重置数值,必须再次调用start才开始倒数;start在已运行时直接返回。- 组件卸载时通过
onUnmounted自动清理定时器。 - 归零触发
onFinish后剩余时间停在 0,重新开始前应先调用reset设置新的总时长。