1# TextTimer 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @liyujie43--> 5<!--Designer: @weixin_52725220--> 6<!--Tester: @xiong0104--> 7<!--Adviser: @HelloCrease--> 8 9通过文本显示计时信息并控制其计时器状态的组件。 10 11组件不可见时，时间变动将停止，组件的可见状态基于[onVisibleAreaChange](./ts-universal-component-visible-area-change-event.md#onvisibleareachange)处理，可见阈值ratios大于0即视为可见状态。 12 13> **说明：** 14> 15> 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 16 17## 子组件 18 19无 20 21## 接口 22 23TextTimer(options?: TextTimerOptions) 24 25**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 26 27**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 28 29**系统能力：** SystemCapability.ArkUI.ArkUI.Full 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| -------- | -------- | -------- | -------- | 35| options | [TextTimerOptions](#texttimeroptions对象说明)| 否 | 通过文本显示计时信息并控制其计时器状态的组件参数。 | 36 37## TextTimerOptions对象说明 38 39用于构建TextTimer组件的选项。 40 41**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 42 43**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 44 45**系统能力：** SystemCapability.ArkUI.ArkUI.Full 46 47| 名称 | 类型 | 只读 | 可选 | 说明 | 48| ----------- | -------- | -------- | -------- | -------- | 49| isCountDown | boolean | 否 | 是 | 倒计时开关。值为true时，计时器开启倒计时，例如从30秒 ~ 0秒。值为false时，计时器开始计时，例如从0秒 ~ 30秒。<br/>默认值：false | 50| count | number | 否 | 是 | 计时器时间（isCountDown为true时生效），单位为毫秒。最长不超过86400000毫秒（24小时）。 0<count<86400000时，count值为计时器初始值。否则，使用默认值为计时器初始值。<br/>默认值：60000 | 51| controller | [TextTimerController](#texttimercontroller) | 否 | 是 | TextTimer控制器。 | 52 53## 属性 54 55除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 56 57### format 58 59format(value: string) 60 61设置自定义格式，需至少包含一个HH、mm、ss、SS中的关键字。使用yy、MM、dd等日期格式时，使用默认值。 62 63计时器更新频率按format最小单位处理，例如：format设置为'HH:mm'时，更新频率为一分钟。 64 65**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 66 67**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 68 69**系统能力：** SystemCapability.ArkUI.ArkUI.Full 70 71**参数：** 72 73| 参数名 | 类型 | 必填 | 说明 | 74| ------ | ------ | ---- | -------------------------------------- | 75| value | string | 是 | 自定义格式。<br/>默认值：'HH:mm:ss.SS' | 76 77 78### fontColor 79 80fontColor(value: ResourceColor) 81 82设置字体颜色。 83 84**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 85 86**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 87 88**系统能力：** SystemCapability.ArkUI.ArkUI.Full 89 90**参数：** 91 92| 参数名 | 类型 | 必填 | 说明 | 93| ------ | ------------------------------------------ | ---- | ---------- | 94| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 字体颜色。 | 95 96### fontSize 97 98fontSize(value: Length) 99 100设置字体大小。 101 102**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 103 104**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 105 106**系统能力：** SystemCapability.ArkUI.ArkUI.Full 107 108**参数：** 109 110| 参数名 | 类型 | 必填 | 说明 | 111| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 112| value | [Length](ts-types.md#length) | 是 | 字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。不支持设置百分比字符串。 | 113 114### fontStyle 115 116fontStyle(value: FontStyle) 117 118设置字体样式。 119 120**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 121 122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ------ | ------------------------------------------- | ---- | --------------------------------------- | 130| value | [FontStyle](ts-appendix-enums.md#fontstyle) | 是 | 字体样式。<br/>默认值：FontStyle.Normal | 131 132### fontWeight 133 134fontWeight(value: number | FontWeight | ResourceStr) 135 136设置文本的字体粗细，设置过大可能会导致不同字体下的文字出现截断。 137 138**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 139 140**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 141 142**系统能力：** SystemCapability.ArkUI.ArkUI.Full 143 144**参数：** 145 146| 参数名 | 类型 | 必填 | 说明 | 147| ------ | ---------- | ------ | ----------------- | 148| value | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| [ResourceStr](ts-types.md#resourcestr) | 是 | 文本的字体粗细，number类型取值范围为[100, 900]，取值间隔为100，取值越大，字体越粗。number类型取值范围外的默认值为400。[ResourceStr](ts-types.md#resourcestr)类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、"bolder"、"lighter"、"regular"、"medium"，分别对应FontWeight中相应的枚举值。<br/>默认值：FontWeight.Normal <br>从API version 20开始，支持Resource类型。| 149 150### fontFamily 151 152fontFamily(value: ResourceStr) 153 154设置字体列表。 155 156**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 157 158**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 159 160**系统能力：** SystemCapability.ArkUI.ArkUI.Full 161 162**参数：** 163 164| 参数名 | 类型 | 必填 | 说明 | 165| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | 166| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 字体列表。默认字体为'HarmonyOS Sans'。<br>应用当前支持'HarmonyOS Sans'字体和[注册自定义字体](../js-apis-font.md)。<br>卡片当前仅支持'HarmonyOS Sans'字体。 | 167 168### textShadow<sup>11+</sup> 169 170textShadow(value: ShadowOptions | Array<ShadowOptions>) 171 172设置文字阴影效果。该接口支持以数组形式入参，实现多重文字阴影。不支持fill字段, 不支持智能取色模式。 173 174**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 175 176**系统能力：** SystemCapability.ArkUI.ArkUI.Full 177 178**参数：** 179 180| 参数名 | 类型 | 必填 | 说明 | 181| ------ | ------------------------------------------------------------ | ---- | -------------- | 182| value | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| Array<[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明)> | 是 | 文字阴影效果。 | 183 184### contentModifier<sup>12+</sup> 185 186contentModifier(modifier: ContentModifier\<TextTimerConfiguration>) 187 188定制TextTimer内容区的方法。 189 190**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 191 192**系统能力：** SystemCapability.ArkUI.ArkUI.Full 193 194**参数：** 195 196| 参数名 | 类型 | 必填 | 说明 | 197| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 198| modifier | [ContentModifier\<TextTimerConfiguration>](#texttimerconfiguration12对象说明) | 是 | 在TextTimer组件上，定制内容区的方法。<br/>modifier： 内容修改器，开发者需要自定义class实现ContentModifier接口。 | 199 200## 事件 201 202### onTimer 203 204onTimer(event: (utc: number, elapsedTime: number) => void) 205 206时间文本发生变化时触发该事件。锁屏状态和应用后台状态下不会触发该事件。 207设置高精度的format（SSS、SS）时，回调间隔可能会出现波动。 208 209**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 210 211**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 212 213**系统能力：** SystemCapability.ArkUI.ArkUI.Full 214 215**参数：** 216 217| 参数名 | 类型 | 必填 | 说明 | 218| ----------- | ------ | ---- | ------------------------------------------------------------ | 219| utc | number | 是 | Linux时间戳，即自1970年1月1日起经过的时间，单位为设置格式的最小单位。 | 220| elapsedTime | number | 是 | 计时器经过的时间，单位为设置格式的最小单位。 | 221 222## TextTimerController 223 224TextTimer组件的控制器，用于控制文本计时器。一个TextTimer组件仅支持绑定一个控制器，组件创建完成后相关指令才能被调用。 225 226**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 227 228**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 229 230### 导入对象 231 232``` 233textTimerController: TextTimerController = new TextTimerController(); 234``` 235 236### constructor 237 238constructor() 239 240TextTimerController的构造函数。 241 242**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 243 244**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 245 246**系统能力：** SystemCapability.ArkUI.ArkUI.Full 247 248### start 249 250start() 251 252计时开始。 253 254**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 255 256**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 257 258**系统能力：** SystemCapability.ArkUI.ArkUI.Full 259 260### pause 261 262pause() 263 264计时暂停。 265 266**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 267 268**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 269 270**系统能力：** SystemCapability.ArkUI.ArkUI.Full 271 272### reset 273 274reset() 275 276重置计时器。 277 278**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 279 280**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 281 282**系统能力：** SystemCapability.ArkUI.ArkUI.Full 283 284## TextTimerConfiguration<sup>12+</sup>对象说明 285 286ContentModifier接口使用的TextTimer配置。 287 288开发者需要自定义class实现ContentModifier接口。 289 290**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 291 292**系统能力：** SystemCapability.ArkUI.ArkUI.Full 293 294| 名称 | 类型 | 只读 | 可选 | 说明 | 295| ------ | ------ | ------ | ------ |-------------------------------- | 296| count | number | 否 | 否 | 计时器时间（isCountDown为true时生效），单位为毫秒。最长不超过86400000毫秒（24小时）。 0<count<86400000时，count值为倒计时初始值。否则，使用默认值为倒计时初始值。<br> 默认值：60000。 | 297| isCountDown | boolean| 否 | 否 | 是否倒计时。值为true时，计时器开启倒计时，例如从30秒 ~ 0秒。值为false时，计时器开始计时，例如从0秒 ~ 30秒。<br> 默认值：false | 298| started | boolean | 否 | 否 | 是否已经开始了计时。默认值：false， 表示未开始计时。| 299| elapsedTime | number | 否 | 否 |计时器经过的时间，单位为设置格式的最小单位。 | 300 301## 示例 302### 示例1（支持手动启停的文本计时器） 303 304该示例展示了TextTimer组件的基本使用方法，通过[format](#format)属性设置计时器的文本显示格式。 305 306用户可以通过点击"start"、"pause"、"reset"按钮，开启、暂停、重置计时器。 307 308```ts 309// xxx.ets 310@Entry 311@Component 312struct TextTimerExample { 313 textTimerController: TextTimerController = new TextTimerController(); 314 @State format: string = 'mm:ss.SS'; 315 316 build() { 317 Column() { 318 TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController }) 319 .format(this.format) 320 .fontColor(Color.Black) 321 .fontSize(50) 322 .onTimer((utc: number, elapsedTime: number) => { 323 console.info('textTimer notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime); 324 }) 325 Row() { 326 Button("start").onClick(() => { 327 this.textTimerController.start(); 328 }) 329 Button("pause").onClick(() => { 330 this.textTimerController.pause(); 331 }) 332 Button("reset").onClick(() => { 333 this.textTimerController.reset(); 334 }) 335 } 336 } 337 } 338} 339``` 340 341 342 343 344### 示例2（设定文本阴影样式） 345 346该示例通过[textShadow](#textshadow11)属性设置计时器的文本阴影样式。 347 348``` ts 349// xxx.ets 350@Entry 351@Component 352struct TextTimerExample { 353 @State textShadows: ShadowOptions | Array<ShadowOptions> = [{ 354 radius: 10, 355 color: Color.Red, 356 offsetX: 10, 357 offsetY: 0 358 }, { 359 radius: 10, 360 color: Color.Black, 361 offsetX: 20, 362 offsetY: 0 363 }, { 364 radius: 10, 365 color: Color.Brown, 366 offsetX: 30, 367 offsetY: 0 368 }, { 369 radius: 10, 370 color: Color.Green, 371 offsetX: 40, 372 offsetY: 0 373 }, { 374 radius: 10, 375 color: Color.Yellow, 376 offsetX: 100, 377 offsetY: 0 378 }]; 379 380 build() { 381 Column({ space: 8 }) { 382 TextTimer().fontSize(50).textShadow(this.textShadows) 383 } 384 } 385} 386``` 387 388 389### 示例3（设定自定义内容区） 390 391该示例实现了两个简易秒表，使用浅灰色背景。计时器开始后，会实时显示时间变化。倒计时器开始后，背景会变成黑色，正计时器开始后，背景会变成灰色。 392 393``` ts 394// xxx.ets 395class MyTextTimerModifier implements ContentModifier<TextTimerConfiguration> { 396 constructor() { 397 } 398 399 applyContent(): WrappedBuilder<[TextTimerConfiguration]> { 400 return wrapBuilder(buildTextTimer); 401 } 402} 403 404@Builder 405function buildTextTimer(config: TextTimerConfiguration) { 406 Column() { 407 Stack({ alignContent: Alignment.Center }) { 408 Circle({ width: 150, height: 150 }) 409 .fill(config.started ? (config.isCountDown ? 0xFF232323 : 0xFF717171) : 0xFF929292) 410 Column() { 411 Text(config.isCountDown ? "倒计时" : "正计时").fontColor(Color.White) 412 Text( 413 (config.isCountDown ? "剩余" : "已经过去了") + (config.isCountDown ? 414 (Math.max(config.count / 1000 - config.elapsedTime / 100, 0)).toFixed(1) + "/" + 415 (config.count / 1000).toFixed(0) 416 : ((config.elapsedTime / 100).toFixed(0)) 417 ) + "秒" 418 ).fontColor(Color.White) 419 } 420 } 421 } 422} 423 424@Entry 425@Component 426struct Index { 427 @State count: number = 10000; 428 @State myTimerModifier: MyTextTimerModifier = new MyTextTimerModifier(); 429 countDownTextTimerController: TextTimerController = new TextTimerController(); 430 countUpTextTimerController: TextTimerController = new TextTimerController(); 431 432 build() { 433 Row() { 434 Column() { 435 TextTimer({ isCountDown: true, count: this.count, controller: this.countDownTextTimerController }) 436 .contentModifier(this.myTimerModifier) 437 .onTimer((utc: number, elapsedTime: number) => { 438 console.info('textTimer onTimer utc is：' + utc + ', elapsedTime: ' + elapsedTime); 439 }) 440 .margin(10) 441 TextTimer({ isCountDown: false, controller: this.countUpTextTimerController }) 442 .contentModifier(this.myTimerModifier) 443 .onTimer((utc: number, elapsedTime: number) => { 444 console.info('textTimer onTimer utc is：' + utc + ', elapsedTime: ' + elapsedTime); 445 }) 446 Row() { 447 Button("start").onClick(() => { 448 this.countDownTextTimerController.start(); 449 this.countUpTextTimerController.start(); 450 }).margin(10) 451 Button("pause").onClick(() => { 452 this.countDownTextTimerController.pause(); 453 this.countUpTextTimerController.pause(); 454 }).margin(10) 455 Button("reset").onClick(() => { 456 this.countDownTextTimerController.reset(); 457 this.countUpTextTimerController.reset(); 458 }).margin(10) 459 }.margin(20) 460 }.width('100%') 461 }.height('100%') 462 } 463} 464``` 465 466 467### 示例4（创建之后立即执行计时） 468 469该示例展示了TextTimer计时器如何在创建完成之后立即开始计时。 470 471``` ts 472// xxx.ets 473@Entry 474@Component 475struct TextTimerStart { 476 textTimerController: TextTimerController = new TextTimerController(); 477 @State format: string = 'mm:ss.SS'; 478 479 build() { 480 Column() { 481 Scroll() 482 .height('20%') 483 TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController }) 484 .format(this.format) 485 .fontColor(Color.Black) 486 .fontSize(50) 487 .onTimer((utc: number, elapsedTime: number) => { 488 console.info('textTimer notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime); 489 }) 490 .onAppear(() => { 491 this.textTimerController.start(); 492 }) 493 } 494 } 495} 496``` 497
