@tataland/use-countdown

Tata 组件库 - useCountdown 倒计时 composable。

统一了 mass / mass2 里各页面各写一份的倒计时逻辑：既支持"从现在起倒计时 N 秒"（验证码倒计时），也支持"目标时间点，随接口数据变化自动重新计时"（活动开始/结束倒计时），并统一处理了 iOS Safari 日期解析（yyyy-MM-dd HH:mm:ss 需要把 - 换成 /）和组件销毁时的定时器清理。

安装

npm install @tataland/use-countdown

用法一：倒计时 N 秒（验证码等）

import { useCountdown } from "@tataland/use-countdown";

const { remaining, duration, isRunning, start } = useCountdown(0, { immediate: false });

function sendCode() {
  // 发验证码...
  start(60); // 从现在起倒计时 60 秒
}

<template>
  <button :disabled="isRunning" @click="sendCode">
    {{ isRunning ? `${remaining}s 后重新发送` : "发送验证码" }}
  </button>
</template>

用法二：目标时间点（接口下发，自动跟随变化）

import { useCountdown } from "@tataland/use-countdown";

const info = ref<{ startTime: string }>();

// getter 形式：info.value.startTime 变化时自动重新计时
const { duration, isRunning } = useCountdown(() => info.value?.startTime, {
  onFinish: () => {
    // 倒计时结束后的回调，比如刷新页面状态
  },
});

<template>
  <span v-if="isRunning">{{ duration.text }}</span>
  <!-- 或者自己拼格式： -->
  <span v-if="isRunning">{{ duration.d }}:{{ duration.h }}:{{ duration.m }}:{{ duration.s }}</span>
</template>

API

useCountdown(source, options?)

• source: number | string | Date | (() => number | string | Date | null | undefined)
  • number — 视为"从现在起倒计时 N 秒"
  • string | Date — 视为目标时间点（string 支持 yyyy-MM-dd HH:mm:ss 格式）
  • 传函数（getter）时会用 watch 监听其返回值变化，值变化后自动重新开始计时
• options.interval — 计时间隔（ms），默认 1000
• options.immediate — 是否自动开始，默认 true（传 false 时需要手动调用 start()）
• options.onFinish — 倒计时归零时触发

返回：

| 名称 | 类型 | 说明 | | --------- | --------------------------------- | ----------------------------------------------------- | | remaining | Ref<number> | 剩余秒数 | | duration | ComputedRef<{d,h,m,s,text}> | 格式化后的天/时/分/秒（补零字符串）与拼接文案 text | | isRunning | Ref<boolean> | 是否正在倒计时 | | start | (override?: number\|string\|Date) => void | 开始/重新开始；传参时忽略 source，直接用该值 | | pause | () => void | 暂停（保留剩余时间，可用 resume 继续） | | resume | () => void | 从暂停处继续 | | stop | () => void | 停止并将剩余时间清零 |

组件卸载（onUnmounted）时会自动清理定时器，不需要手动处理。