一、组件介绍

TextTimer是HarmonyOS NEXT中的一个计时器文本组件，它继承自Text组件，提供了计时和倒计时的功能。通过这个组件，我们可以方便地实现各种计时显示需求，如倒计时、定时器、时间格式化显示等功能。

二、基本概念

1. 计时模式

TextTimer支持两种计时模式：

• 倒计时模式（countdown）：从指定时间开始倒数计时
• 计时模式（countup）：从零开始向上计时

2. 时间格式

组件支持自定义时间格式，可以通过format属性设置以下占位符：

• HH: 小时数（24小时制）
• mm: 分钟数
• ss: 秒数
• SSS: 毫秒数

三、属性说明

1. 基础属性

interface TextTimerInterface {
  // 是否开始计时
  isStart?: boolean;
  // 计时模式：countdown（倒计时）或 countup（正计时）
  count?: CountType;
  // 总时长（毫秒）
  total?: number;
  // 时间格式
  format?: string;
}

2. 属性详解

1. isStart

   • 类型：boolean
   • 默认值：false
   • 说明：控制计时器的启动和停止

2. count

   • 类型：CountType（'countdown' | 'countup'）
   • 默认值：'countdown'
   • 说明：设置计时器模式

3. total

   • 类型：number
   • 默认值：无
   • 说明：设置计时总时长（毫秒）

4. format

   • 类型：string
   • 默认值：'HH:mm:ss.SSS'
   • 说明：设置时间显示格式

四、事件说明

1. onTimer

onTimer(callback: (utc: number) => void)

• 功能：计时回调事件
• 参数：utc（当前计时值，单位毫秒）
• 触发：每次计时更新时

2. onFinish

onFinish(callback: () => void)

• 功能：计时结束事件
• 触发：倒计时模式下计时结束时

五、使用方法

1. 基本用法

TextTimer({
  isStart: true,
  count: CountType.Countdown,
  total: 60000,
  format: 'mm:ss'
})
.fontSize(30)
.fontColor('#FF0000')

2. 事件处理

TextTimer({
  isStart: this.isTimerStart,
  count: CountType.Countdown,
  total: 10000
})
.onTimer((utc: number) => {
  console.info('当前计时：' + utc);
})
.onFinish(() => {
  console.info('计时结束');
})

六、最佳实践

1. 合理设置格式

   // 只显示分秒
   format: 'mm:ss'
   
   // 显示小时分秒
   format: 'HH:mm:ss'
   
   // 显示到毫秒
   format: 'HH:mm:ss.SSS'
   

2. 动态控制

   @State isStart: boolean = false;
   
   TextTimer({
     isStart: this.isStart,
     count: CountType.Countdown,
     total: 5000
   })
   .onClick(() => {
     this.isStart = !this.isStart;
   })
   

3. 状态监听

   TextTimer({
     isStart: true,
     count: CountType.Countdown,
     total: 3000
   })
   .onTimer((utc) => {
     if (utc <= 1000) {
       // 最后一秒特殊处理
       this.handleLastSecond();
     }
   })
   

   七、总结

   本教程详细介绍了HarmonyOS NEXT中TextTimer组件的使用方法，包括基本概念、属性说明、事件处理以及最佳实践。通过倒计时和计时模式的灵活使用，以及时间格式的自定义，TextTimer能够满足多种计时显示需求。结合事件监听和动态控制，开发者可以实现丰富的交互效果，提升用户体验。