1# TextTimer 2 3The **TextTimer** component displays timing information and is controlled in text format. 4 5The time updates stop when the component is invisible. The component's visibility is determined by the value of **ratios** in the [onVisibleAreaChange](./ts-universal-component-visible-area-change-event.md#onvisibleareachange) event callback: If the value is greater than 0, the component is visible. 6 7> **NOTE** 8> 9> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 10 11## Child Components 12 13Not supported 14 15## APIs 16 17TextTimer(options?: TextTimerOptions) 18 19**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 20 21**Atomic service API**: This API can be used in atomic services since API version 11. 22 23**System capability**: SystemCapability.ArkUI.ArkUI.Full 24 25**Parameters** 26 27| Name| Type| Mandatory| Description| 28| -------- | -------- | -------- | -------- | 29| options | [TextTimerOptions](#texttimeroptions)| No| Parameters of the **TextTimer** component.| 30 31## TextTimerOptions 32 33**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 34 35**Atomic service API**: This API can be used in atomic services since API version 11. 36 37**System capability**: SystemCapability.ArkUI.ArkUI.Full 38 39| Name | Type | Mandatory | Description | 40| ----------- | -------- | -------- | -------- | 41| isCountDown | boolean | No | Whether the timer is a countdown. The value **true** means that the timer counts up, and **false** means that the timer counts down.<br>Default value: **false**| 42| count | number | No | Timer duration, in milliseconds. It is effective only when **isCountDown** is **true**. The maximum value is 86400000 ms (24 hours). If 0 < **count** < 86400000, **count** is the initial value of the timer. Otherwise, the default value is used as the initial value.<br>Default value: **60000**| 43| controller | [TextTimerController](#texttimercontroller) | No | **TextTimer** controller.| 44 45## Attributes 46 47In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 48 49### format 50 51format(value: string) 52 53Sets the custom format. The value must contain at least one of the following keywords: **HH**, mm, **ss**, and **SS**. If the specified date format is yy, MM, or dd, the default value is used instead. 54 55**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 56 57**Atomic service API**: This API can be used in atomic services since API version 11. 58 59**System capability**: SystemCapability.ArkUI.ArkUI.Full 60 61**Parameters** 62 63| Name| Type | Mandatory| Description | 64| ------ | ------ | ---- | -------------------------------------- | 65| value | string | Yes | Custom format<br>Default value: **'HH:mm:ss.SS'**| 66 67 68### fontColor 69 70fontColor(value: ResourceColor) 71 72Sets the font color. 73 74**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 75 76**Atomic service API**: This API can be used in atomic services since API version 11. 77 78**System capability**: SystemCapability.ArkUI.ArkUI.Full 79 80**Parameters** 81 82| Name| Type | Mandatory| Description | 83| ------ | ------------------------------------------ | ---- | ---------- | 84| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Font color.| 85 86### fontSize 87 88fontSize(value: Length) 89 90Sets the font size. 91 92**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 93 94**Atomic service API**: This API can be used in atomic services since API version 11. 95 96**System capability**: SystemCapability.ArkUI.ArkUI.Full 97 98**Parameters** 99 100| Name| Type | Mandatory| Description | 101| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 102| value | [Length](ts-types.md#length) | Yes | Font size. If **fontSize** is of the number type, the unit fp is used. The default font size is 16 fp. The value cannot be a percentage.| 103 104### fontStyle 105 106fontStyle(value: FontStyle) 107 108Sets the font style. 109 110**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 111 112**Atomic service API**: This API can be used in atomic services since API version 11. 113 114**System capability**: SystemCapability.ArkUI.ArkUI.Full 115 116**Parameters** 117 118| Name| Type | Mandatory| Description | 119| ------ | ------------------------------------------- | ---- | --------------------------------------- | 120| value | [FontStyle](ts-appendix-enums.md#fontstyle) | Yes | Font style.<br>Default value: **FontStyle.Normal**| 121 122### fontWeight 123 124fontWeight(value: number | FontWeight | string) 125 126Sets the font weight. If the value is too large, the text may be clipped depending on the font. 127 128**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 129 130**Atomic service API**: This API can be used in atomic services since API version 11. 131 132**System capability**: SystemCapability.ArkUI.ArkUI.Full 133 134**Parameters** 135 136| Name| Type | Mandatory| Description | 137| ------ | ---------- | ------ | ----------------- | 138| value | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | Yes | Font weight. For the number type, the value range is [100, 900], at an interval of 100. The default value is **400**. A larger value indicates a heavier font weight. For the string type, only strings that represent a number, for example, **400**, and the following enumerated values of **FontWeight** are supported: **bold**, **bolder**, **lighter**, **regular**, and **medium**.<br>Default value: **FontWeight.Normal**| 139 140### fontFamily 141 142fontFamily(value: ResourceStr) 143 144Sets the font family. 145 146**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 147 148**Atomic service API**: This API can be used in atomic services since API version 11. 149 150**System capability**: SystemCapability.ArkUI.ArkUI.Full 151 152**Parameters** 153 154| Name| Type | Mandatory| Description | 155| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | 156| value | [ResourceStr](ts-types.md#resourcestr) | Yes | Font family. Default font: **'HarmonyOS Sans'**<br>The 'HarmonyOS Sans' font and [registered custom fonts](../js-apis-font.md) are supported for applications.<br>Only the 'HarmonyOS Sans' font is supported for widgets.| 157 158### textShadow<sup>11+</sup> 159 160textShadow(value: ShadowOptions | Array<ShadowOptions>) 161 162Sets the text shadow. It supports input parameters in an array to implement multiple text shadows. This API does not work with the **fill** attribute or coloring strategy. 163 164**Atomic service API**: This API can be used in atomic services since API version 12. 165 166**System capability**: SystemCapability.ArkUI.ArkUI.Full 167 168**Parameters** 169 170| Name| Type | Mandatory| Description | 171| ------ | ------------------------------------------------------------ | ---- | -------------- | 172| value | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| Array<[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions)> | Yes | Text shadow.| 173 174### contentModifier<sup>12+</sup> 175 176contentModifier(modifier: ContentModifier\<TextTimerConfiguration>) 177 178Creates a content modifier. 179 180**Atomic service API**: This API can be used in atomic services since API version 12. 181 182**System capability**: SystemCapability.ArkUI.ArkUI.Full 183 184**Parameters** 185 186| Name| Type | Mandatory| Description | 187| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 188| modifier | [ContentModifier\<TextTimerConfiguration>](#texttimerconfiguration12) | Yes | Content modifier to apply to the **TextTimer** component.<br>**modifier**: content modifier. You need a custom class to implement the **ContentModifier** API.| 189 190## Events 191 192### onTimer 193 194onTimer(event: (utc: number, elapsedTime: number) => void) 195 196Triggered when the time text changes. This event is not triggered when the screen is locked or the application is running in the background. 197When high-precision formats (such as **SSS** or **SS**) are used, the callback interval may vary. 198 199**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 200 201**Atomic service API**: This API can be used in atomic services since API version 11. 202 203**System capability**: SystemCapability.ArkUI.ArkUI.Full 204 205**Parameters** 206 207| Name | Type | Mandatory| Description | 208| ----------- | ------ | ---- | ------------------------------------------------------------ | 209| utc | number | Yes | Linux timestamp, which is the amount of time that has elapsed since January 1, 1970, in the minimum unit of the format.| 210| elapsedTime | number | Yes | Elapsed time of the timer, in the minimum unit of the format. | 211 212## TextTimerController 213 214Implements a controller for controlling the **TextTimer** component. A **TextTimer** component can only be bound to one controller, and the relevant commands can only be called after the component has been created. 215 216**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 217 218**Atomic service API**: This API can be used in atomic services since API version 11. 219 220### Objects to Import 221 222``` 223textTimerController: TextTimerController = new TextTimerController() 224``` 225 226### constructor 227 228constructor() 229 230A constructor used to create a **TextTimerController** object. 231 232**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 233 234**Atomic service API**: This API can be used in atomic services since API version 11. 235 236**System capability**: SystemCapability.ArkUI.ArkUI.Full 237 238### start 239 240start() 241 242Starts the timer. 243 244**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 245 246**Atomic service API**: This API can be used in atomic services since API version 11. 247 248**System capability**: SystemCapability.ArkUI.ArkUI.Full 249 250### pause 251 252pause() 253 254Pauses the timer. 255 256**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 257 258**Atomic service API**: This API can be used in atomic services since API version 11. 259 260**System capability**: SystemCapability.ArkUI.ArkUI.Full 261 262### reset 263 264reset() 265 266Resets the timer. 267 268**Widget capability**: Since API version 10, this API is supported in ArkTS widgets. 269 270**Atomic service API**: This API can be used in atomic services since API version 11. 271 272**System capability**: SystemCapability.ArkUI.ArkUI.Full 273 274## TextTimerConfiguration<sup>12+</sup> 275 276You need a custom class to implement the **ContentModifier** API. 277 278**Atomic service API**: This API can be used in atomic services since API version 12. 279 280**System capability**: SystemCapability.ArkUI.ArkUI.Full 281 282| Name| Type | Mandatory | Description | 283| ------ | ------ | ------ |-------------------------------- | 284| count | number | Yes| Timer duration, in milliseconds. It is effective only when **isCountDown** is **true**. The maximum value is 86400000 ms (24 hours). If the value is between 0 and 86,400,000, it is used as the initial countdown time. Otherwise, the default value is used as the initial countdown time.<br> Default value: **60000**| 285| isCountDown | boolean| Yes| Whether the timer is a countdown. The value **true** means that the timer counts up, and **false** means that the timer counts down.<br> Default value: **false**| 286| started | boolean | Yes| Whether the timer has already started.| 287| elapsedTime | number | Yes| Elapsed time of the timer, in the minimum unit of the format.| 288 289## Example 290### Example 1: Implementing a Text Timer with Start, Pause, and Reset Buttons 291 292This example demonstrates the basic usage of the **TextTimer** component, setting the timer display format using the **format** attribute. 293 294Users can start, pause, and reset the timer by clicking the **start**, **pause**, and **reset** buttons. 295 296```ts 297// xxx.ets 298@Entry 299@Component 300struct TextTimerExample { 301 textTimerController: TextTimerController = new TextTimerController() 302 @State format: string = 'mm:ss.SS' 303 304 build() { 305 Column() { 306 TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController }) 307 .format(this.format) 308 .fontColor(Color.Black) 309 .fontSize(50) 310 .onTimer((utc: number, elapsedTime: number) => { 311 console.info('textTimer notCountDown utc is: ' + utc + ', elapsedTime: ' + elapsedTime) 312 }) 313 Row() { 314 Button("start").onClick(() => { 315 this.textTimerController.start() 316 }) 317 Button("pause").onClick(() => { 318 this.textTimerController.pause() 319 }) 320 Button("reset").onClick(() => { 321 this.textTimerController.reset() 322 }) 323 } 324 } 325 } 326} 327``` 328 329 330 331 332### Example 2: Setting the Text Shadow Style 333 334This example shows how to set the text shadow style for the timer using the **textShadow** attribute. 335 336``` ts 337// xxx.ets 338@Entry 339@Component 340struct TextTimerExample { 341 @State textShadows: ShadowOptions | Array<ShadowOptions> = [{ 342 radius: 10, 343 color: Color.Red, 344 offsetX: 10, 345 offsetY: 0 346 }, { 347 radius: 10, 348 color: Color.Black, 349 offsetX: 20, 350 offsetY: 0 351 }, { 352 radius: 10, 353 color: Color.Brown, 354 offsetX: 30, 355 offsetY: 0 356 }, { 357 radius: 10, 358 color: Color.Green, 359 offsetX: 40, 360 offsetY: 0 361 }, { 362 radius: 10, 363 color: Color.Yellow, 364 offsetX: 100, 365 offsetY: 0 366 }] 367 368 build() { 369 Column({ space: 8 }) { 370 TextTimer().fontSize(50).textShadow(this.textShadows) 371 } 372 } 373} 374``` 375 376 377### Example 3: Configuring the Custom Content Area 378 379This example showcases two simple **TextTimer** components set against a light gray background. Once the timers are activated, they display the time progression in real-time. When the countdown timer starts, the background turns black; when the count-up timer starts, the background turns gray. 380 381``` ts 382// xxx.ets 383class MyTextTimerModifier implements ContentModifier<TextTimerConfiguration> { 384 constructor() { 385 } 386 387 applyContent(): WrappedBuilder<[TextTimerConfiguration]> { 388 return wrapBuilder(buildTextTimer) 389 } 390} 391 392@Builder 393function buildTextTimer(config: TextTimerConfiguration) { 394 Column() { 395 Stack({ alignContent: Alignment.Center }) { 396 Circle({ width: 150, height: 150 }) 397 .fill(config.started ? (config.isCountDown ? 0xFF232323 : 0xFF717171) : 0xFF929292) 398 Column() { 399 Text(config.isCountDown ? "Countdown" : "Count-up").fontColor(Color.White) 400 Text( 401 (config.isCountDown ? "Remaining" : "Elapsed") + (config.isCountDown ? 402 (Math.max(config.count / 1000 - config.elapsedTime / 100, 0)).toFixed(1) + "/" + 403 (config.count / 1000).toFixed(0) 404 : ((config.elapsedTime / 100).toFixed(0)) 405 ) + "s" 406 ).fontColor(Color.White) 407 } 408 } 409 } 410} 411 412@Entry 413@Component 414struct Index { 415 @State count: number = 10000 416 @State myTimerModifier: MyTextTimerModifier = new MyTextTimerModifier() 417 countDownTextTimerController: TextTimerController = new TextTimerController() 418 countUpTextTimerController: TextTimerController = new TextTimerController() 419 420 build() { 421 Row() { 422 Column() { 423 TextTimer({ isCountDown: true, count: this.count, controller: this.countDownTextTimerController }) 424 .contentModifier(this.myTimerModifier) 425 .onTimer((utc: number, elapsedTime: number) => { 426 console.info('textTimer onTimer utc is:' + utc + ', elapsedTime: ' + elapsedTime) 427 }) 428 .margin(10) 429 TextTimer({ isCountDown: false, controller: this.countUpTextTimerController }) 430 .contentModifier(this.myTimerModifier) 431 .onTimer((utc: number, elapsedTime: number) => { 432 console.info('textTimer onTimer utc is:' + utc + ', elapsedTime: ' + elapsedTime) 433 }) 434 Row() { 435 Button("start").onClick(() => { 436 this.countDownTextTimerController.start() 437 this.countUpTextTimerController.start() 438 }).margin(10) 439 Button("pause").onClick(() => { 440 this.countDownTextTimerController.pause() 441 this.countUpTextTimerController.pause() 442 }).margin(10) 443 Button("reset").onClick(() => { 444 this.countDownTextTimerController.reset() 445 this.countUpTextTimerController.reset() 446 }).margin(10) 447 }.margin(20) 448 }.width('100%') 449 }.height('100%') 450 } 451} 452``` 453 454 455### Example 4: Enabling the Timer to Start Immediately After Creation 456 457This example demonstrates how to start the **TextTimer** immediately after it is created. 458 459``` ts 460// xxx.ets 461@Entry 462@Component 463struct TextTimerStart { 464 textTimerController: TextTimerController = new TextTimerController() 465 @State format: string = 'mm:ss.SS' 466 467 build() { 468 Column() { 469 Scroll() 470 .height('20%') 471 TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController }) 472 .format(this.format) 473 .fontColor(Color.Black) 474 .fontSize(50) 475 .onTimer((utc: number, elapsedTime: number) => { 476 console.info('textTimer notCountDown utc is: ' + utc + ', elapsedTime: ' + elapsedTime) 477 }) 478 .onAppear(() => { 479 this.textTimerController.start() 480 }) 481 } 482 } 483} 484``` 485 486
