更新记录

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

新增

  • 首次发布
  • 倒计时组件(uni-app x / uvue 版),支持 time 时长(ms)与 endTime 结束时间戳(ms)双驱动,endTime 优先
  • format 支持 DD / HH / mm / ss / SS 占位符,无 DD 时小时 = 天 * 24 + 时
  • 双样式:type="text" 文本拼接 / "box" 分块卡片,box 支持 showLabel 单位标签与 labels 自定义
  • millisecond 开启厘秒精度(interval 50ms),文本 format 含 SS 同样生效
  • 提供 start / pause / reset 方法(defineExpose 暴露,父组件通过 ref + $callMethod 调用),结束触发 finish 事件
  • 基于 Date.now() 差值累计避免计时漂移,卸载自动清理定时器

平台兼容性

uni-app x(5.0)

Chrome Safari Android iOS 鸿蒙 微信小程序
√ √ √ √ √ √

ry-countdown-x 倒计时(uni-app x)

倒计时组件(uni-app x / uvue 版):支持 time 时长与 endTime 结束时间戳双驱动、文本与分块卡片双样式、format 占位符自由拼装、毫秒精度,并提供 start / pause / reset 手动控制方法。适用于秒杀倒计时、活动剩余时间、订单支付倒计时等场景。

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

安装

三种方式任选其一。

方式一:uni_modules 导入(推荐)

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

方式二:源码放到 components 目录

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

方式三:手动导入

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

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

使用示例

<template>
    <!-- 1. 文本模式:默认 format="HH:mm:ss" -->
    <ry-countdown :time="95000"></ry-countdown>

    <!-- 2. 自定义格式(DD 天 / HH 时 / mm 分 / ss 秒 / SS 厘秒) -->
    <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>

    <!-- 5. 结束时间戳驱动 + 结束事件 -->
    <ry-countdown :end-time="endTime" format="HH:mm:ss" @finish="onFinish"></ry-countdown>

    <!-- 6. 手动控制:ref + $callMethod -->
    <ry-countdown ref="cdRef" :time="60000" :auto-start="false"></ry-countdown>
    <text @click="onControl('start')">开始</text>
    <text @click="onControl('pause')">暂停</text>
    <text @click="onControl('reset')">重置</text>
</template>

<script setup lang="uts">
    import { ref } from 'vue'

    const endTime = ref<number>(Date.now() + 60000)
    const cdRef = ref<ComponentPublicInstance | null>(null)

    const onControl = (fn : string) => {
        const cd = cdRef.value
        if (cd != null) {
            cd.$callMethod(fn)
        }
    }

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

API

Props

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

Events

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

Methods

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

uni-app x 中调用自定义组件方法需先 defineExpose 暴露,父组件通过 ref + $callMethod('方法名') 调用,组件已内置暴露。

格式说明

  • DD 天、HH 时、mm 分、ss 秒、SS 厘秒(两位补零)
  • format 不含 DD 时,HH 为总小时数(天 * 24 + 时),适合「仅展示 HH:mm:ss」的场景
  • type="box" 时块数量与天 / 厘秒块按 format 占位符推导;若需 box 模式展示天,请在 format 中带上 DD(如 format="DD天HH:mm:ss")

实现说明

计时基于「结束时间点 - Date.now()」差值计算剩余,避免 setInterval 漂移;millisecond 或 format 含 SS 时 interval 降为 50ms,否则 200ms。组件卸载时自动 clearInterval,无定时器泄漏。App-Android / iOS / 鸿蒙 / Web / 小程序表现一致。

技术支持

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

支持与赞赏

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

支付宝赞助 微信赞助

隐私、权限声明

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

无

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

无

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

无

许可协议

MIT协议

暂无用户评论。