Skip to content

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是否按毫秒粒度刷新,默认按秒刷新booleanfalse-
options.onChange每次刷新时回调,参数为当前剩余时间(current: CountDownTime) => voidnull-
options.onFinish倒计时结束时的回调() => voidnull-

返回值 ​

字段说明类型
current当前剩余时间,含 days / hours / minutes / seconds / milliseconds / remainTimeComputedRef<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 设置新的总时长。