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 18Since API version 11, this API is supported in ArkTS widgets. 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.<br>For countries or regions crossing the International Date Line, use -13 (UTC+13) and -14 (UTC+14) to ensure consistent time within the entire 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| 25| controller | [TextClockController](#textclockcontroller) | No | Controller to control the status of the **<TextClock\>** component.| 26 27## Attributes 28 29In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 30 31| Name | Type| Description | 32| ------ | -------- | ------------------------------------------------------------ | 33| format | string | Time format.<br>**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**.)<br>**H**: hour (24-hour format) **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**.)<br>Separators: slashes (/), hyphens (-), dots (.), or any custom characters (which cannot be letters) used to separate the parts of the date<br>The 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.<br>When 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.<br>If **format** is left empty or set to **undefined**, the default value will be used.<br><br>- Default value for non-widgets: aa hh:mm:ss<br>- Default value for widgets: hh:mm<br>- 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.<br>Since API version 11, this API is supported in ArkTS widgets.| 34| textShadow<sup>11+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| Array<[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions)> | Text shadow. It supports input parameters in an array to implement multiple text shadows.<br>**NOTE**<br>This API does not work with the **fill** attribute or coloring strategy.<br>Since API version 11, this API is supported in ArkTS widgets.| 35| fontFeature<sup>11+</sup> | string | Font feature, for example, monospaced digits.<br>Format: normal \| \<feature-tag-value\><br>- The format of \<feature-tag-value\> is \<string\> \[ \<integer\>\| on \| off ]<br>- There can be multiple \<feature-tag-value\> values, which are separated by commas (,).<br>For example, the input format of the monospaced clock numbers is "ss01" on.<br>Since API version 11, this API is supported in ArkTS widgets.| 36 37The following table shows how different settings of **format** work out. 38 39| Input Format | Display Effect| 40| ------------------------------------------------------------ | ------ | 41| EEEE, M, d, yyyy | Saturday, February 4, 2023| 42| MMM d, yyyy | February 4, 2023 | 43| EEEE, M, d | Saturday, February 4 | 44| MMM dd | February 4 | 45| MM/dd/yyyy | 02/04/2023 | 46| EEEE MM dd | Saturday February 04 | 47| yyyy | 2023 | 48| yy | 23 | 49| MM | February | 50| M | February| 51| dd (complete date)| 04| 52| d | 4| 53| EEEE (full name)| Saturday| 54| E, EE, EEE (abbreviation)| Sat| 55| MMM d, yyyy| February 4, 2023| 56| yyyy/M/d | 2023/2/4 | 57| yyyy-M-d | 2023-2-4 | 58| yyyy.M.d | 2023.2.4 | 59| HH:mm:ss| 17:00:04 | 60| aa hh:mm:ss| 5:00:04 AM| 61| hh:mm:ss| 5:00:04 | 62| HH:mm| 17:00 | 63| aa hh:mm| 5:00 AM| 64| hh:mm| 5:00 | 65| mm:ss| 00:04 | 66| mm:ss.SS| 00:04.91 | 67| mm:ss.SSS| 00:04.536 | 68| hh:mm:ss aa | 5:00:04 AM| 69| HH | 17 | 70 71## Events 72 73In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 74 75| Name | Description | 76| -------------------------------------------- | ------------------------------------------------------------ | 77| onDateChange(event: (value: number) => void) | Triggered when the time changes.<br>- **value**: Unix time stamp, which is the number of seconds that have elapsed since the Unix epoch.<br>- This event is not triggered when the component is invisible.<br>- If the event is not used in a widget, it is triggered when the change occurs in seconds.<br>- If the event is used in a widget, it is triggered when the change occurs in minutes.<br>Since API version 11, this API is supported in ArkTS widgets.| 78 79## TextClockController 80 81Implements 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. 82 83Since API version 11, this API is supported in ArkTS widgets. 84 85### Objects to Import 86 87```ts 88controller: TextClockController = new TextClockController(); 89``` 90 91### start 92 93start() 94 95Starts the **<TextClock\>** component. 96 97Since API version 11, this API is supported in ArkTS widgets. 98 99### stop 100 101stop() 102 103Stops the **<TextClock\>** component. 104 105Since API version 11, this API is supported in ArkTS widgets. 106 107## Example 108### Example 1 109```ts 110@Entry 111@Component 112struct Second { 113 @State accumulateTime: number = 0 114 // Objects to import 115 controller: TextClockController = new TextClockController() 116 build() { 117 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 118 Text('Current milliseconds is ' + this.accumulateTime) 119 .fontSize(20) 120 // Display the system time in 12-hour format for the UTC+8 time zone, accurate to seconds. 121 TextClock({ timeZoneOffset: -8, controller: this.controller }) 122 .format('aa hh:mm:ss') 123 .onDateChange((value: number) => { 124 this.accumulateTime = value 125 }) 126 .margin(20) 127 .fontSize(30) 128 Button("start TextClock") 129 .margin({ bottom: 10 }) 130 .onClick(() => { 131 // Start the text clock. 132 this.controller.start() 133 }) 134 Button("stop TextClock") 135 .onClick(() => { 136 // Stop the text clock. 137 this.controller.stop() 138 }) 139 } 140 .width('100%') 141 .height('100%') 142 } 143} 144``` 145 146 147### Example 2 148``` ts 149@Entry 150@Component 151struct TextClockExample { 152 @State textShadows : ShadowOptions | Array<ShadowOptions> = [{ radius: 10, color: Color.Red, offsetX: 10, offsetY: 0 },{ radius: 10, color: Color.Black, offsetX: 20, offsetY: 0 }, 153 { radius: 10, color: Color.Brown, offsetX: 30, offsetY: 0 },{ radius: 10, color: Color.Green, offsetX: 40, offsetY: 0 }, 154 { radius: 10, color: Color.Yellow, offsetX: 100, offsetY: 0 }] 155 build() { 156 Column({ space: 8 }) { 157 TextClock().fontSize(50).textShadow(this.textShadows) 158 } 159 } 160} 161``` 162 163
