Skip to content

useCountDown — Countdown ​

17:43

Description ​

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
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 ​

Calls start, pause and reset respectively; onChange resets the status at zero, and reset(null) only resets the value without starting again.

View source
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>

Finish callback ​

A 10-second countdown fires onFinish at zero, and each start calls reset(null) first to restore the initial duration.

View source
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>

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
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 ​

Parameters ​

ParameterDescriptionTypeDefaultVersion
options.timeTotal countdown duration in ms, requirednumber--
options.millisecondWhether to refresh per millisecond instead of per secondbooleanfalse-
options.onChangeCalled on every refresh with the current remaining time(current: CountDownTime) => voidnull-
options.onFinishCalled when the countdown ends() => voidnull-

Returns ​

FieldDescriptionType
currentCurrent remaining time with days / hours / minutes / seconds / milliseconds / remainTimeComputedRef<CountDownTime>
startStarts the countdown; calling it while running does not restart the timing() => void
pausePauses the countdown and clears the timer() => void
resetResets 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 mode current updates only when the whole second changes, while millisecond: true refreshes on every poll.
  • reset pauses first and then resets the value, so start must be called again; start returns immediately when already running.
  • The timer is cleared automatically through onUnmounted when the component unmounts.
  • After reaching zero and firing onFinish, the remaining time stays at 0, so call reset with a new duration before starting again.