鸿蒙 Next 计时器组件TextTimer的本领做个详解

背景先容

在一样平常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包含下面属性：
名称范例必填说明isCountDownboolean否是否倒计时。值为true时，计时器开启倒计时，值为false时，计时器开始计时。

默认值：falsecountnumber否计时器时间（isCountDown为true时生效），单位为毫秒。最长不超过86400000毫秒（24小时）。 0<count<86400000时，count值为计时器初始值。否则，使用默认值为计时器初始值。

默认值：60000controllerTextTimerController否TextTimer控制器。 其中TextTimerController 重要用于控制计时器的开启、暂停等：

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

变乱先容

重要包含onTimer变乱：

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

使用示例

示例一：按钮控制计时器

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

复制代码

效果：

示例二：自动执行计时

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

复制代码

使用局限性

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

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

下面是代码示例：

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

复制代码

最终效果如下：

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。