HarmonyOS Next 自定义计时器组件详解原创

我的口味

发布于 2025-3-31 11:43

浏览

0收藏

背景介绍

在日常UI开发中，经常会用到计时控件，比如播放视频是的时间进度显示以及音视频通话时显示的通话时长，都需要用到正计时的计时控件。还有些场景会用到倒计时的计时控件，设置一个最大时间，开始倒计时。在Android中我们一般使用TextView，配合Handler来更新TextView实现计时效果。HarmonyOS Next提供了TextTimer组件来实现计时效果。下面先介绍TextTimer能力。

TextTimer 介绍

TextTimer 是一个通过文本显示计时信息并控制其计时器状态的组件。在组件不可见时时间变动将停止，组件的可见状态基于onVisibleAreaChange处理，可见阈值ratios大于0即视为可见状态。

属性介绍

format(value: string)：设置自定义格式，需至少包含一个HH、mm、ss、SS中的关键字。如使用yy、MM、dd等日期格式，则使用默认值。
fontColor(value: ResourceColor)：设置字体颜色。
fontWeight (value: number | FontWeight | string)：设置文本的字体粗细，设置过大可能会在不同字体下有截断。number 类型取值 [100, 900]，取值间隔为 100，默认为 400，取值越大，字体越粗。string 类型仅支持 number 类型取值的字符串形式（例如 “400”），以及 “bold”、“bolder”、“lighter”、“regular”、“medium”，分别对应 FontWeight 中相应的枚举值。
fontFamily (value: ResourceStr)：设置字体列表，默认字体为 ‘HarmonyOS Sans’。应用当前支持 ‘HarmonyOS Sans’ 字体和注册自定义字体，卡片当前仅支持 ‘HarmonyOS Sans’ 字体。
textShadow(value: ShadowOptions | Array<ShadowOptions>)：设置文字阴影效果，该接口支持以数组形式入参实现多重文字阴影，不支持 fill 字段，不支持智能取色模式。
contentModifier(modifier: ContentModifier<TextTimerConfiguration>)：定制 TextTimer 内容区的方法，modifier 为内容修改器，开发者需要自定义 class 实现 ContentModifier 接口。

TextTimer构造中需要传入TextTimerOptions对象，TextTimerOptions包含下面属性：

名称	类型	必填	说明
isCountDown	boolean	否	是否倒计时。值为true时，计时器开启倒计时，值为false时，计时器开始计时。默认值：false
count	number	否	计时器时间（isCountDown为true时生效），单位为毫秒。最长不超过86400000毫秒（24小时）。 0<count<86400000时，count值为计时器初始值。否则，使用默认值为计时器初始值。默认值：60000
controller	TextTimerController	否	TextTimer控制器。

其中TextTimerController 主要用于控制计时器的开启、暂停等：

start()：计时开始。
pause()：计时暂停。
reset()：重置计时器。

事件介绍

主要包含onTimer事件：

onTimer (event: (utc: number, elapsedTime: number) => void)：时间文本发生变化时触发，锁屏状态和应用后台状态下不会触发该事件。设置高精度的 format（SSS、SS）时，回调间隔可能会出现波动。参数 utc 为 Linux 时间戳，即自 1970 年 1 月 1 日起经过的时间，单位为设置格式的最小单位；elapsedTime 为计时器经过的时间，单位为设置格式的最小单位。

使用示例

示例一：按钮控制计时器

@Entry
@Component
struct TextTimerExample {
  textTimerController: TextTimerController = new TextTimerController()
  @State format: string = 'mm:ss.SS'

  build() {
    Column() {
      TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController })
        .format(this.format)
        .fontColor(Color.Black)
        .fontSize(50)
        .onTimer((utc: number, elapsedTime: number) => {
          console.info('textTimer notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime)
        })
      Row() {
        Button("start").onClick(() => {
          this.textTimerController.start()
        })
        Button("pause").onClick(() => {
          this.textTimerController.pause()
        })
        Button("reset").onClick(() => {
          this.textTimerController.reset()
        })
      }
    }
  }
}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.

效果：
HarmonyOS Next 自定义计时器组件详解-鸿蒙开发者社区

示例二：自动执行计时

@Entry
@Component
struct TextTimerStart {
  textTimerController: TextTimerController = new TextTimerController()
  @State format: string = 'mm:ss.SS'

  build() {
    Column() {
      Scroll()
        .height('20%')
      TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController })
        .format(this.format)
        .fontColor(Color.Black)
        .fontSize(50)
        .onTimer((utc: number, elapsedTime: number) => {
          console.info('textTimer notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime)
        })
        .onAppear(() => {
          this.textTimerController.start()
        })
    }
  }
}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.

HarmonyOS Next 自定义计时器组件详解-鸿蒙开发者社区

使用局限性

针对正计时场景，每次都是从0开始，有些场景我们期望从某个时间开始计时。比如针对页面切换场景，在视频通话场景，在全屏画面时和悬浮窗时是两个页面，从全屏切换到悬浮窗时希望计时是连续的而不是从0开始，怎么办？
TextTimer提供了内容区域定制的方法：contentModifier，这里需要我们实现一个 ContentModifier<TextTimerConfiguration>。

首先需要实现一个MyTextTimerModifier， applyContent方法中封装Builder方法；
在自定义Builder方法中自定义UI；
调用contentModifier将自定义的MyTextTimerModifier实现配置到TextTimer；
需要删除TextTimer的颜色和字体配置，通过自定义UI中配置
format设置会影响elapsedTime的单位
config.elapsedTime加一个初始值就实现了从某个时间开始计时
将秒转换为mm:ss格式

下面是代码示例：

  
let startTime:number = 100;  
  
function formatData(diffTimeBySecond: number): string {  
  const hours = Math.floor(diffTimeBySecond / 3600);  
  const minutes = Math.floor((diffTimeBySecond % 3600) / 60);  
  const remainingSeconds = Math.floor(diffTimeBySecond % 60);  
  
  // 补零函数  
  const pad = (num: number) => num.toString().padStart(2, '0');  
  
  return hours > 0  
    ? `${pad(hours)}:${pad(minutes)}:${pad(remainingSeconds)}`  
    : `${pad(minutes)}:${pad(remainingSeconds)}`;  
}  
class MyTextTimerModifier implements ContentModifier<TextTimerConfiguration> {  
  constructor() {  
  }  
  applyContent(): WrappedBuilder<[TextTimerConfiguration]> {  
    return wrapBuilder(buildTextTimer)  
  }  
}  
  
@Builder  
function buildTextTimer(config: TextTimerConfiguration) {  
  Column() {  
      Column() {  
        Text(formatData(config.elapsedTime + startTime)).fontColor(Color.Red)  
    }  
  }}  
  
@Entry  
@Component  
struct Index {  
  @State count: number = 10000  
  @State myTimerModifier: MyTextTimerModifier = new MyTextTimerModifier()  
  countUpTextTimerController: TextTimerController = new TextTimerController()  
  
  build() {  
    Row() {  
      Column() {  
        TextTimer({ isCountDown: false, controller: this.countUpTextTimerController })  
          .contentModifier(this.myTimerModifier)  
          .onTimer((utc: number, elapsedTime: number) => {  
            console.info('textTimer onTimer utc is：' + utc + ', elapsedTime: ' + elapsedTime)  
          })  
        Row() {  
          Button("start").onClick(() => {  
            this.countUpTextTimerController.start()  
          }).margin(10)  
          Button("pause").onClick(() => {  
            this.countUpTextTimerController.pause()  
          }).margin(10)  
          Button("reset").onClick(() => {  
            this.countUpTextTimerController.reset()  
          }).margin(10)  
        }.margin(20)  
      }.width('100%')  
    }.height('100%')  
  }  
}
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.

最终效果如下：
HarmonyOS Next 自定义计时器组件详解-鸿蒙开发者社区

分类

标签

51CTO

51CTO博客

51CTO学堂

HarmonyOS Next 自定义计时器组件详解原创

背景介绍

TextTimer 介绍

属性介绍

事件介绍

使用示例

示例一：按钮控制计时器

示例二：自动执行计时

使用局限性

目录

订阅鸿蒙技术特刊，精选内容抢先看

51CTO

51CTO博客

51CTO学堂

HarmonyOS Next 自定义计时器组件详解 原创

背景介绍

TextTimer 介绍

属性介绍

事件介绍

使用示例

示例一：按钮控制计时器

示例二：自动执行计时

使用局限性

目录

订阅鸿蒙技术特刊，精选内容抢先看

HarmonyOS Next 自定义计时器组件详解原创