1# TextClock 2 3TextClock组件通过文本将当前系统时间显示在设备上。支持不同时区的时间显示，最高精度到秒级。 4 5在组件不可见时时间变动将停止，组件的可见状态基于[onVisibleAreaChange](./ts-universal-component-visible-area-change-event.md#onvisibleareachange)处理，可见阈值ratios大于0即视为可见状态。 6 7>**说明：** 8> 9>该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 10> 11 12## 子组件 13 14无 15 16## 接口 17 18TextClock(options?: { timeZoneOffset?: number, controller?: TextClockController }) 19 20**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 21 22**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 23 24**系统能力：** SystemCapability.ArkUI.ArkUI.Full 25 26**参数：** 27 28| 参数名 | 类型 | 必填 | 说明 | 29| -------------- | -------- | ------ | --------------------------------------------------------------------------- | 30| 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 }集合中的浮点数时不再进行取整。| 31| controller | [TextClockController](#textclockcontroller) | 否 | 绑定一个控制器，用来控制文本时钟的状态。| 32 33## 属性 34 35除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 36 37### format 38 39format(value: string) 40 41设置显示时间格式，如“yyyy/MM/dd”、“yyyy-MM-dd”。 42 43y：年（yyyy表示完整年份，yy表示年份后两位）<br />M：月（若想使用01月则使用MM）<br />d：日（若想使用01日则使用dd）<br />E：星期（若想使用星期六则使用EEEE，若想使用周六则使用E、EE、EEE）H：小时（24小时制） h：小时（12小时制） <br/>m：分钟<br/>s：秒<br/>SS：厘秒(format中S个数<3，全部按厘秒处理)<br />SSS：毫秒(format中S个数>=3，全部按毫秒处理)<br/>a：上午/下午（当设置小时制式为H时，该参数不生效） 44 45日期间隔符："年月日"、“/”、"-"、"."（可以自定义间隔符样式，间隔符不可以为字母，汉字则作为间隔符处理） 46 47允许自行拼接组合显示格式，即：年、月、日、星期、时、分、秒、毫秒可拆分为子元素，可自行排布组合。时间更新频率最高为一秒一次，不建议单独设置厘秒和毫秒格式。 48 49当设置无效字母时（非上述字母被认为是无效字母），该字母会被忽略。如果format全是无效字母时，显示格式跟随系统语言和系统小时制。例如系统语言为中文时，12小时制显示格式为yyyy/MM/dd aa hh:mm:ss.SSS，24小时制显示格式为yyyy/MM/dd HH:mm:ss.SSS。 50 51若format为空或者undefined，则使用默认值。 52 53非卡片中默认值：12小时制：aa hh:mm:ss，24小时制：HH:mm:ss。<br />卡片中默认值：12小时制：hh:mm，24小时制：HH:mm 。<br />卡片中使用时，最小时间单位为分钟。如果设置格式中有秒或厘秒按默认值处理。 54 55**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 56 57**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 58 59**系统能力：** SystemCapability.ArkUI.ArkUI.Full 60 61**参数：** 62 63| 参数名 | 类型 | 必填 | 说明 | 64| ------ | ------ | ---- | -------------- | 65| value | string | 是 | 显示时间格式。 | 66 67以下是format输入的格式样式及对应的显示效果： 68 69| 输入格式 | 显示效果 | 70| ----------------------- | ------------------- | 71| yyyy年M月d日 EEEE | 2023年2月4日 星期六 | 72| yyyy年M月d日 | 2023年2月4日 | 73| M月d日 EEEE | 2月4日 星期六 | 74| M月d日 | 2月4日 | 75| MM/dd/yyyy | 02/04/2023 | 76| EEEE MM月dd日 | 星期六 02月04日 | 77| yyyy（完整年份） | 2023年 | 78| yy（年份后两位） | 23年 | 79| MM（完整月份） | 02月 | 80| M（月份） | 2月 | 81| dd（完整日期） | 04日 | 82| d（日期） | 4日 | 83| EEEE（完整星期） | 星期六 | 84| E、EE、EEE（简写星期） | 周六 | 85| yyyy年M月d日 | 2023年2月4日 | 86| yyyy/M/d | 2023/2/4 | 87| yyyy-M-d | 2023-2-4 | 88| yyyy.M.d | 2023.2.4 | 89| HH:mm:ss（时:分:秒） | 17:00:04 | 90| aa hh:mm:ss（时:分:秒） | 上午 5:00:04 | 91| hh:mm:ss（时:分:秒） | 5:00:04 | 92| HH:mm（时:分） | 17:00 | 93| aa hh:mm（时:分） | 上午 5:00 | 94| hh:mm（时:分） | 5:00 | 95| mm:ss（分:秒） | 00:04 | 96| mm:ss.SS（分:秒.厘秒） | 00:04.91 | 97| mm:ss.SSS（分:秒.毫秒） | 00:04.536 | 98| hh:mm:ss aa | 5:00:04 上午 | 99| HH | 17 | 100 101### fontColor 102 103fontColor(value: ResourceColor) 104 105设置字体颜色。 106 107**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 108 109**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 110 111**系统能力：** SystemCapability.ArkUI.ArkUI.Full 112 113**参数：** 114 115| 参数名 | 类型 | 必填 | 说明 | 116| ------ | ------------------------------------------ | ---- | ---------- | 117| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 字体颜色。 | 118 119### fontSize 120 121fontSize(value: Length) 122 123设置字体大小。 124 125**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 126 127**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 128 129**系统能力：** SystemCapability.ArkUI.ArkUI.Full 130 131**参数：** 132 133| 参数名 | 类型 | 必填 | 说明 | 134| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 135| value | [Length](ts-types.md#length) | 是 | 字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。不支持设置百分比字符串。 | 136 137### fontStyle 138 139fontStyle(value: FontStyle) 140 141设置字体样式。 142 143**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 144 145**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 146 147**系统能力：** SystemCapability.ArkUI.ArkUI.Full 148 149**参数：** 150 151| 参数名 | 类型 | 必填 | 说明 | 152| ------ | ------------------------------------------- | ---- | --------------------------------------- | 153| value | [FontStyle](ts-appendix-enums.md#fontstyle) | 是 | 字体样式。<br/>默认值：FontStyle.Normal | 154 155### fontWeight 156 157fontWeight(value: number | FontWeight | string) 158 159设置文本的字体粗细，设置过大可能会在不同字体下有截断。 160 161**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 162 163**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 164 165**系统能力：** SystemCapability.ArkUI.ArkUI.Full 166 167**参数：** 168 169| 参数名 | 类型 | 必填 | 说明 | 170| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 171| value | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | 是 | 文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、"bolder"、"lighter"、"regular"、"medium"，分别对应FontWeight中相应的枚举值。<br/>默认值：FontWeight.Normal | 172 173### fontFamily 174 175fontFamily(value: ResourceStr) 176 177设置字体列表。 178 179**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 180 181**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 182 183**系统能力：** SystemCapability.ArkUI.ArkUI.Full 184 185**参数：** 186 187| 参数名 | 类型 | 必填 | 说明 | 188| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | 189| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 字体列表。默认字体'HarmonyOS Sans'。<br>应用当前支持'HarmonyOS Sans'字体和[注册自定义字体](../js-apis-font.md)。<br>卡片当前仅支持'HarmonyOS Sans'字体。 | 190 191### textShadow<sup>11+</sup> 192 193textShadow(value: ShadowOptions | Array<ShadowOptions>) 194 195设置文字阴影效果。该接口支持以数组形式入参，实现多重文字阴影。不支持fill字段, 不支持智能取色模式。 196 197**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 198 199**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 200 201**系统能力：** SystemCapability.ArkUI.ArkUI.Full 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| ------ | ------------------------------------------------------------ | ---- | -------------- | 207| value | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| Array<[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明)> | 是 | 文字阴影效果。 | 208 209### fontFeature<sup>11+</sup> 210 211fontFeature(value: string) 212 213设置文字特性效果，比如数字等宽的特性。 214 215格式为：normal \| \<feature-tag-value\> 216 217\<feature-tag-value\>的格式为：\<string\> \[ \<integer\> \| on \| off ] 218 219\<feature-tag-value\>的个数可以有多个，中间用','隔开。 220 221例如，使用等宽时钟数字的输入格式为："ss01" on。 222 223**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 224 225**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 226 227**系统能力：** SystemCapability.ArkUI.ArkUI.Full 228 229**参数：** 230 231| 参数名 | 类型 | 必填 | 说明 | 232| ------ | ------ | ---- | -------------- | 233| value | string | 是 | 文字特性效果。 | 234 235### contentModifier<sup>12+</sup> 236 237contentModifier(modifier: ContentModifier\<TextClockConfiguration>) 238 239定制TextClock内容区的方法。 240 241**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 242 243**系统能力：** SystemCapability.ArkUI.ArkUI.Full 244 245**参数：** 246 247| 参数名 | 类型 | 必填 | 说明 | 248| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 249| modifier | [ContentModifier\<TextClockConfiguration>](#textclockconfiguration12对象说明) | 是 | 在TextClock组件上，定制内容区的方法。<br/>modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。 | 250 251### dateTimeOptions<sup>12+</sup> 252 253dateTimeOptions(dateTimeOptions: Optional\<DateTimeOptions>) 254 255设置小时是否显示前导0。 256 257**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 258 259**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 260 261**系统能力：** SystemCapability.ArkUI.ArkUI.Full 262 263**参数：** 264 265| 参数名 | 类型 | 必填 | 说明 | 266| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 267| dateTimeOptions | Optional<[DateTimeOptions](../../apis-localization-kit/js-apis-intl.md#datetimeoptions)> | 是 | 设置小时是否显示前导0，只支持设置hour参数，参数值为{hour: "2-digit"}时表示显示前导0，参数值为{hour: "numeric"}时表示不显示前导0。<br/>默认值：undefined，由组件根据应用设置格式自行判断是否显示前导0。| 268 269## 事件 270 271除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 272 273### onDateChange 274 275onDateChange(event: (value: number) => void) 276 277提供时间变化回调，该事件回调间隔为秒。 278 279组件不可见时不回调。 280 281非卡片中使用时，该事件回调间隔为秒。 282 283卡片中使用时，该事件回调间隔为分钟。 284 285**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 286 287**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 288 289**系统能力：** SystemCapability.ArkUI.ArkUI.Full 290 291**参数：** 292 293| 参数名 | 类型 | 必填 | 说明 | 294| ------ | ------ | ---- | ------------------------------------------------------ | 295| value | number | 是 | Unix Time Stamp，即自1970年1月1日（UTC）起经过的秒数。 | 296 297## TextClockController 298 299TextClock容器组件的控制器，可以将该控制器绑定到TextClock组件，通过它控制文本时钟的启动与停止。一个TextClock组件仅支持绑定一个控制器。 300 301**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 302 303**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 304 305**系统能力：** SystemCapability.ArkUI.ArkUI.Full 306 307### 导入对象 308 309```ts 310controller: TextClockController = new TextClockController(); 311``` 312 313### constructor 314 315constructor() 316 317TextClockController的构造函数。 318 319**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 320 321**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 322 323**系统能力：** SystemCapability.ArkUI.ArkUI.Full 324 325### start 326 327start() 328 329启动文本时钟。 330 331**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 332 333**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 334 335**系统能力：** SystemCapability.ArkUI.ArkUI.Full 336 337### stop 338 339stop() 340 341停止文本时钟。 342 343**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 344 345**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 346 347**系统能力：** SystemCapability.ArkUI.ArkUI.Full 348 349## TextClockConfiguration<sup>12+</sup>对象说明 350 351开发者需要自定义class实现ContentModifier接口。 352 353**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 354 355**系统能力：** SystemCapability.ArkUI.ArkUI.Full 356 357| 名称 | 类型 | 必填 | 说明 | 358| ------ | ------ | ------ |-------------------------------- | 359| timeZoneOffset | number | 是 | 当前文本时钟时区偏移量。 | 360| started | boolean | 是 | 指示文本时钟是否启动。<br>默认值：true。 | 361| timeValue | number | 是 | 当前文本时钟时区的UTC秒数。 | 362 363## 示例 364### 示例1 365```ts 366@Entry 367@Component 368struct Second { 369 @State accumulateTime: number = 0 370 // 导入对象 371 controller: TextClockController = new TextClockController() 372 build() { 373 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 374 Text('Current milliseconds is ' + this.accumulateTime) 375 .fontSize(20) 376 // 以12小时制显示东八区的系统时间，精确到秒。 377 TextClock({ timeZoneOffset: -8, controller: this.controller }) 378 .format('aa hh:mm:ss') 379 .onDateChange((value: number) => { 380 this.accumulateTime = value 381 }) 382 .margin(20) 383 .fontSize(30) 384 Button("start TextClock") 385 .margin({ bottom: 10 }) 386 .onClick(() => { 387 // 启动文本时钟 388 this.controller.start() 389 }) 390 Button("stop TextClock") 391 .onClick(() => { 392 // 停止文本时钟 393 this.controller.stop() 394 }) 395 } 396 .width('100%') 397 .height('100%') 398 } 399} 400``` 401 402 403### 示例2 404``` ts 405@Entry 406@Component 407struct TextClockExample { 408 @State textShadows : ShadowOptions | Array<ShadowOptions> = [{ radius: 10, color: Color.Red, offsetX: 10, offsetY: 0 },{ radius: 10, color: Color.Black, offsetX: 20, offsetY: 0 }, 409 { radius: 10, color: Color.Brown, offsetX: 30, offsetY: 0 },{ radius: 10, color: Color.Green, offsetX: 40, offsetY: 0 }, 410 { radius: 10, color: Color.Yellow, offsetX: 100, offsetY: 0 }] 411 build() { 412 Column({ space: 8 }) { 413 TextClock().fontSize(50).textShadow(this.textShadows) 414 } 415 } 416} 417``` 418 419 420### 示例3 421该示例实现了自定义文本时钟样式的功能，自定义样式实现了一个时间选择器组件：通过文本时钟的时区偏移量与UTC秒数，来动态改变时间选择器的选中值，实现时钟效果。同时，根据文本时钟的启动状态，实现文本选择器的12小时制与24小时制的切换。 422 423``` ts 424class MyTextClockStyle implements ContentModifier<TextClockConfiguration> { 425 currentTimeZoneOffset: number = new Date().getTimezoneOffset() / 60 426 title: string = '' 427 428 constructor(title: string) { 429 this.title = title 430 } 431 432 applyContent(): WrappedBuilder<[TextClockConfiguration]> { 433 return wrapBuilder(buildTextClock) 434 } 435} 436 437@Builder 438function buildTextClock(config: TextClockConfiguration) { 439 Row() { 440 Column() { 441 Text((config.contentModifier as MyTextClockStyle).title) 442 .fontSize(20) 443 .margin(20) 444 TimePicker({ 445 selected: (new Date(config.timeValue * 1000 + ((config.contentModifier as MyTextClockStyle).currentTimeZoneOffset - config.timeZoneOffset) * 60 * 60 * 1000)), 446 format: TimePickerFormat.HOUR_MINUTE_SECOND 447 }) 448 .useMilitaryTime(!config.started) 449 } 450 } 451} 452 453@Entry 454@Component 455struct TextClockExample { 456 @State accumulateTime1: number = 0 457 @State timeZoneOffset: number = -8 458 controller1: TextClockController = new TextClockController() 459 controller2: TextClockController = new TextClockController() 460 461 build() { 462 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 463 Text('Current milliseconds is ' + this.accumulateTime1) 464 .fontSize(20) 465 .margin({ top: 20 }) 466 TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller1 }) 467 .format('aa hh:mm:ss') 468 .onDateChange((value: number) => { 469 this.accumulateTime1 = value 470 }) 471 .margin(20) 472 .fontSize(30) 473 TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller2 }) 474 .format('aa hh:mm:ss') 475 .fontSize(30) 476 .contentModifier(new MyTextClockStyle('ContentModifier:')) 477 Button("start TextClock") 478 .margin({ top: 20, bottom: 10 }) 479 .onClick(() => { 480 // 启动文本时钟 481 this.controller1.start() 482 this.controller2.start() 483 }) 484 Button("stop TextClock") 485 .margin({ bottom: 30 }) 486 .onClick(() => { 487 // 停止文本时钟 488 this.controller1.stop() 489 this.controller2.stop() 490 }) 491 492 } 493 .width('100%') 494 .height('100%') 495 } 496} 497``` 498 499 500### 示例4 501该示例演示了dateTimeOptions属性为小时字段增加或去除前导0的功能。24小时制的小时字段默认带有前导0，可通过dateTimeOptions属性去除前导0，12小时制的小时字段默认不带有前导0，可通过dateTimeOptions属性增加前导0。 502``` ts 503@Entry 504@Component 505struct TextClockExample { 506 build() { 507 Column({ space: 8 }) { 508 Row() { 509 Text("24小时制去除前导0：") 510 .fontSize(20) 511 TextClock() 512 .fontSize(20) 513 .format("HH:mm:ss") 514 .dateTimeOptions({hour: "numeric"}) 515 } 516 Row() { 517 Text("12小时制增加前导0：") 518 .fontSize(20) 519 TextClock() 520 .fontSize(20) 521 .format("aa hh:mm:ss") 522 .dateTimeOptions({hour: "2-digit"}) 523 } 524 } 525 .alignItems(HorizontalAlign.Start) 526 } 527} 528``` 529
