更新记录

1.0.0(2026-11-17) 下载此版本

新增

  • 首次发布
  • 倒计时组件,支持 text 文本 / box 分块卡片两种样式
  • 双驱动:time 时长(ms)或 endTime 结束时间戳(ms,大于 0 优先按 Date.now() 差值计算)
  • format 格式串支持 DD / HH / mm / ss / SS(厘秒)占位符,无 DD 时小时 = 天 * 24 + 时
  • millisecond 开启毫秒精度(interval 50ms,文本模式 format 含 SS 同样生效),无毫秒时 200ms
  • 基于 Date.now() 差值累计避免计时漂移,结束触发 finish 事件(仅一次)
  • 提供 start / pause / reset 方法(通过 ref 调用),autoStart 控制自动开始,卸载自动清理定时器

平台兼容性

uni-app(5.0)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
- √ √ √ √ - √ √ √
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
√ √ √ - - - - - - - - -

ry-countdown 倒计时

倒计时组件(uni-app / Vue3 版):text 文本 / box 分块卡片两种样式,支持时长(time)或结束时间戳(endTime)双驱动。格式串支持 DD / HH / mm / SS(厘秒)占位符,毫秒精度可选,提供 start / pause / reset 方法与 finish 事件,一套 API 覆盖秒杀活动、验证码、开抢倒计时、直播预告等场景。

需要 uni-app x(uvue)版本请使用 ry-countdown-x。

安装

三种方式任选其一。

方式一:uni_modules 导入(推荐)

通过 HBuilderX 从插件市场导入 uni_modules,组件位于 uni_modules/ry-countdown/components/ry-countdown/ 下,easycom 自动注册,无需 import。

方式二:源码放到 components 目录

下载源码后,把组件放到项目的 components/ry-countdown/ry-countdown.vue,保持该目录结构,即符合 easycom 默认规则,自动注册。

方式三:手动导入

组件放在其他任意位置时,显式导入注册即可,与 easycom 不冲突(显式导入优先生效):

import ryCountdown from '@/components/ry-countdown/ry-countdown.vue'

使用示例

<template>
    <!-- 1. 最简用法:文本倒计时(时长驱动) -->
    <ry-countdown :time="95000"></ry-countdown>

    <!-- 2. 自定义格式:含天与中文占位 -->
    <ry-countdown :time="90061000" format="DD天HH时mm分ss秒"></ry-countdown>

    <!-- 3. 分块卡片 + 单位标签 -->
    <ry-countdown :time="90061000" type="box" :show-label="true"></ry-countdown>

    <!-- 4. 毫秒精度(厘秒) -->
    <ry-countdown :time="95000" :millisecond="true"></ry-countdown>
    <ry-countdown :time="95000" type="box" :millisecond="true" :show-label="true"></ry-countdown>

    <!-- 5. 结束时间戳驱动(如秒杀) -->
    <ry-countdown :end-time="endTime" format="HH:mm:ss" @finish="onFinish"></ry-countdown>

    <!-- 6. 手动控制:start / pause / reset 通过 ref 调用 -->
    <ry-countdown ref="cd" :time="60000" :auto-start="false"></ry-countdown>
    <view @click="$refs.cd.start()">开始</view>
    <view @click="$refs.cd.pause()">暂停</view>
    <view @click="$refs.cd.reset()">重置</view>
</template>

<script setup>
    import { ref } from 'vue'

    // 结束时间戳:1 小时后
    const endTime = ref(Date.now() + 3600000)

    const onFinish = () => {
        uni.showToast({ title: '倒计时结束', icon: 'none' })
    }
</script>

API

Props

属性 类型 默认值 说明
time Number 0 倒计时时长(ms),endTime 不传时生效
endTime Number 0 结束时间戳(ms),大于 0 时优先按 Date.now() 差值计算
format String 'HH:mm:ss' 文本模式格式串:DD 天 / HH 时 / mm 分 / ss 秒 / SS 厘秒,无 DD 时小时 = 天 * 24 + 时
type String 'text' 样式:text 按 format 拼接 / box 分块卡片
autoStart Boolean true 是否自动开始计时
millisecond Boolean false 是否显示厘秒(interval 50ms;文本模式 format 含 SS 同样生效)
showLabel Boolean false box 模式是否显示单位标签
labels Array ['天','时','分','秒'] box 模式单位标签

Events

事件名 说明 回调参数
finish 倒计时结束时触发(仅一次) —

Methods(通过 ref 调用)

方法名 说明
start 开始 / 从暂停的剩余时间继续
pause 暂停计时
reset 重置到初始(endTime 模式按当前时间重算)并暂停

Slots

本组件无插槽,内容由 time / endTime / format 驱动。

分块说明

box 模式的块数量按 format 占位符推导:format 含 DD 显示天块,含 SS 或开启 millisecond 追加厘秒块;showLabel 开启后每块下方显示对应单位标签(厘秒块无标签)。

实现说明

计时基于 Date.now() 与结束时间点的差值累计,每 tick 直接换算剩余时间,规避 setInterval 误差漂移;interval 无毫秒 200ms / 有毫秒 50ms。剩余归零后清定时器并触发 finish(仅一次),组件卸载前自动清理定时器,time / endTime 变化时重置并按 autoStart 决定是否继续。全端(H5 / 小程序 / App)表现一致。

技术支持

  • 微信:howe1144(一定在线,紧急问题首选)
  • QQ 群:415367029(常规问题,群友互助,作者可能在线)
  • ***(很少在线)
  • 插件市场评论区:回复不及时,仅适合不着急的留言反馈

支持与赞赏

如果你觉得本插件解决了你的问题,可以考虑支持作者:

支付宝赞助 微信赞助

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

许可协议

MIT协议

暂无用户评论。