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## TextClockController 26 27TextClock容器组件的控制器，可以将此对象绑定到TextClock组件，再通过它控制文本时钟的启动与停止。一个TextClock组件仅支持绑定一个控制器。 28 29### 导入对象 30 31```ts 32controller: TextClockController = new TextClockController(); 33``` 34 35### start 36 37start() 38 39启动文本时钟。 40 41### stop 42 43stop() 44 45停止文本时钟。 46 47 48## 属性 49 50除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 51 52| 名称 | 参数类型 | 描述 | 53| ------ | --------------- | ------------------------------------------------------------ | 54| 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/>默认值： 'hms'| 55 56## 事件 57 58除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 59 60| 名称 | 功能描述 | 61| -------------------------------------------- | ------------------------------------------------------------ | 62| onDateChange(event: (value: number) => void) | 提供时间变化回调，该事件最小回调间隔为秒。<br /> value: Unix Time Stamp，即自1970年1月1日（UTC）起经过的毫秒数。 | 63 64 65## 示例 66 67```ts 68@Entry 69@Component 70struct Second { 71 @State accumulateTime: number = 0; 72 // 导入对象 73 controller: TextClockController = new TextClockController(); 74 build() { 75 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 76 Text('Current milliseconds is ' + this.accumulateTime) 77 .fontSize(20) 78 // 以12小时制显示东八区的系统时间，精确到秒。 79 TextClock({ timeZoneOffset: -8, controller: this.controller }) 80 .format('hms') 81 .onDateChange((value: number) => { 82 this.accumulateTime = value; 83 }) 84 .margin(20) 85 .fontSize(30) 86 Button("start TextClock") 87 .margin({ bottom: 10 }) 88 .onClick(() => { 89 // 启动文本时钟 90 this.controller.start(); 91 }) 92 Button("stop TextClock") 93 .onClick(() => { 94 // 停止文本时钟 95 this.controller.stop(); 96 }) 97 } 98 .width('100%') 99 .height('100%') 100 } 101} 102``` 103 104 105
