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