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
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
10## Child Components
11
12Not supported
13
14## APIs
15
16TextClock(options?: { timeZoneOffset?: number, controller?: TextClockController })
17
18This API can be used in ArkTS widgets since API version 11.
19
20**Parameters**
21
22| Name           | Type     | Mandatory    | Description                                                    |
23| -------------- | -------- | ------ | --------------------------------------------------------------------------- |
24| 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, the value is rounded up, with digits after the decimal point 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>Since API version 11, the value is not rounded when it is set to 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.|
25| controller     | [TextClockController](#textclockcontroller) | No     | Controller to control the status of the **<TextClock\>** component.|
26
27## Attributes
28
29Among 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.
30
31### format
32
33format(value: string)
34
35Sets the time format, for example, **yyyy/mm/dd** or **yyyy-mm-dd**.
36
37**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**.)
38
39Separators: slashes (/), hyphens (-), dots (.), or any custom characters (which cannot be letters) used to separate the parts of the date
40
41The 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.
42
43When an invalid letter is set, the letter is ignored. If the value contains only invalid letters, the time will be displayed in the format of yyyy/MM/dd aa hh:mm:ss.SSS.
44
45If **format** is left empty or set to **undefined**, the default value will be used.
46
47Default value for non-widgets: aa hh:mm:ss. Default value for widgets: hh:mm. When used in a widget, the minimum time unit is minute. In this case, if the format contains seconds or centiseconds, the default value will be used.
48
49**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
50
51**System capability**: SystemCapability.ArkUI.ArkUI.Full
52
53**Parameters**
54
55| Name| Type  | Mandatory| Description          |
56| ------ | ------ | ---- | -------------- |
57| value  | string | Yes  | Time format to set.|
58
59The following table shows how different settings of **format** work out.
60
61| Input Format               | Display Effect           |
62| ----------------------- | ------------------- |
63| EEEE, M, d, yyyy      | Saturday, February 4, 2023|
64| MMM d, yyyy           | February 4, 2023       |
65| EEEE, M, d            | Saturday, February 4      |
66| MMM dd                 | February 4             |
67| MM/dd/yyyy              | 02/04/2023          |
68| EEEE MM dd          | Saturday February 04    |
69| yyyy       | 2023             |
70| yy       | 23               |
71| MM         | February               |
72| M              | February                |
73| dd (complete date)         | 04               |
74| d               | 4                |
75| EEEE (full name)       | Saturday             |
76| E, EE, EEE (abbreviation) | Sat               |
77| MMM d, yyyy           | February 4, 2023       |
78| yyyy/M/d                | 2023/2/4            |
79| yyyy-M-d                | 2023-2-4            |
80| yyyy.M.d                | 2023.2.4            |
81| HH:mm:ss   | 17:00:04            |
82| aa hh:mm:ss| 5:00:04 AM       |
83| hh:mm:ss   | 5:00:04             |
84| HH:mm         | 17:00               |
85| aa hh:mm      | 5:00 AM          |
86| hh:mm         | 5:00                |
87| mm:ss         | 00:04               |
88| mm:ss.SS | 00:04.91            |
89| mm:ss.SSS| 00:04.536           |
90| hh:mm:ss aa             | 5:00:04 AM       |
91| HH                      | 17                  |
92
93## textShadow<sup>11+</sup>
94
95textShadow(value: ShadowOptions | Array&lt;ShadowOptions&gt;)
96
97Sets 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.
98
99**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
100
101**System capability**: SystemCapability.ArkUI.ArkUI.Full
102
103**Parameters**
104
105| Name| Type                                                        | Mandatory| Description          |
106| ------ | ------------------------------------------------------------ | ---- | -------------- |
107| value  | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| Array&lt;[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions)> | Yes  | Text shadow.|
108
109### fontFeature<sup>11+</sup>
110
111fontFeature(value: string)
112
113Sets the font feature, for example, monospaced digits.
114
115Format: normal \| \<feature-tag-value\>
116
117Format of **\<feature-tag-value\>**: \<string\> \[ \<integer\> \| on \| off ]
118
119There can be multiple **\<feature-tag-value\>** values, which are separated by commas (,).
120
121For example, the input format for monospaced clock fonts is "ss01" on.
122
123**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
124
125**System capability**: SystemCapability.ArkUI.ArkUI.Full
126
127**Parameters**
128
129| Name| Type  | Mandatory| Description          |
130| ------ | ------ | ---- | -------------- |
131| value  | string | Yes  | Font feature.|
132
133## Events
134
135In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
136
137### onDateChange
138
139onDateChange(event: (value: number) => void)
140
141Triggered when the time changes.
142
143This event does not take effect when the component is invisible.
144
145If the event is not used in a widget, it is triggered when the change occurs in seconds.
146
147If the event is used in a widget, it is triggered when the change occurs in minutes.
148
149**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
150
151**System capability**: SystemCapability.ArkUI.ArkUI.Full
152
153**Parameters**
154
155| Name| Type  | Mandatory| Description                                                  |
156| ------ | ------ | ---- | ------------------------------------------------------ |
157| value  | number | Yes  | Unix time stamp, which is the number of seconds that have elapsed since the Unix epoch.|
158
159## TextClockController
160
161Implements 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.
162
163This API can be used in ArkTS widgets since API version 11.
164
165### Objects to Import
166
167```ts
168controller: TextClockController = new TextClockController();
169```
170
171### start
172
173start()
174
175Starts the **<TextClock\>** component.
176
177This API can be used in ArkTS widgets since API version 11.
178
179### stop
180
181stop()
182
183Stops the **<TextClock\>** component.
184
185This API can be used in ArkTS widgets since API version 11.
186
187## Example
188### Example 1
189```ts
190@Entry
191@Component
192struct Second {
193  @State accumulateTime: number = 0
194  // Objects to import
195  controller: TextClockController = new TextClockController()
196  build() {
197    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
198      Text('Current milliseconds is ' + this.accumulateTime)
199        .fontSize(20)
200      // Display the system time in 12-hour format for the UTC+8 time zone, accurate to seconds.
201      TextClock({ timeZoneOffset: -8, controller: this.controller })
202        .format('aa hh:mm:ss')
203        .onDateChange((value: number) => {
204          this.accumulateTime = value
205        })
206        .margin(20)
207        .fontSize(30)
208      Button("start TextClock")
209        .margin({ bottom: 10 })
210        .onClick(() => {
211          // Start the text clock.
212          this.controller.start()
213        })
214      Button("stop TextClock")
215        .onClick(() => {
216          // Stop the text clock.
217          this.controller.stop()
218        })
219    }
220    .width('100%')
221    .height('100%')
222  }
223}
224```
225![text_clock](figures/text_clock.gif)
226
227### Example 2
228``` ts
229@Entry
230@Component
231struct TextClockExample {
232  @State textShadows : ShadowOptions | Array<ShadowOptions> = [{ radius: 10, color: Color.Red, offsetX: 10, offsetY: 0 },{ radius: 10, color: Color.Black, offsetX: 20, offsetY: 0 },
233      { radius: 10, color: Color.Brown, offsetX: 30, offsetY: 0 },{ radius: 10, color: Color.Green, offsetX: 40, offsetY: 0 },
234      { radius: 10, color: Color.Yellow, offsetX: 100, offsetY: 0 }]
235  build() {
236    Column({ space: 8 }) {
237      TextClock().fontSize(50).textShadow(this.textShadows)
238    }
239  }
240}
241```
242![TextshadowExample](figures/text_clock_textshadow.png)
243