示例工程小程序前端【免费下载链接】miniprogram-demo微信小程序组件 / API / 云开发示例项目地址https://gitcode.com/gh_mirrors/mi/miniprogram-demo点击查看免费下载导读CountDown 是 TDesign 小程序组件库tdesign-miniprogram中用于实时展示倒计时数值的组件在微信小程序中适用于秒杀抢购、活动倒计时、验证码重发、直播开场等典型场景。本文将结合 miniprogram-demo 仓库中该组件的完整源码count-down.js 及配套 count-down.wxml从引入方式、全部 Props/Events 参数、自定义格式化、样式主题与 CSS 变量到底层实现原理给出可直接复制运行的实战方案。一、组件概览与引入方式CountDown 组件用于实时展示倒计时数值组件源码位于仓库的 miniprogram/packageAPI/components/tdesign-miniprogram/count-down/核心文件包括count-down.js组件逻辑基于SuperComponent的类组件实现count-down.wxml组件模板渲染count-down.wxss三套主题default / round / square的样式props.js 与 type.d.ts属性定义与类型声明utils.js时间解析与格式化核心工具引入方式分两种全局引入在miniprogram根目录的app.json中配置usingComponentsusingComponents: { t-count-down: tdesign-miniprogram/count-down/count-down }局部引入在需要使用该组件的页面或组件的index.json中配置usingComponents: { t-count-down: tdesign-miniprogram/count-down/count-down }从 count-down.json 可以看到组件自身声明了component: true与styleIsolation: apply-shared内部依赖了t-icon组件。组件类名前缀由 common/config.js 中的prefix: t决定因此最终渲染的根节点类名为t-count-down。提示若希望与 TDesign 官方站点演示中的数字字体效果保持一致可在项目中引入 TCloudNumber 字体将TCloudNumberVF.ttf作为TCloudNumber字体资源。在 count-down.wxss 中可以看到根节点默认的font-family第一个字体即为TCloudNumber。二、CountDown Props 参数详解组件全部属性在 props.js 中定义以下表格完整列出各参数及其默认值| 名称 | 类型 | 默认值 | 描述 | 必传 | | -- | -- | -- | -- | -- | | style | Object | - | 样式 | N | | custom-style | Object | - | 样式一般用于开启虚拟化组件节点场景 | N | | auto-start | Boolean | true | 是否自动开始倒计时 | N | | content | String / Slot | default | 最终倒计时的展示内容值为default时使用默认的格式否则使用自定义样式插槽 | N | | format | String | HH:mm:ss | 时间格式DD-日HH-时mm-分ss-秒SSS-毫秒 | N | | millisecond | Boolean | false | 是否开启毫秒级渲染 | N | | size | String | medium | 倒计时尺寸。可选项small/medium/large自0.5.1版本引入 | N | | split-with-unit | Boolean | false | 使用时间单位分割自0.5.1版本引入 | N | | theme | String | default | 倒计时风格。可选项default/round/square自0.5.1版本引入 | N | | time | Number | 0 |必需。倒计时时长单位毫秒 | Y |关键参数说明time必传倒计时总时长单位毫秒。例如 10 秒的倒计时传入time10000。从源码 count-down.js 可见当time属性变化时observers.time组件会调用reset()重新开始计数初始remain this.properties.time。format时间格式支持DD日、HH时、mm分、ss秒、SSS毫秒五种单位默认HH:mm:ss。注意这里mm表示分钟、ss表示秒。可以自由组合例如跨天倒计时formatDD天 HH:mm:ss含毫秒formatHH:mm:ss:SSS仅分钟和秒formatmm:ss底层格式化逻辑实现在 utils.js 的parseFormat中它先计算各单位的数值D/H/m/s/S再按格式串中出现的顺序依次替换为数字。当格式中的单位重复出现如HH时会进行前导零补位——这正是倒计时显示00:05:03而非0:5:3的原因。auto-start自动开始默认true即组件挂载后立即开始倒计时。若设为false则需手动调用组件的start()方法启动。millisecond毫秒级渲染默认false组件按“秒”粒度更新见下文的isSameSecond优化开启后以毫秒粒度渲染配合format中的SSS可展示毫秒级倒计时如比赛计时器。size 与 theme尺寸与风格sizesmall / medium / large 三档尺寸themedefault / round / square 三种风格。round为圆形胶囊数字块square为圆角方形数字块两者默认使用错误色背景见 CSS Variables 一节。split-with-unit单位分割默认false时数字之间用冒号:分隔00 : 05 : 03设为true后分隔符替换为中文单位00天 05时 03分之类。该行为在 count-down.wxml 中通过timeDataUnit渲染单位中文映射定义在 utils.jsDD: 天、HH: 时、mm: 分、ss: 秒、SSS: 毫秒。基础用法示例!-- 10 秒倒计时默认格式 HH:mm:ss自动开始 -- t-count-down time{{10000}} / !-- 跨天倒计时自定义格式与单位分割 -- t-count-down time{{86400000}} formatDD天 HH:mm:ss split-with-unit{{true}} / !-- 毫秒级倒计时 -- t-count-down time{{5000}} millisecond{{true}} formatHH:mm:ss:SSS / !-- 手动控制不自动开始由页面调用 start() -- t-count-down idmyCountDown time{{60000}} auto-start{{false}} /三、CountDown Events 事件| 名称 | 参数 | 描述 | | -- | -- | -- | | change |(time: TimeData)| 时间变化时触发 | | finish | - | 倒计时结束时触发 |change事件的参数TimeData结构如下interface TimeData { days: number; hours: number; minutes: number; seconds: number; milliseconds: number; }在 count-down.js 的updateTime(remain)中可以看到每次更新时间都会先this.triggerEvent(change, timeData)抛出时间数据当剩余时间归零时执行this.pause()并this.triggerEvent(finish)。change事件在每次渲染更新秒级或毫秒级时都会触发适合用来把剩余时间同步给页面其他位置finish只触发一次适合处理倒计时结束后的业务逻辑如按钮恢复可点、活动开始等。Page({ onCountdownChange(e) { const { days, hours, minutes, seconds } e.detail; console.log(剩余 ${days} 天 ${hours} 时 ${minutes} 分 ${seconds} 秒); }, onCountdownFinish() { wx.showToast({ title: 倒计时结束 }); }, });t-count-down time{{10000}} bind:changeonCountdownChange bind:finishonCountdownFinish /四、外部样式类External Classes组件支持通过外部样式类覆盖内部关键节点的样式| 类名 | 描述 | | -- | -- | | t-class | 根节点样式类 | | t-class-count | 计数样式类 | | t-class-split | 分隔线样式类 |这三个外部类在 count-down.js 中声明t-class/t-class-count/t-class-split并在 count-down.wxml 中分别挂到根view、数字text与分隔符text上。使用方式在页面 wxss 中定义同名类然后在组件标签上通过externalClasses传入t-count-down classcustom time{{10000}} t-classmy-root t-class-countmy-count t-class-splitmy-split //* 页面 wxss */ .my-root { /* 覆盖根节点样式 */ } .my-count { color: #0052d9; } .my-split { color: #999; }五、CSS Variables 自定义主题组件提供了 4 个 CSS 变量用于在不改动组件源码的情况下定制颜色与圆角| 名称 | 默认值 | 描述 | | -- | -- | -- | | --td-countdown-bg-color | error-color-6 | 数字块背景色round / square 主题 | | --td-countdown-default-color | font-gray-1 | default 主题文字颜色 | | --td-countdown-round-border-radius | radius-circle | round 主题圆角默认 50% 圆形 | | --td-countdown-round-color | font-white-1 | round / square 主题文字颜色 | | --td-countdown-square-border-radius | radius-small | square 主题圆角 |这些变量的实际消费点位于 count-down.wxss--td-countdown-default-color控制default主题文字颜色--td-countdown-bg-color与--td-countdown-round-color共同控制round/square主题的数字块两个 border-radius 变量分别控制圆形与方形数字块的圆角。注意样式表中的变量都有多层回退值如var(--td-countdown-bg-color, var(--td-error-color-6, #d54941))即使不设置 CSS 变量组件也能按 TDesign 默认色板正常渲染。在页面中覆盖示例/* 页面或全局 wxss */ page { --td-countdown-bg-color: #0052d9; /* 数字块改为品牌蓝 */ --td-countdown-round-color: #ffffff; /* round 主题文字保持白色 */ --td-countdown-square-border-radius: 8rpx; }六、代码演示基础倒计时与调整尺寸基础倒计时t-count-down time{{10000}} /这是最简单的用法传入毫秒级时长组件自动以HH:mm:ss格式开始递减显示结束后触发finish事件。秒杀场景中常搭配formatHH:mm:ss与bind:finish实现“活动开始”的切换。调整尺寸与风格size与theme组合使用可快速适配不同视觉需求!-- 小尺寸、方形风格 -- t-count-down time{{600000}} sizesmall themesquare / !-- 中尺寸默认、圆形风格 -- t-count-down time{{600000}} themeround / !-- 大尺寸、默认风格 -- t-count-down time{{600000}} sizelarge /三档尺寸的视觉规格可在 count-down.wxss 中查到small数字块为 40rpx、medium为 48rpx、large为 56rpxround/square主题下数字块为正方形背景块default主题下仅显示数字与冒号文本。七、源码原理倒计时是如何驱动的理解内部实现有助于排查“跳秒”“不触发事件”等问题。核心逻辑全部集中在 count-down.js 中1. 时间轴与启动start / pause / resetstart()记录endTime Date.now() remain绝对结束时间戳随后循环调用doCount()pause()清除timeoutId并停止计数reset()先暂停再以properties.time重置remain并刷新界面若autoStart为真则立即重新启动。因此修改time属性等价于自动reset()见observers.time。2. 定时器节拍doCountdoCount()使用setTimeout(..., 33)约 33ms 一跳约 30fps。每跳通过getTime()计算Math.max(endTime - Date.now(), 0)获取真实剩余毫秒数开启millisecond时每跳都updateTime(time)实现毫秒级渲染未开启时通过isSameSecond(time, remain)utils.js 中Math.floor(t/1000)比较判断是否跨秒只有跨秒或归零才更新界面从而避免无谓的 setData、显著降低渲染开销剩余时间不为 0 时继续递归调度下一次doCount()。3. 时间数据拆分parseTimeDatautils.js 中parseTimeData按天/时/分/秒/毫秒逐级取整得到{DD, HH, mm, ss, SSS}结构毫秒仅在开启毫秒级渲染时才有实际变化。4. 卸载清理组件在lifetimes.detached中清理定时器clearTimeout避免页面销毁后定时器继续运行导致内存泄漏或 setData 报错。从实现可以看出组件基于绝对时间戳而非“每次减 1 秒”的累减方式计算因此即使发生中断剩余时间也始终精确同时秒级模式下借助“同一秒内跳过渲染”的优化兼顾了流畅度与性能。八、注意事项与最佳实践time 单位为毫秒传值前先做单位换算如 5 分钟 300000避免把秒误当毫秒导致倒计时异常长。动态修改 time 会自动重置若在倒计时过程中更新time组件会执行reset()如需“暂停后继续”应改用pause()/start()方法控制而不是重设time。自定义内容插槽将content设为非default值即可启用插槽自行渲染倒计时数字样式源码 count-down.wxml 中content ! default时会渲染具名插槽content与默认插槽。样式作用域组件开启了styleIsolation: apply-shared页面样式可作用于组件内部但更推荐通过 External Classes 或 CSS 变量定制避免类名冲突。配合数字字体若追求与官方演示一致的等宽数字排版可引入 TCloudNumber 字体资源。九、相关资源组件源码与样式count-down.js、count-down.wxml、count-down.wxss属性与类型定义props.js、type.d.ts时间解析工具utils.js组件公共基类与主题前缀common/src/index.js、common/config.js该组件位于本仓库的 miniprogram/packageAPI/components/tdesign-miniprogram/ 下可直接在微信开发者工具中导入 miniprogram-demo 项目进行真机预览与调试。赞分享示例工程小程序前端【免费下载链接】miniprogram-demo微信小程序组件 / API / 云开发示例项目地址https://gitcode.com/gh_mirrors/mi/miniprogram-demo点击查看免费下载相关推荐TDesign MiniProgram CountDown 倒计时组件完全指南从属性配置到源码实现原理TDesign MiniProgram CountDown 倒计时组件完全指南从属性配置到源码实现原理 CountDown 是 TDesign MiniPro前端UI组件小程序设计系统移动开发tdesign-miniprogram CountDown 倒计时组件实战指南属性、事件、主题样式与源码原理tdesign miniprogram CountDown 倒计时组件实战指南属性、事件、主题样式与源码原理 本文以 TDesign 小程序组件库tdesi前端UI组件小程序设计系统移动开发Vue倒计时组件 —— fengyuanchen/vue-countdownVue倒计时组件 —— fengyuanchen/vue countdown 项目基础介绍及编程语言 fengyuanchen/vue countdown 是一创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考