1# TextClock
2
3The **TextClock** component displays the current system time in text format for different time zones. The time is accurate to seconds.
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
12## Child Components
13
14Not supported
15
16## APIs
17
18TextClock(options?: TextClockOptions)
19
20**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
21
22**Atomic service API**: This API can be used in atomic services since API version 11.
23
24**System capability**: SystemCapability.ArkUI.ArkUI.Full
25
26**Parameters**
27
28| Name| Type| Mandatory| Description|
29| -------- | -------- | -------- | -------- |
30| options |  [TextClockOptions](#textclockoptions14)| No| Options of the text clock.|
31
32## TextClockOptions<sup>14+</sup>
33
34**Widget capability**: This API can be used in ArkTS widgets since API version 14.
35
36**Atomic service API**: This API can be used in atomic services since API version 14.
37
38**System capability**: SystemCapability.ArkUI.ArkUI.Full
39
40| Name           | Type     | Mandatory    | Description                                                    |
41| -------------- | -------- | ------ | --------------------------------------------------------------------------- |
42| timeZoneOffset | number   | No    | Time zone offset.<br>The value range is [-14, 12], indicating UTC+12 to UTC-12. A negative value indicates Eastern Standard Time, and a positive value indicates Western Standard Time. For example, **-8** indicates UTC+8. If the value is a floating point number within the value range, it is rounded off, with the decimal portion discarded.<br>For countries or regions crossing the International Date Line, use -13 (UTC+13) and -14 (UTC+14) to ensure time consistency across the country or region. If the set value is not within the valid range, the time zone offset of the current system will be used.<br>Default value: time zone offset of the current system<br>The value is not rounded when it is a floating point number in the { 9.5, 3.5, -3.5, -4.5, -5.5, -5.75, -6.5, -9.5, -10.5, -12.75 } set.|
43| controller     | [TextClockController](#textclockcontroller) | No     | Controller to control the status of the **<TextClock\>** component.|
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 time format, for example, **yyyy/MM/dd** or **yyyy-MM-dd**.
54
55**y**: year (yyyy indicates the complete year, and yy indicates the last two digits of the year.)<br>**M**: month (To display 01 for January, use **MM** instead.)<br>**d**: day (To display 01 for the first day, use **dd** instead.)<br>**E**: day of week (To display the full name, use **EEEE**; to display the abbreviation, use **E**, **EE**, or **EEE**.)<b>**H**: hour (24-hour format)<b>**h**: hour (12-hour format)<br>**m**: minute<br>**s**: second<br>**SS**: centisecond (If the number of the uppercase letter S is less than 3, the part is processed as centiseconds.)<br>**SSS**: millisecond (If the number of the uppercase letter S is greater than or equal to 3, the part is processed as milliseconds.)<br>**a**: morning/afternoon (This parameter does not take effect when the hour part is set to **H**.)
56
57Separators: slashes (/), hyphens (-), dots (.), or any custom characters (which cannot be letters) used to separate the parts of the date
58
59The parts of the date can be used alone or combined with each other as needed. The time can be updated as frequent as once per second. As such, whenever possible, avoid setting the centisecond and millisecond parts separately.
60
61When an invalid letter is set, the letter is ignored. If all letters in **format** are invalid, the display format follows the system's language and hour format settings.
62
63If **format** is left empty or set to **undefined**, the default value will be used.
64
65Default value outside of widgets: 12-hour format: aa hh:mm:ss; 24-hour format: HH:mm:ss.<br>Default value in widgets: 12-hour format: hh:mm, 24-hour format: HH:mm.<br>When used in widgets, the minimum time unit is minute. In this case, if the format contains seconds or centiseconds, the default value will be used.
66
67**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
68
69**Atomic service API**: This API can be used in atomic services since API version 11.
70
71**System capability**: SystemCapability.ArkUI.ArkUI.Full
72
73**Parameters**
74
75| Name| Type  | Mandatory| Description          |
76| ------ | ------ | ---- | -------------- |
77| value  | string | Yes  | Time format to set.|
78
79The following table shows how different settings of **format** work out.
80
81| Input Format               | Display Effect           |
82| ----------------------- | ------------------- |
83| EEEE, M, d, yyyy      | Saturday, February 4, 2023|
84| MMM d, yyyy           | February 4, 2023       |
85| EEEE, M, d            | Saturday, February 4      |
86| MMM dd                 | February 4             |
87| MM/dd/yyyy              | 02/04/2023          |
88| EEEE MM dd          | Saturday February 04    |
89| yyyy       | 2023             |
90| yy       | 23               |
91| MM         | February               |
92| M              | February                |
93| dd (complete date)         | 04               |
94| d               | 4                |
95| EEEE (full name)       | Saturday             |
96| E, EE, EEE (abbreviation) | Sat               |
97| MMM d, yyyy           | February 4, 2023       |
98| yyyy/M/d                | 2023/2/4            |
99| yyyy-M-d                | 2023-2-4            |
100| yyyy.M.d                | 2023.2.4            |
101| HH:mm:ss   | 17:00:04            |
102| aa hh:mm:ss| 5:00:04 AM       |
103| hh:mm:ss   | 5:00:04             |
104| HH:mm         | 17:00               |
105| aa hh:mm      | 5:00 AM          |
106| hh:mm         | 5:00                |
107| mm:ss         | 00:04               |
108| mm:ss.SS | 00:04.91            |
109| mm:ss.SSS| 00:04.536           |
110| hh:mm:ss aa             | 5:00:04 AM       |
111| HH                      | 17                  |
112
113### fontColor
114
115fontColor(value: ResourceColor)
116
117Sets the font color.
118
119**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
120
121**Atomic service API**: This API can be used in atomic services since API version 11.
122
123**System capability**: SystemCapability.ArkUI.ArkUI.Full
124
125**Parameters**
126
127| Name| Type                                      | Mandatory| Description      |
128| ------ | ------------------------------------------ | ---- | ---------- |
129| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Font color.|
130
131### fontSize
132
133fontSize(value: Length)
134
135Sets the font size.
136
137**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
138
139**Atomic service API**: This API can be used in atomic services since API version 11.
140
141**System capability**: SystemCapability.ArkUI.ArkUI.Full
142
143**Parameters**
144
145| Name| Type                        | Mandatory| Description                                                        |
146| ------ | ---------------------------- | ---- | ------------------------------------------------------------ |
147| 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. This parameter cannot be set in percentage.|
148
149### fontStyle
150
151fontStyle(value: FontStyle)
152
153Sets the font style.
154
155**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
156
157**Atomic service API**: This API can be used in atomic services since API version 11.
158
159**System capability**: SystemCapability.ArkUI.ArkUI.Full
160
161**Parameters**
162
163| Name| Type                                       | Mandatory| Description                                   |
164| ------ | ------------------------------------------- | ---- | --------------------------------------- |
165| value  | [FontStyle](ts-appendix-enums.md#fontstyle) | Yes  | Font style.<br>Default value: **FontStyle.Normal**|
166
167### fontWeight
168
169fontWeight(value: number | FontWeight | string)
170
171Sets the font weight. If the value is too large, the text may be clipped depending on the font.
172
173**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
174
175**Atomic service API**: This API can be used in atomic services since API version 11.
176
177**System capability**: SystemCapability.ArkUI.ArkUI.Full
178
179**Parameters**
180
181| Name| Type                                                        | Mandatory| Description                                                        |
182| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
183| 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**|
184
185### fontFamily
186
187fontFamily(value: ResourceStr)
188
189Sets the font family.
190
191**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
192
193**Atomic service API**: This API can be used in atomic services since API version 11.
194
195**System capability**: SystemCapability.ArkUI.ArkUI.Full
196
197**Parameters**
198
199| Name| Type                                  | Mandatory| Description                                                        |
200| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ |
201| 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.|
202
203### textShadow<sup>11+</sup>
204
205textShadow(value: ShadowOptions | Array&lt;ShadowOptions&gt;)
206
207Sets 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.
208
209**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
210
211**Atomic service API**: This API can be used in atomic services since API version 12.
212
213**System capability**: SystemCapability.ArkUI.ArkUI.Full
214
215**Parameters**
216
217| Name| Type                                                        | Mandatory| Description          |
218| ------ | ------------------------------------------------------------ | ---- | -------------- |
219| value  | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| Array&lt;[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions)> | Yes  | Text shadow.|
220
221### fontFeature<sup>11+</sup>
222
223fontFeature(value: string)
224
225Sets the font feature, for example, monospaced digits.
226
227Format: normal \| \<feature-tag-value\>
228
229Format of **\<feature-tag-value\>**: \<string\> \[ \<integer\> \| on \| off ]
230
231There can be multiple **\<feature-tag-value\>** values, which are separated by commas (,).
232
233For example, the input format for monospaced clock fonts is "ss01" on.
234
235**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
236
237**Atomic service API**: This API can be used in atomic services since API version 12.
238
239**System capability**: SystemCapability.ArkUI.ArkUI.Full
240
241**Parameters**
242
243| Name| Type  | Mandatory| Description          |
244| ------ | ------ | ---- | -------------- |
245| value  | string | Yes  | Font feature.|
246
247### contentModifier<sup>12+</sup>
248
249contentModifier(modifier: ContentModifier\<TextClockConfiguration>)
250
251Creates a content modifier.
252
253**Atomic service API**: This API can be used in atomic services since API version 12.
254
255**System capability**: SystemCapability.ArkUI.ArkUI.Full
256
257**Parameters**
258
259| Name| Type                                         | Mandatory| Description                                            |
260| ------ | --------------------------------------------- | ---- | ------------------------------------------------ |
261| modifier  | [ContentModifier\<TextClockConfiguration>](#textclockconfiguration12)| Yes  | Content modifier to apply to the text clock.<br>**modifier**: content modifier. You need a custom class to implement the **ContentModifier** API.|
262
263### dateTimeOptions<sup>12+</sup>
264
265dateTimeOptions(dateTimeOptions: Optional\<DateTimeOptions>)
266
267Sets whether to display a leading zero for the hour.
268
269**Widget capability**: This API can be used in ArkTS widgets since API version 12.
270
271**Atomic service API**: This API can be used in atomic services since API version 12.
272
273**System capability**: SystemCapability.ArkUI.ArkUI.Full
274
275**Parameters**
276
277| Name| Type                                                        | Mandatory| Description                                                        |
278| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
279| dateTimeOptions  | Optional<[DateTimeOptions](../../apis-localization-kit/js-apis-intl.md#datetimeoptions)> | Yes  | Whether to display leading zeros in the hour. It only supports setting the **hour** parameter. When the parameter value is **{hour: "2-digit"}**, a leading zero is displayed. When the parameter value is **{hour: "numeric"}**, no leading zero is displayed.<br>Default value: **undefined**, indicating that the component decides whether to display a leading zero based on the format settings configured in the application.|
280
281## Events
282
283In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
284
285### onDateChange
286
287onDateChange(event: (value: number) => void)
288
289Triggered when the time changes.
290
291This event does not take effect when the component is invisible.
292
293If the event is not used in a widget, it is triggered when the change occurs in seconds.
294
295If the event is used in a widget, it is triggered when the change occurs in minutes.
296
297**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
298
299**Atomic service API**: This API can be used in atomic services since API version 11.
300
301**System capability**: SystemCapability.ArkUI.ArkUI.Full
302
303**Parameters**
304
305| Name| Type  | Mandatory| Description                                                  |
306| ------ | ------ | ---- | ------------------------------------------------------ |
307| value  | number | Yes  | Unix time stamp, which is the number of seconds that have elapsed since the Unix epoch.|
308
309## TextClockController
310
311Implements the controller of the **TextClock** component. You can bind the controller to the component to control its start and stop. A **TextClock** component can be bound to only one controller.
312
313**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
314
315**Atomic service API**: This API can be used in atomic services since API version 11.
316
317**System capability**: SystemCapability.ArkUI.ArkUI.Full
318
319### Objects to Import
320
321```ts
322controller: TextClockController = new TextClockController();
323```
324
325### constructor
326
327constructor()
328
329A constructor used to create a **TextClockController** instance.
330
331**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
332
333**Atomic service API**: This API can be used in atomic services since API version 11.
334
335**System capability**: SystemCapability.ArkUI.ArkUI.Full
336
337### start
338
339start()
340
341Starts the **<TextClock\>** component.
342
343**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
344
345**Atomic service API**: This API can be used in atomic services since API version 11.
346
347**System capability**: SystemCapability.ArkUI.ArkUI.Full
348
349### stop
350
351stop()
352
353Stops the **<TextClock\>** component.
354
355**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
356
357**Atomic service API**: This API can be used in atomic services since API version 11.
358
359**System capability**: SystemCapability.ArkUI.ArkUI.Full
360
361## TextClockConfiguration<sup>12+</sup>
362
363You need a custom class to implement the **ContentModifier** API.
364
365**Atomic service API**: This API can be used in atomic services since API version 12.
366
367**System capability**: SystemCapability.ArkUI.ArkUI.Full
368
369| Name| Type   |    Mandatory     |  Description             |
370| ------ | ------ | ------ |-------------------------------- |
371| timeZoneOffset | number | Yes| Time zone offset of the text clock.|
372| started | boolean | Yes| Whether the text clock is started.<br>Default value: **true**|
373| timeValue | number | Yes| Time zone offset of the text clock in seconds from UTC.|
374
375## Example
376### Example 1
377```ts
378@Entry
379@Component
380struct Second {
381  @State accumulateTime: number = 0
382  // Objects to import
383  controller: TextClockController = new TextClockController()
384  build() {
385    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
386      Text('Current milliseconds is ' + this.accumulateTime)
387        .fontSize(20)
388      // Display the system time in 12-hour format for the UTC+8 time zone, accurate to seconds.
389      TextClock({ timeZoneOffset: -8, controller: this.controller })
390        .format('aa hh:mm:ss')
391        .onDateChange((value: number) => {
392          this.accumulateTime = value
393        })
394        .margin(20)
395        .fontSize(30)
396      Button("start TextClock")
397        .margin({ bottom: 10 })
398        .onClick(() => {
399          // Start the text clock.
400          this.controller.start()
401        })
402      Button("stop TextClock")
403        .onClick(() => {
404          // Stop the text clock.
405          this.controller.stop()
406        })
407    }
408    .width('100%')
409    .height('100%')
410  }
411}
412```
413![text_clock](figures/text_clock.gif)
414
415### Example 2
416``` ts
417@Entry
418@Component
419struct TextClockExample {
420  @State textShadows : ShadowOptions | Array<ShadowOptions> = [{ radius: 10, color: Color.Red, offsetX: 10, offsetY: 0 },{ radius: 10, color: Color.Black, offsetX: 20, offsetY: 0 },
421      { radius: 10, color: Color.Brown, offsetX: 30, offsetY: 0 },{ radius: 10, color: Color.Green, offsetX: 40, offsetY: 0 },
422      { radius: 10, color: Color.Yellow, offsetX: 100, offsetY: 0 }]
423  build() {
424    Column({ space: 8 }) {
425      TextClock().fontSize(50).textShadow(this.textShadows)
426    }
427  }
428}
429```
430![TextshadowExample](figures/text_clock_textshadow.png)
431
432### Example 3
433This example implements the functionality of customizing the style of a text clock, creating a time picker component with a custom style: The time picker dynamically adjusts its selected value based on the text clock's timezone offset and the time zone offset in seconds from UTC, creating a clock effect; depending on whether the text clock is started, the time picker toggles between a 12-hour and a 24-hour format display.
434
435``` ts
436class MyTextClockStyle implements ContentModifier<TextClockConfiguration> {
437  currentTimeZoneOffset: number = new Date().getTimezoneOffset() / 60
438  title: string = ''
439
440  constructor(title: string) {
441    this.title = title
442  }
443
444  applyContent(): WrappedBuilder<[TextClockConfiguration]> {
445    return wrapBuilder(buildTextClock)
446  }
447}
448
449@Builder
450function buildTextClock(config: TextClockConfiguration) {
451  Row() {
452    Column() {
453      Text((config.contentModifier as MyTextClockStyle).title)
454        .fontSize(20)
455        .margin(20)
456      TimePicker({
457        selected: (new Date(config.timeValue * 1000 + ((config.contentModifier as MyTextClockStyle).currentTimeZoneOffset - config.timeZoneOffset) * 60 * 60 * 1000)),
458        format: TimePickerFormat.HOUR_MINUTE_SECOND
459      })
460        .useMilitaryTime(!config.started)
461    }
462  }
463}
464
465@Entry
466@Component
467struct TextClockExample {
468  @State accumulateTime1: number = 0
469  @State timeZoneOffset: number = -8
470  controller1: TextClockController = new TextClockController()
471  controller2: TextClockController = new TextClockController()
472
473  build() {
474    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
475      Text('Current milliseconds is ' + this.accumulateTime1)
476        .fontSize(20)
477        .margin({ top: 20 })
478      TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller1 })
479        .format('aa hh:mm:ss')
480        .onDateChange((value: number) => {
481          this.accumulateTime1 = value
482        })
483        .margin(20)
484        .fontSize(30)
485      TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller2 })
486        .format('aa hh:mm:ss')
487        .fontSize(30)
488        .contentModifier(new MyTextClockStyle('ContentModifier:'))
489      Button("start TextClock")
490        .margin({ top: 20, bottom: 10 })
491        .onClick(() => {
492          // Start the text clock.
493          this.controller1.start()
494          this.controller2.start()
495        })
496      Button("stop TextClock")
497        .margin({ bottom: 30 })
498        .onClick(() => {
499          // Stop the text clock.
500          this.controller1.stop()
501          this.controller2.stop()
502        })
503
504    }
505    .width('100%')
506    .height('100%')
507  }
508}
509```
510![ContentModifierExample](figures/text_clock_contentmodifier.gif)
511
512### Example 4
513This example demonstrates how to use the **dateTimeOptions** attribute to add or remove the leading zero for the hour field. By default, the hour field in the 24-hour format includes a leading zero. In the 12-hour format, the hour field typically does not include a leading zero.
514``` ts
515@Entry
516@Component
517struct TextClockExample {
518  build() {
519    Column({ space: 8 }) {
520      Row() {
521        Text("Remove the leading zero in 24-hour format: ")
522          .fontSize(20)
523        TextClock()
524          .fontSize(20)
525          .format("HH:mm:ss")
526          .dateTimeOptions({hour: "numeric"})
527      }
528      Row() {
529        Text("Add the leading zero in 12-hour format: ")
530          .fontSize(20)
531        TextClock()
532          .fontSize(20)
533          .format("aa hh:mm:ss")
534          .dateTimeOptions({hour: "2-digit"})
535      }
536    }
537    .alignItems(HorizontalAlign.Start)
538  }
539}
540```
541![TextClockExample](figures/text_clock_datetimeoptions.png)
542