HarmonyOS 6 TextTimer 组件使用文档

文章目录完整示例核心概念与API1 构造入参 TextTimerOptions2 链式通用属性3 核心事件4 TextTimerController 控制器代码模块解析1 基础正计时 - 默认格式2 基础正计时 - 自定义时间格式3 倒计时模式配置4 计时状态控制区域时间格式化规则运行效果说明总结完整示例// 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%); } }运行效果如图点击开始进行倒计时点击重置回到最初核心概念与API1 构造入参 TextTimerOptions仅支持官方限定属性用于组件初始化配置isCountDown布尔类型是否开启倒计时模式默认false正计时count数值类型倒计时总时长单位毫秒controller绑定 TextTimerController 控制器用于手动控制计时timeZone配置计时时区满足多地区时间展示需求。重要规范format不属于构造入参不可写入大括号内需使用链式调用写法。2 链式通用属性用于样式定制与时间格式化全局通用写法.format()自定义时间展示格式支持hh/mm/ss/ms组合配置.fontSize()/.fontColor()控制计时文本字号与字体颜色支持 Text 组件同类文字样式属性拓展性强。3 核心事件onTimer计时周期回调事件计时运行期间持续触发回调参数为当前毫秒数可用于监听计时进度、判断倒计时结束逻辑。4 TextTimerController 控制器组件专属控制器实现计时状态手动管控start()启动/继续计时pause()暂停当前计时reset()重置计时至初始状态。代码模块解析1 基础正计时 - 默认格式无需传入任何初始化参数组件以系统默认格式hh:mm:ss.ms展示正计时开箱即用适合快速实现基础计时需求。TextTimer({}) .fontSize(26) .fontColor(#007DFF);2 基础正计时 - 自定义时间格式通过链式调用.format()自定义展示规则示例配置mm:ss仅展示分钟与秒钟精简计时展示内容适配轻量计时场景。TextTimer({}) .format(mm:ss) .fontSize(26) .fontColor(#FF6F3D);3 倒计时模式配置开启isCountDown: true切换为倒计时模式count: 30000设置总时长为30秒绑定控制器支持外部按钮控制配置mm:ss.ms格式展示分钟、秒、毫秒借助onTimer回调监听剩余时间当时间小于等于0时自动暂停计时模拟倒计时结束逻辑。4 计时状态控制区域通过 Row 横向布局放置功能按钮分别绑定控制器方法实现计时开始、暂停、重置三大核心操作交互逻辑清晰满足手动管控计时的业务需求。时间格式化规则结合官方文档TextTimer支持以下格式化关键字自由组合hh小时mm分钟ss秒钟ms毫秒组合示例完整格式hh:mm:ss.ms精简格式mm:ss高精度格式ss.ms运行效果说明页面采用垂直 Column 布局分区展示三种计时器效果布局整洁顶部为默认格式正计时实时刷新时间中部为自定义分秒格式正计时样式差异化展示底部为30秒倒计时计时结束自动暂停并打印日志配套功能按钮可自由控制倒计时的启动、暂停与重置全局配置背景色、边距、间距UI 展示美观适配移动端全尺寸设备。总结TextTimer是鸿蒙轻量级原生计时组件同时覆盖正计时、倒计时两大核心场景采用「构造初始化链式样式」的标准开发模式贴合鸿蒙 ArkTS 编码规范依托控制器与计时回调可灵活实现计时状态管控与业务逻辑拓展示例代码覆盖组件主流用法可直接复制复用快速落地各类计时类开发需求。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是持续创作的动力