1# TextClock 2 3TextClock组件通过文本将当前系统时间显示在设备上。支持不同时区的时间显示，最高精度到秒级。 4 5>**说明：** 6> 7>该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9 10## 子组件 11 12无 13 14## 接口 15 16TextClock(options?: { timeZoneOffset?: number, controller?: TextClockController }) 17 18从API version 11开始，该接口支持在ArkTS卡片中使用。 19 20**参数：** 21 22| 参数名 | 参数类型 | 必填 | 参数描述 | 23| -------------- | -------- | ------ | --------------------------------------------------------------------------- | 24| timeZoneOffset | number | 否 | 设置时区偏移量。<br>取值范围为[-14, 12]，表示东十二区到西十二区，其中负值表示东时区，正值表示西时区，比如东八区为-8。设置值为该取值范围内的浮点数时会进行取整，舍弃小数部分。<br>对横跨国际日界线的国家或地区，用-13（UTC+13）和-14（UTC+14）来保证整个国家或者区域处在相同的时间，当设置的值不在取值范围内时，将使用当前系统的时区偏移量。<br/>默认值：当前系统的时区偏移量 <br/>从API version 11开始，设置值为{ 9.5, 3.5, -3.5, -4.5, -5.5, -5.75, -6.5, -9.5, -10.5, -12.75 }集合中的浮点数时不再进行取整。| 25| controller | [TextClockController](#textclockcontroller) | 否 | 绑定一个控制器，用来控制文本时钟的状态。| 26 27## 属性 28 29除支持[通用属性](ts-universal-attributes-size.md)和[文本通用属性](ts-universal-attributes-text-style.md)的fontColor、fontSize、fontStyle、fontWeight、fontFamily外，还支持以下属性： 30 31| 名称 | 参数类型 | 描述 | 32| ------ | -------- | ------------------------------------------------------------ | 33| format | string | y：年（yyyy表示完整年份，yy表示年份后两位）<br />M：月（若想使用01月则使用MM）<br />d：日（若想使用01日则使用dd）<br />E：星期（若想使用星期六则使用EEEE，若想使用周六则使用E、EE、EEE）<br />H：小时（24小时制） h：小时（12小时制） <br/>m：分钟<br/>s：秒<br/>SS：厘秒(format中S个数<3，全部按厘秒处理)<br />SSS：毫秒(format中S个数>=3，全部按毫秒处理)<br/>a：上午/下午（当设置小时制式为H时，该参数不生效）<br />日期间隔符："年月日"、“/”、"-"、"."（可以自定义间隔符样式，间隔符不可以为字母，汉字则作为间隔符处理）<br/>允许自行拼接组合显示格式，即：年、月、日、星期、时、分、秒、毫秒可拆分为子元素，可自行排布组合。时间更新频率最高为一秒一次，不建议单独设置厘秒和毫秒格式。<br />当设置无效字母时（非上述字母被认为是无效字母），该字母会被忽略。如果format全是无效字母时，显示为格式yyyy/MM/dd aa hh:mm:ss.SSS<br />若format为空或者undefined，则使用默认值。<br /><br />- 非卡片中默认值：aa hh:mm:ss<br/>- 卡片中默认值：hh:mm <br />- 卡片中使用时，最小时间单位为分钟。如果设置格式中有秒或厘秒按默认值处理。<br/>从API version 11开始，该接口支持在ArkTS卡片中使用。 | 34| textShadow<sup>11+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| Array<[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明)> | 设置文字阴影效果。该接口支持以数组形式入参，实现多重文字阴影。<br/>**说明:** 不支持fill字段, 不支持智能取色模式。 <br/>从API version 11开始，该接口支持在ArkTS卡片中使用。 | 35| fontFeature<sup>11+</sup> | string | 设置文字特性效果，比如数字等宽的特性。<br />格式为：normal \| \<feature-tag-value\><br />- \<feature-tag-value\>的格式为：\<string\> \[ \<integer\> \| on \| off ]<br />- \<feature-tag-value\>的个数可以有多个，中间用','隔开。 <br />例如，使用等宽时钟数字的输入格式为："ss01" on<br/>从API version 11开始，该接口支持在ArkTS卡片中使用。| 36 37以下是format输入的格式样式及对应的显示效果： 38 39| 输入格式 | 显示效果 | 40| ------------------------------------------------------------ | ------ | 41| yyyy年M月d日 EEEE | 2023年2月4日 星期六 | 42| yyyy年M月d日 | 2023年2月4日 | 43| M月d日 EEEE | 2月4日 星期六 | 44| M月d日 | 2月4日 | 45| MM/dd/yyyy | 02/04/2023 | 46| EEEE MM月dd日 | 星期六 02月04日 | 47| yyyy（完整年份） | 2023年 | 48| yy（年份后两位） | 23年 | 49| MM（完整月份） | 02月 | 50| M（月份） | 2月 | 51| dd（完整日期） | 04日 | 52| d（日期） | 4日 | 53| EEEE（完整星期） | 星期六 | 54| E、EE、EEE（简写星期） | 周六 | 55| yyyy年M月d日 | 2023年2月4日 | 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 | 61| hh:mm:ss（时:分:秒） | 5:00:04 | 62| HH:mm（时:分） | 17:00 | 63| aa hh:mm（时:分） | 上午 5:00 | 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 上午 | 69| HH | 17 | 70 71## 事件 72 73除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 74 75| 名称 | 功能描述 | 76| -------------------------------------------- | ------------------------------------------------------------ | 77| onDateChange(event: (value: number) => void) | 提供时间变化回调，该事件回调间隔为秒。<br/>- value: Unix Time Stamp，即自1970年1月1日（UTC）起经过的秒数。<br/>- 组件不可见时不回调。<br/>- 非卡片中使用时，该事件回调间隔为秒。<br/>- 卡片中使用时，该事件回调间隔为分钟。<br/>从API version 11开始，该接口支持在ArkTS卡片中使用。| 78 79## TextClockController 80 81TextClock容器组件的控制器，可以将该控制器绑定到TextClock组件，通过它控制文本时钟的启动与停止。一个TextClock组件仅支持绑定一个控制器。 82 83从API version 11开始，该接口支持在ArkTS卡片中使用。 84 85### 导入对象 86 87```ts 88controller: TextClockController = new TextClockController(); 89``` 90 91### start 92 93start() 94 95启动文本时钟。 96 97从API version 11开始，该接口支持在ArkTS卡片中使用。 98 99### stop 100 101stop() 102 103停止文本时钟。 104 105从API version 11开始，该接口支持在ArkTS卡片中使用。 106 107## 示例 108### 示例1 109```ts 110@Entry 111@Component 112struct Second { 113 @State accumulateTime: number = 0 114 // 导入对象 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 // 以12小时制显示东八区的系统时间，精确到秒。 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 // 启动文本时钟 132 this.controller.start() 133 }) 134 Button("stop TextClock") 135 .onClick(() => { 136 // 停止文本时钟 137 this.controller.stop() 138 }) 139 } 140 .width('100%') 141 .height('100%') 142 } 143} 144``` 145 146 147### 示例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
