useCountDown — Countdown
17:43Description
useCountDown times against an end timestamp so the result does not drift from decrementing intervals. It exposes the reactive remaining time plus start / pause / reset methods, with per-second or per-millisecond refresh and a finish callback.
Examples
Per-second countdown
A 60-second countdown starts in onMounted, and current refreshes the remaining days, hours, minutes, seconds and milliseconds every second.
View source
<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
Calls start, pause and reset respectively; onChange resets the status at zero, and reset(null) only resets the value without starting again.
View source
<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>Finish callback
A 10-second countdown fires onFinish at zero, and each start calls reset(null) first to restore the initial duration.
View source
<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>Usage
Explains that timing is based on an end timestamp, onUnmounted clears the timer automatically, and start must be called again after reset.
View source
<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
Parameters
| Parameter | Description | Type | Default | Version |
|---|---|---|---|---|
| options.time | Total countdown duration in ms, required | number | - | - |
| options.millisecond | Whether to refresh per millisecond instead of per second | boolean | false | - |
| options.onChange | Called on every refresh with the current remaining time | (current: CountDownTime) => void | null | - |
| options.onFinish | Called when the countdown ends | () => void | null | - |
Returns
| Field | Description | Type |
|---|---|---|
| current | Current remaining time with days / hours / minutes / seconds / milliseconds / remainTime | ComputedRef<CountDownTime> |
| start | Starts the countdown; calling it while running does not restart the timing | () => void |
| pause | Pauses the countdown and clears the timer | () => void |
| reset | Resets the remaining time; null falls back to the initial time, and resetting does not start automatically | (totalTime?: number | null) => void |
Notes
- The hook polls with a 30ms
setTimeout; in per-second modecurrentupdates only when the whole second changes, whilemillisecond: truerefreshes on every poll. resetpauses first and then resets the value, sostartmust be called again;startreturns immediately when already running.- The timer is cleared automatically through
onUnmountedwhen the component unmounts. - After reaching zero and firing
onFinish, the remaining time stays at 0, so callresetwith a new duration before starting again.