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/>设置值为{ 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 366该示例展示了TextClock组件的基本使用方法，通过format属性设置时钟文本的格式。 367 368点击"start TextClock"按钮，按钮回调函数会调用TextClockController启动文本时钟。点击"stop TextClock"按钮，会调用TextClockController暂停文本时钟。 369 370示例中的组件通过设置onDateChange回调函数，在文本时钟更新时，持续修改accumulateTime的内容。 371 372```ts 373@Entry 374@Component 375struct Second { 376 @State accumulateTime: number = 0 377 // 导入对象 378 controller: TextClockController = new TextClockController() 379 380 build() { 381 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 382 Text('Current milliseconds is ' + this.accumulateTime) 383 .fontSize(20) 384 // 以12小时制显示东八区的系统时间，精确到秒。 385 TextClock({ timeZoneOffset: -8, controller: this.controller }) 386 .format('aa hh:mm:ss') 387 .onDateChange((value: number) => { 388 this.accumulateTime = value 389 }) 390 .margin(20) 391 .fontSize(30) 392 Button("start TextClock") 393 .margin({ bottom: 10 }) 394 .onClick(() => { 395 // 启动文本时钟 396 this.controller.start() 397 }) 398 Button("stop TextClock") 399 .onClick(() => { 400 // 停止文本时钟 401 this.controller.stop() 402 }) 403 } 404 .width('100%') 405 .height('100%') 406 } 407} 408``` 409 410 411### 示例2（设定文本阴影样式） 412 413该示例通过textShadow属性设置文本时钟的文本阴影样式。 414 415``` ts 416@Entry 417@Component 418struct TextClockExample { 419 @State textShadows: ShadowOptions | Array<ShadowOptions> = [{ 420 radius: 10, 421 color: Color.Red, 422 offsetX: 10, 423 offsetY: 0 424 }, { 425 radius: 10, 426 color: Color.Black, 427 offsetX: 20, 428 offsetY: 0 429 }, { 430 radius: 10, 431 color: Color.Brown, 432 offsetX: 30, 433 offsetY: 0 434 }, { 435 radius: 10, 436 color: Color.Green, 437 offsetX: 40, 438 offsetY: 0 439 }, { 440 radius: 10, 441 color: Color.Yellow, 442 offsetX: 100, 443 offsetY: 0 444 }] 445 446 build() { 447 Column({ space: 8 }) { 448 TextClock().fontSize(50).textShadow(this.textShadows) 449 } 450 } 451} 452``` 453 454 455### 示例3（设定自定义内容区） 456该示例实现了自定义文本时钟样式的功能，自定义样式实现了一个时间选择器组件：通过文本时钟的时区偏移量与UTC秒数，来动态改变时间选择器的选中值，实现时钟效果。同时，根据文本时钟的启动状态，实现文本选择器的12小时制与24小时制的切换。 457 458``` ts 459class MyTextClockStyle implements ContentModifier<TextClockConfiguration> { 460 currentTimeZoneOffset: number = new Date().getTimezoneOffset() / 60 461 title: string = '' 462 463 constructor(title: string) { 464 this.title = title 465 } 466 467 applyContent(): WrappedBuilder<[TextClockConfiguration]> { 468 return wrapBuilder(buildTextClock) 469 } 470} 471 472@Builder 473function buildTextClock(config: TextClockConfiguration) { 474 Row() { 475 Column() { 476 Text((config.contentModifier as MyTextClockStyle).title) 477 .fontSize(20) 478 .margin(20) 479 TimePicker({ 480 selected: (new Date(config.timeValue * 1000 + 481 ((config.contentModifier as MyTextClockStyle).currentTimeZoneOffset - config.timeZoneOffset) * 60 * 60 * 482 1000)), 483 format: TimePickerFormat.HOUR_MINUTE_SECOND 484 }) 485 .useMilitaryTime(!config.started) 486 } 487 } 488} 489 490@Entry 491@Component 492struct TextClockExample { 493 @State accumulateTime1: number = 0 494 @State timeZoneOffset: number = -8 495 controller1: TextClockController = new TextClockController() 496 controller2: TextClockController = new TextClockController() 497 498 build() { 499 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 500 Text('Current milliseconds is ' + this.accumulateTime1) 501 .fontSize(20) 502 .margin({ top: 20 }) 503 TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller1 }) 504 .format('aa hh:mm:ss') 505 .onDateChange((value: number) => { 506 this.accumulateTime1 = value 507 }) 508 .margin(20) 509 .fontSize(30) 510 TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller2 }) 511 .format('aa hh:mm:ss') 512 .fontSize(30) 513 .contentModifier(new MyTextClockStyle('ContentModifier:')) 514 Button("start TextClock") 515 .margin({ top: 20, bottom: 10 }) 516 .onClick(() => { 517 // 启动文本时钟 518 this.controller1.start() 519 this.controller2.start() 520 }) 521 Button("stop TextClock") 522 .margin({ bottom: 30 }) 523 .onClick(() => { 524 // 停止文本时钟 525 this.controller1.stop() 526 this.controller2.stop() 527 }) 528 529 } 530 .width('100%') 531 .height('100%') 532 } 533} 534``` 535 536 537### 示例4（设置前导零） 538该示例演示了dateTimeOptions属性为小时字段增加或去除前导0的功能。24小时制的小时字段默认带有前导0，可通过dateTimeOptions属性去除前导0，12小时制的小时字段默认不带有前导0，可通过dateTimeOptions属性增加前导0。 539``` ts 540@Entry 541@Component 542struct TextClockExample { 543 build() { 544 Column({ space: 8 }) { 545 Row() { 546 Text("24小时制去除前导0：") 547 .fontSize(20) 548 TextClock() 549 .fontSize(20) 550 .format("HH:mm:ss") 551 .dateTimeOptions({ hour: "numeric" }) 552 } 553 554 Row() { 555 Text("12小时制增加前导0：") 556 .fontSize(20) 557 TextClock() 558 .fontSize(20) 559 .format("aa hh:mm:ss") 560 .dateTimeOptions({ hour: "2-digit" }) 561 } 562 } 563 .alignItems(HorizontalAlign.Start) 564 } 565} 566``` 567
