CountDown 倒计时

介绍

用于实时展示倒计时数值，支持天/时/分/秒显示、中英文分割符、边框样式、自定义颜色等，并提供控制器用于手动控制倒计时的开始、暂停和重置。

引入

import { TnCountDown, TnCountDownController } from "@tuniao/tn-ui";

代码演示

基础用法

通过 time 属性设置倒计时总时长，单位为秒。默认显示 时:分:秒 格式，自动开始倒计时。

点我查看代码

TnCountDown({ time: 300 });

显示天数

通过 showDay 属性开启天数显示。当时间不足一天时默认自动隐藏天数（autoHideDay 控制）。

点我查看代码

// 1天零1小时
TnCountDown({ time: 90100, showDay: true });

只显示分秒

通过 showHour 属性控制小时的显示，设为 false 时仅显示分和秒。

点我查看代码

// 10分钟，只显示分:秒
TnCountDown({ time: 600, showHour: false });

中文分割符

通过 separatorMode 属性切换分割符模式，'cn' 为中文（天/时/分/秒），'en' 为英文冒号。

点我查看代码

// 中文分割符
TnCountDown({ time: 500, separatorMode: 'cn' });

// 中文分割符 + 显示天数
TnCountDown({ time: 86500, separatorMode: 'cn', showDay: true });

自定义颜色

通过 textColor 和 separatorColor 属性分别设置数字和分割符的颜色。支持主题色名称（如 "primary"、"danger"）和自定义色值（如 "#01beff"）。

点我查看代码

// 主题色 - primary
TnCountDown({
  time: 3700,
  textColor: "primary",
  separatorColor: "primary",
});

// 主题色 - danger
TnCountDown({
  time: 3700,
  textColor: "danger",
  separatorColor: "danger",
});

// 自定义 hex 色值
TnCountDown({
  time: 3700,
  textColor: "#01beff",
  separatorColor: "#01beff",
});

显示边框

通过 showBorder 属性为每个时间数字添加边框。可通过 itemBorderColor 自定义边框颜色。

点我查看代码

// 英文分割符 + 边框
TnCountDown({ time: 450, showBorder: true });

// 中文分割符 + 边框
TnCountDown({ time: 450, showBorder: true, separatorMode: 'cn' });

// 自定义边框颜色 + 主题色文字
TnCountDown({
  time: 450,
  showBorder: true,
  itemBorderColor: "primary",
  textColor: "primary",
  separatorColor: "primary",
});

自定义字体大小

通过 fontSize 属性设置字体大小，单位为 vp。不设置时使用主题默认字体大小。

点我查看代码

TnCountDown({ time: 360, fontSize: 12 });
TnCountDown({ time: 360, fontSize: 20 });
TnCountDown({ time: 360, fontSize: 28 });

手动控制

通过 controller 属性传入 TnCountDownController 实例，配合 autoStart: false 实现手动控制倒计时的开始、暂停和重置。

类型说明

TnCountDownController 控制器方法：

方法名	说明	参数
start	开始倒计时	-
pause	暂停倒计时	-
reset	重置倒计时，可传入新的时间（秒）	time?: number

点我查看代码

@ComponentV2
struct CountDownDemo {
  @Local controller: TnCountDownController = new TnCountDownController();
  @Local statusText: string = "未开始";

  build() {
    Column({ space: 12 }) {
      Text(`状态：${this.statusText}`);

      TnCountDown({
        time: 600,
        autoStart: false,
        controller: this.controller,
        textColor: "primary",
        fontSize: 20,
        separatorColor: "primary",
        onStart: () => {
          this.statusText = "倒计时中";
        },
        onEnd: () => {
          this.statusText = "已结束";
        },
      });

      Row({ space: 12 }) {
        TnButton({
          content: "开始",
          btnSize: "sm",
          type: "primary",
          onBtnClick: () => {
            this.controller.start();
            this.statusText = "倒计时中";
          },
        });
        TnButton({
          content: "暂停",
          btnSize: "sm",
          type: "warning",
          onBtnClick: () => {
            this.controller.pause();
            this.statusText = "已暂停";
          },
        });
        TnButton({
          content: "重置",
          btnSize: "sm",
          type: "info",
          onBtnClick: () => {
            this.controller.reset();
            this.statusText = "未开始";
          },
        });
      }
    }
  }
}

API

Props

参数	说明	类型	默认值
time	倒计时时长，单位秒	number	0
autoStart	是否自动开始倒计时	boolean	true
textColor	数字文字颜色，支持主题色名称或自定义色值	string	-
fontSize	字体大小(vp)，不设置时使用主题默认值	number	0
showDay	是否显示天数	boolean	false
showHour	是否显示小时	boolean	true
showMinute	是否显示分钟	boolean	true
showSecond	是否显示秒数	boolean	true
autoHideDay	时间不足一天时自动隐藏天数	boolean	true
separatorMode	分割符模式	'en' | 'cn'	'en'
separatorColor	分割符颜色，支持主题色名称或自定义色值	string	-
showBorder	是否显示数字边框	boolean	false
itemBorderColor	边框颜色，支持主题色名称或自定义色值	string	-
controller	倒计时控制器	TnCountDownController	-

Events

事件名	说明	回调参数
onStart	倒计时开始时触发	-
onEnd	倒计时结束时触发	-

TnCountDownController 方法

方法名	说明	参数	返回值
start	开始倒计时	-	void
pause	暂停倒计时	-	void
reset	重置倒计时	time?: number（新的时间，单位秒，不传则使用初始值）	void