1# TextTimer
2
3The **TextTimer** component displays timing information and is controlled in text format.
4
5>  **NOTE**
6>
7> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
8
9## Child Components
10
11Not supported
12
13## APIs
14
15TextTimer(options?: TextTimerOptions)
16
17**Widget capability**: Since API version 10, this API is supported in ArkTS widgets.
18
19**Atomic service API**: This API can be used in atomic services since API version 11.
20
21**Parameters**
22
23| Name| Type| Mandatory| Description|
24| -------- | -------- | -------- | -------- |
25| options |  [TextTimerOptions](#texttimeroptions)| No| Parameters of the **TextTimer** component.|
26
27## TextTimerOptions
28
29**Widget capability**: Since API version 10, this API is supported in ArkTS widgets.
30
31**Atomic service API**: This API can be used in atomic services since API version 11.
32
33| Name    | Type    | Mandatory | Description                  |
34| ----------- | -------- | -------- | -------- |
35| isCountDown | boolean  | No  | Whether to count down.<br>Default value: **false**|
36| count       | number   | No  | Countdown time, in milliseconds. This parameter is valid only when **isCountDown** is set to **true**. The maximum value is 86400000 ms (24 hours). In the case of 0 < Value of **count** < 86400000, the value of **count** is used as the initial countdown value. In other cases, the default value is used as the initial countdown value.<br>Default value: **60000**|
37| controller  | [TextTimerController](#texttimercontroller) | No | **TextTimer** controller.|
38
39## Attributes
40
41Among the [universal attributes](ts-universal-attributes-size.md) and [universal text attributes](ts-universal-attributes-text-style.md), **fontColor**, **fontSize**, **fontStyle**, **fontWeight**, and **fontFamily** are supported. In addition, the following attributes are supported.
42
43### format
44
45format(value: string)
46
47Sets 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.
48
49**Widget capability**: Since API version 10, this API is supported in ArkTS widgets.
50
51**Atomic service API**: This API can be used in atomic services since API version 11.
52
53**System capability**: SystemCapability.ArkUI.ArkUI.Full
54
55**Parameters**
56
57| Name| Type  | Mandatory| Description                                  |
58| ------ | ------ | ---- | -------------------------------------- |
59| value  | string | Yes  | Custom format<br>Default value: **'HH:mm:ss.SS'**|
60
61### textShadow<sup>11+</sup>
62
63textShadow(value: ShadowOptions | Array&lt;ShadowOptions&gt;)
64
65Sets 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.
66
67**Atomic service API**: This API can be used in atomic services since API version 12.
68
69**System capability**: SystemCapability.ArkUI.ArkUI.Full
70
71**Parameters**
72
73| Name| Type                                                        | Mandatory| Description          |
74| ------ | ------------------------------------------------------------ | ---- | -------------- |
75| value  | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| Array&lt;[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions)> | Yes  | Text shadow.|
76
77### contentModifier<sup>12+</sup>
78
79contentModifier(modifier: ContentModifier\<TextTimerConfiguration>)
80
81Creates a content modifier.
82
83**Atomic service API**: This API can be used in atomic services since API version 12.
84
85**System capability**: SystemCapability.ArkUI.ArkUI.Full
86
87**Parameters**
88
89| Name| Type                                         | Mandatory| Description                                            |
90| ------ | --------------------------------------------- | ---- | ------------------------------------------------ |
91| 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.|
92
93## Events
94
95### onTimer
96
97onTimer(event: (utc: number, elapsedTime: number) =&gt; void)
98
99Triggered when the time text changes. This event is not triggered when the screen is locked or the application is running in the background.
100
101**Widget capability**: Since API version 10, this API is supported in ArkTS widgets.
102
103**Atomic service API**: This API can be used in atomic services since API version 11.
104
105**System capability**: SystemCapability.ArkUI.ArkUI.Full
106
107**Parameters**
108
109| Name     | Type  | Mandatory| Description                                                        |
110| ----------- | ------ | ---- | ------------------------------------------------------------ |
111| 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.|
112| elapsedTime | number | Yes  | Elapsed time of the timer, in the minimum unit of the format.                |
113
114## TextTimerController
115
116Implements 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.
117
118**Widget capability**: Since API version 10, this API is supported in ArkTS widgets.
119
120**Atomic service API**: This API can be used in atomic services since API version 11.
121
122### Objects to Import
123
124```
125textTimerController: TextTimerController = new TextTimerController()
126```
127
128### start
129
130start()
131
132Starts the timer.
133
134**Widget capability**: Since API version 10, this API is supported in ArkTS widgets.
135
136**Atomic service API**: This API can be used in atomic services since API version 11.
137
138**System capability**: SystemCapability.ArkUI.ArkUI.Full
139
140### pause
141
142pause()
143
144Pauses the timer.
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### reset
153
154reset()
155
156Resets the timer.
157
158**Widget capability**: Since API version 10, this API is supported in ArkTS widgets.
159
160**Atomic service API**: This API can be used in atomic services since API version 11.
161
162**System capability**: SystemCapability.ArkUI.ArkUI.Full
163
164## TextTimerConfiguration<sup>12+</sup>
165
166You need a custom class to implement the **ContentModifier** API.
167
168**Atomic service API**: This API can be used in atomic services since API version 12.
169
170**System capability**: SystemCapability.ArkUI.ArkUI.Full
171
172| Name | Type   |    Default Value     |  Description             |
173| ------ | ------ | ------ |-------------------------------- |
174| count | number | 60000 | Countdown time, in milliseconds. This parameter is valid only when **isCountDown** is set to **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.|
175| isCountDown | boolean| false | Whether to count down.|
176| started | boolean | - | Whether the countdown has started.|
177| elapsedTime | number | - | Elapsed time of the timer, in the minimum unit of the format.|
178
179## Example
180### Example 1
181```ts
182// xxx.ets
183@Entry
184@Component
185struct TextTimerExample {
186  textTimerController: TextTimerController = new TextTimerController()
187  @State format: string = 'mm:ss.SS'
188
189  build() {
190    Column() {
191      TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController })
192        .format(this.format)
193        .fontColor(Color.Black)
194        .fontSize(50)
195        .onTimer((utc: number, elapsedTime: number) => {
196          console.info('textTimer notCountDown utc is: ' + utc + ', elapsedTime: ' + elapsedTime)
197        })
198      Row() {
199        Button("start").onClick(() => {
200          this.textTimerController.start()
201        })
202        Button("pause").onClick(() => {
203          this.textTimerController.pause()
204        })
205        Button("reset").onClick(() => {
206          this.textTimerController.reset()
207        })
208      }
209    }
210  }
211}
212```
213
214
215![en-us_image_0000001257138345](figures/en-us_image_0000001257138345.gif)
216
217### Example 2
218``` ts
219// xxx.ets
220@Entry
221@Component
222struct TextTimerExample {
223  @State textShadows : ShadowOptions | Array<ShadowOptions> = [{ radius: 10, color: Color.Red, offsetX: 10, offsetY: 0 },{ radius: 10, color: Color.Black, offsetX: 20, offsetY: 0 },
224      { radius: 10, color: Color.Brown, offsetX: 30, offsetY: 0 },{ radius: 10, color: Color.Green, offsetX: 40, offsetY: 0 },
225      { radius: 10, color: Color.Yellow, offsetX: 100, offsetY: 0 }]
226  build() {
227    Column({ space: 8 }) {
228      TextTimer().fontSize(50).textShadow(this.textShadows)
229    }
230  }
231}
232```
233![TextshadowExample](figures/text_timer_textshadow.png)
234
235### Example 3
236This 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.
237``` ts
238// xxx.ets
239class MyTextTimerModifier implements ContentModifier<TextTimerConfiguration> {
240  constructor() {
241  }
242  applyContent() : WrappedBuilder<[TextTimerConfiguration]>
243  {
244      return wrapBuilder(buildTextTimer)
245  }
246}
247
248@Builder function buildTextTimer(config: TextTimerConfiguration) {
249  Column() {
250     Stack({ alignContent: Alignment.Center }) {
251       Circle({ width: 150, height: 150 }).fill(config.started ? (config.isCountDown ? 0xFF232323 : 0xFF717171) : 0xFF929292)
252       Column(){
253         Text(config.isCountDown ? "Countdown" : "Count-up").fontColor(Color.White)
254         Text(
255           (config.isCountDown ? "Remaining" : "Elapsed") + (config.isCountDown?
256             (Math.max(config.count / 1000 - config.elapsedTime / 100,0)).toFixed(1) + "/" + (config.count / 1000).toFixed(0)
257             :((config.elapsedTime / 100).toFixed(0))
258           ) + "s"
259         ).fontColor(Color.White)
260       }
261     }
262  }
263}
264
265@Entry
266@Component
267struct Index {
268  @State count: number = 10000
269  @State myTimerModifier: MyTextTimerModifier = new MyTextTimerModifier()
270  countDownTextTimerController: TextTimerController = new TextTimerController()
271  countUpTextTimerController: TextTimerController = new TextTimerController()
272
273  build() {
274    Row() {
275      Column() {
276        TextTimer({isCountDown: true, count: this.count, controller: this.countDownTextTimerController})
277          .contentModifier(this.myTimerModifier)
278          .onTimer((utc: number, elapsedTime: number) => {
279            console.info('textTimer onTimer utc is:' + utc + ', elapsedTime: ' + elapsedTime)
280          })
281          .margin(10)
282        TextTimer({isCountDown: false, controller: this.countUpTextTimerController})
283          .contentModifier(this.myTimerModifier)
284          .onTimer((utc: number, elapsedTime: number) => {
285            console.info('textTimer onTimer utc is:' + utc + ', elapsedTime: ' + elapsedTime)
286          })
287        Row() {
288          Button("start").onClick(()=>{
289            this.countDownTextTimerController.start()
290            this.countUpTextTimerController.start()
291          }).margin(10)
292          Button("pause").onClick(()=>{
293            this.countDownTextTimerController.pause()
294            this.countUpTextTimerController.pause()
295          }).margin(10)
296          Button("reset").onClick(()=>{
297            this.countDownTextTimerController.reset()
298            this.countUpTextTimerController.reset()
299          }).margin(10)
300        }.margin(20)
301      }.width('100%')
302    }.height('100%')
303  }
304}
305```
306
307
308### Example 4
309In this example, the **TextTimer** component is set to execute immediately after it is created.
310``` ts
311@Entry
312@Component
313struct textTimerStart {
314  textTimerController: TextTimerController = new TextTimerController()
315  @State format: string = 'mm:ss.SS'
316
317  build() {
318    Column() {
319      Scroll()
320        .height('20%')
321      TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController })
322        .format(this.format)
323        .fontColor(Color.Black)
324        .fontSize(50)
325        .onTimer((utc: number, elapsedTime: number) => {
326          console.info('textTimer notCountDown utc is: ' + utc + ', elapsedTime: ' + elapsedTime)
327        })
328        .onAppear(()=>{
329          this.textTimerController.start()
330        })
331    }
332  }
333}
334```
335![text_timer_auto_start](figures/text_timer_auto_start.gif)
336