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## Child Components 10 11Not supported 12 13## APIs 14 15TextClock(options?: { timeZoneOffset?: number, controller?: TextClockController }) 16 17**Parameters** 18 19| Name | Type | Mandatory | Description | 20| -------------- | -------- | ------ | --------------------------------------------------------------------------- | 21| 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| 22| controller | [TextClockController](#textclockcontroller) | No | Controller to control the status of the **<TextClock\>** component.| 23 24## Attributes 25 26In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 27 28| Name | Type | Description | 29| ------ | --------------- | ------------------------------------------------------------ | 30| format | string | Time format.<br>The date separator is a slash (/), and the time separator is a colon (:).<br>For example, yyyyMMdd and yyyy-MM-dd are displayed as yyyy/MM/dd,<br>and hhmmss is displayed as hh:mm:ss.<br>Only one digit is required for the time format. This means that **"hhmmss"** is equivalent to **"hms"**.<br>Supported time format strings:<br>- YYYY/yyyy: four-digit year<br>- YY/yy: last two digits of year<br>- M: one-digit month (MM for two-digit month, for example, 01)<br>- d: one-digit day (dd for two-digit day, for example, 01)<br>- D: number of days that have elapsed in the year<br>- H: 24-hour format<br>- h: 12-hour format<br>- m: minute<br>- s: second<br>- SSS: millisecond<br>If the specified format does not match the supported formats, the default value is used.<br>Default value: **'hms'**| 31 32## Events 33 34In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 35 36| Name | Description | 37| -------------------------------------------- | ------------------------------------------------------------ | 38| onDateChange(event: (value: number) => void) | Called when the time changes in seconds at minimum.<br>- **value**: Unix time stamp, which is the number of milliseconds that have elapsed since the Unix epoch.| 39 40## TextClockController 41 42Implements 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. 43 44### Objects to Import 45 46```ts 47controller: TextClockController = new TextClockController(); 48``` 49 50### start 51 52start() 53 54Starts the **<TextClock\>** component. 55 56### stop 57 58stop() 59 60Stops the **<TextClock\>** component. 61 62## Example 63 64```ts 65@Entry 66@Component 67struct Second { 68 @State accumulateTime: number = 0 69 // Objects to import 70 controller: TextClockController = new TextClockController() 71 build() { 72 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 73 Text('Current milliseconds is ' + this.accumulateTime) 74 .fontSize(20) 75 // Display the system time in 12-hour format for the UTC+8 time zone, accurate to seconds. 76 TextClock({ timeZoneOffset: -8, controller: this.controller }) 77 .format('hms') 78 .onDateChange((value: number) => { 79 this.accumulateTime = value 80 }) 81 .margin(20) 82 .fontSize(30) 83 Button("start TextClock") 84 .margin({ bottom: 10 }) 85 .onClick(() => { 86 // Start the text clock. 87 this.controller.start() 88 }) 89 Button("stop TextClock") 90 .onClick(() => { 91 // Stop the text clock. 92 this.controller.stop() 93 }) 94 } 95 .width('100%') 96 .height('100%') 97 } 98} 99``` 100 101
