1# TextClock 2 3TextClock组件通过文本将当前系统时间显示在设备上。支持不同时区的时间显示，最高精度到秒级。 4 5>**说明：** 6> 7>该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## 子组件 10 11无 12 13## 接口 14 15TextClock(options?: { timeZoneOffset?: number, controller?: TextClockController }) 16 17**参数：** 18 19| 参数名 | 参数类型 | 必填 | 参数描述 | 20| -------------- | -------- | ------ | --------------------------------------------------------------------------- | 21| timeZoneOffset | number | 否 | 设置时区偏移量。<br>取值范围为[-14, 12]，表示东十二区到西十二区，其中负值表示东时区，正值表示西时区，比如东八区为-8。<br>对横跨国际日界线的国家或地区，用-13（UTC+13）和-14（UTC+14）来保证整个国家或者区域处在相同的时间，当设置的值不在取值范围内时，将使用当前系统的时区偏移量。<br/>默认值：当前系统的时区偏移量 | 22| controller | [TextClockController](#textclockcontroller) | 否 | 绑定一个控制器，用来控制文本时钟的状态。| 23 24## 属性 25 26除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 27 28| 名称 | 参数类型 | 描述 | 29| ------ | --------------- | ------------------------------------------------------------ | 30| format | string | 设置显示时间格式。<br/>日期间隔符固定为"/"，时间间隔符为":"。<br/>如yyyyMMdd，yyyy-MM-dd显示为yyyy/MM/dd，<br/>hhmmss显示为hh:mm:ss。 <br/>时间格式只用写一位即可，如"hhmmss"等同于"hms"。<br/>支持的时间格式化字符串：<br/>- YYYY/yyyy：完整年份。<br/>- YY/yy：年份后两位。<br/>- M：月份(若想使用01月则使用MM)。<br/>- d：日期(若想使用01日则使用dd)。<br/>- D：年中日(一年中的第几天)。<br/>- H：24小时制。<br/>- h：12小时制。<br/>- m：分钟。<br/>- s：秒。<br/>- SSS：毫秒。<br/>若格式未匹配，则使用默认值。<br/>默认值： 'hms'| 31 32## 事件 33 34除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 35 36| 名称 | 功能描述 | 37| -------------------------------------------- | ------------------------------------------------------------ | 38| onDateChange(event: (value: number) => void) | 提供时间变化回调，该事件最小回调间隔为秒。<br/>- value: Unix Time Stamp，即自1970年1月1日（UTC）起经过的毫秒数。 | 39 40## TextClockController 41 42TextClock容器组件的控制器，可以将该控制器绑定到TextClock组件，通过它控制文本时钟的启动与停止。一个TextClock组件仅支持绑定一个控制器。 43 44### 导入对象 45 46```ts 47controller: TextClockController = new TextClockController(); 48``` 49 50### start 51 52start() 53 54启动文本时钟。 55 56### stop 57 58stop() 59 60停止文本时钟。 61 62## 示例 63 64```ts 65@Entry 66@Component 67struct Second { 68 @State accumulateTime: number = 0 69 // 导入对象 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 // 以12小时制显示东八区的系统时间，精确到秒。 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 // 启动文本时钟 87 this.controller.start() 88 }) 89 Button("stop TextClock") 90 .onClick(() => { 91 // 停止文本时钟 92 this.controller.stop() 93 }) 94 } 95 .width('100%') 96 .height('100%') 97 } 98} 99``` 100 101
