HarmonyOS 6 TextTimer 组件使用文档

完整示例

// xxx.ets @Entry @Component struct TextTimerDemo { // 计时器控制器 private timerController: TextTimerController = new TextTimerController(); build() { Column({ space: 20 }) { Text("TextTimer 官方标准演示") .fontSize(24) .fontWeight(FontWeight.Bold) .margin({ top: 20 }); // 1. 默认格式 Text("1. 默认格式").fontSize(16).fontColor("#666666"); TextTimer({}) .fontSize(26) .fontColor("#007DFF"); // 2. 自定义格式（format 用链式调用，不是构造参数） Text("2. 自定义格式 mm:ss").fontSize(16).fontColor("#666666"); TextTimer({}) .format("mm:ss") // ✅ 正确写法：链式属性 .fontSize(26) .fontColor("#FF6F3D"); // 3. 倒计时模式 Text("3. 倒计时 30 秒").fontSize(16).fontColor("#666666"); TextTimer({ isCountDown: true, count: 30000, controller: this.timerController }) .format("mm:ss.ms") // ✅ 正确写法 .fontSize(28) .fontColor("#36B37E") .onTimer((milliseconds: number) => { console.log("剩余时间：" + milliseconds); if (milliseconds <= 0) { console.log("倒计时结束"); this.timerController.pause(); } }); // 控制按钮 Row({ space: 15 }) { Button("开始").onClick(() => this.timerController.start()).backgroundColor("#007DFF"); Button("暂停").onClick(() => this.timerController.pause()).backgroundColor("#FF9800"); Button("重置").onClick(() => this.timerController.reset()).backgroundColor("#F44336"); } } .width("100%") .padding(20) .backgroundColor("#F5F5F5") .height("100%"); } }

运行效果如图：

点击开始进行倒计时：

点击重置回到最初：

核心概念与API

1 构造入参 TextTimerOptions

仅支持官方限定属性，用于组件初始化配置：

1. isCountDown：布尔类型，是否开启倒计时模式，默认false（正计时）；
2. count：数值类型，倒计时总时长，单位毫秒；
3. controller：绑定 TextTimerController 控制器，用于手动控制计时；
4. timeZone：配置计时时区，满足多地区时间展示需求。

重要规范：format不属于构造入参，不可写入大括号内，需使用链式调用写法。

2 链式通用属性

用于样式定制与时间格式化，全局通用写法：

1. .format()：自定义时间展示格式，支持hh/mm/ss/ms组合配置；
2. .fontSize()/.fontColor()：控制计时文本字号与字体颜色；
3. 支持 Text 组件同类文字样式属性，拓展性强。

3 核心事件

onTimer：计时周期回调事件，计时运行期间持续触发，回调参数为当前毫秒数，可用于监听计时进度、判断倒计时结束逻辑。

4 TextTimerController 控制器

组件专属控制器，实现计时状态手动管控：

1. start()：启动/继续计时；
2. pause()：暂停当前计时；
3. reset()：重置计时至初始状态。

代码模块解析

1 基础正计时 - 默认格式

无需传入任何初始化参数，组件以系统默认格式hh:mm:ss.ms展示正计时，开箱即用，适合快速实现基础计时需求。

TextTimer({}) .fontSize(26) .fontColor("#007DFF");

2 基础正计时 - 自定义时间格式

通过链式调用.format()自定义展示规则，示例配置mm:ss，仅展示分钟与秒钟，精简计时展示内容，适配轻量计时场景。

TextTimer({}) .format("mm:ss") .fontSize(26) .fontColor("#FF6F3D");

3 倒计时模式配置

1. 开启isCountDown: true切换为倒计时模式；
2. count: 30000设置总时长为30秒；
3. 绑定控制器，支持外部按钮控制；
4. 配置mm:ss.ms格式，展示分钟、秒、毫秒；
5. 借助onTimer回调监听剩余时间，当时间小于等于0时，自动暂停计时，模拟倒计时结束逻辑。

4 计时状态控制区域

通过 Row 横向布局放置功能按钮，分别绑定控制器方法，实现计时开始、暂停、重置三大核心操作，交互逻辑清晰，满足手动管控计时的业务需求。

时间格式化规则

结合官方文档，TextTimer支持以下格式化关键字自由组合：

• hh：小时
• mm：分钟
• ss：秒钟
• ms：毫秒

组合示例：

1. 完整格式：hh:mm:ss.ms
2. 精简格式：mm:ss
3. 高精度格式：ss.ms

运行效果说明

1. 页面采用垂直 Column 布局，分区展示三种计时器效果，布局整洁；
2. 顶部为默认格式正计时，实时刷新时间；
3. 中部为自定义分秒格式正计时，样式差异化展示；
4. 底部为30秒倒计时，计时结束自动暂停并打印日志；
5. 配套功能按钮，可自由控制倒计时的启动、暂停与重置；
6. 全局配置背景色、边距、间距，UI 展示美观，适配移动端全尺寸设备。

总结

1. TextTimer是鸿蒙轻量级原生计时组件，同时覆盖正计时、倒计时两大核心场景；
2. 采用「构造初始化+链式样式」的标准开发模式，贴合鸿蒙 ArkTS 编码规范；
3. 依托控制器与计时回调，可灵活实现计时状态管控与业务逻辑拓展；
4. 示例代码覆盖组件主流用法，可直接复制复用，快速落地各类计时类开发需求。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力