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](#textclockoptions14对象说明)| 否 | 通过文本显示当前系统时间的组件参数。 | 31 32## TextClockOptions<sup>14+</sup>对象说明 33 34**卡片能力：** 从API version 14开始，该接口支持在ArkTS卡片中使用。 35 36**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 37 38**系统能力：** SystemCapability.ArkUI.ArkUI.Full 39 40| 参数名 | 类型 | 必填 | 说明 | 41| -------------- | -------- | ------ | --------------------------------------------------------------------------- | 42| 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 }集合中的浮点数时不进行取整。| 43| controller | [TextClockController](#textclockcontroller) | 否 | 绑定一个控制器，用来控制文本时钟的状态。| 44 45## 属性 46 47除支持[通用属性](ts-universal-attributes-size.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-universal-events-click.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。 | 373| timeValue | number | 是 | 当前文本时钟时区的UTC秒数。 | 374 375## 示例 376### 示例1 377```ts 378@Entry 379@Component 380struct Second { 381 @State accumulateTime: number = 0 382 // 导入对象 383 controller: TextClockController = new TextClockController() 384 build() { 385 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 386 Text('Current milliseconds is ' + this.accumulateTime) 387 .fontSize(20) 388 // 以12小时制显示东八区的系统时间，精确到秒。 389 TextClock({ timeZoneOffset: -8, controller: this.controller }) 390 .format('aa hh:mm:ss') 391 .onDateChange((value: number) => { 392 this.accumulateTime = value 393 }) 394 .margin(20) 395 .fontSize(30) 396 Button("start TextClock") 397 .margin({ bottom: 10 }) 398 .onClick(() => { 399 // 启动文本时钟 400 this.controller.start() 401 }) 402 Button("stop TextClock") 403 .onClick(() => { 404 // 停止文本时钟 405 this.controller.stop() 406 }) 407 } 408 .width('100%') 409 .height('100%') 410 } 411} 412``` 413 414 415### 示例2 416``` ts 417@Entry 418@Component 419struct TextClockExample { 420 @State textShadows : ShadowOptions | Array<ShadowOptions> = [{ radius: 10, color: Color.Red, offsetX: 10, offsetY: 0 },{ radius: 10, color: Color.Black, offsetX: 20, offsetY: 0 }, 421 { radius: 10, color: Color.Brown, offsetX: 30, offsetY: 0 },{ radius: 10, color: Color.Green, offsetX: 40, offsetY: 0 }, 422 { radius: 10, color: Color.Yellow, offsetX: 100, offsetY: 0 }] 423 build() { 424 Column({ space: 8 }) { 425 TextClock().fontSize(50).textShadow(this.textShadows) 426 } 427 } 428} 429``` 430 431 432### 示例3 433该示例实现了自定义文本时钟样式的功能，自定义样式实现了一个时间选择器组件：通过文本时钟的时区偏移量与UTC秒数，来动态改变时间选择器的选中值，实现时钟效果。同时，根据文本时钟的启动状态，实现文本选择器的12小时制与24小时制的切换。 434 435``` ts 436class MyTextClockStyle implements ContentModifier<TextClockConfiguration> { 437 currentTimeZoneOffset: number = new Date().getTimezoneOffset() / 60 438 title: string = '' 439 440 constructor(title: string) { 441 this.title = title 442 } 443 444 applyContent(): WrappedBuilder<[TextClockConfiguration]> { 445 return wrapBuilder(buildTextClock) 446 } 447} 448 449@Builder 450function buildTextClock(config: TextClockConfiguration) { 451 Row() { 452 Column() { 453 Text((config.contentModifier as MyTextClockStyle).title) 454 .fontSize(20) 455 .margin(20) 456 TimePicker({ 457 selected: (new Date(config.timeValue * 1000 + ((config.contentModifier as MyTextClockStyle).currentTimeZoneOffset - config.timeZoneOffset) * 60 * 60 * 1000)), 458 format: TimePickerFormat.HOUR_MINUTE_SECOND 459 }) 460 .useMilitaryTime(!config.started) 461 } 462 } 463} 464 465@Entry 466@Component 467struct TextClockExample { 468 @State accumulateTime1: number = 0 469 @State timeZoneOffset: number = -8 470 controller1: TextClockController = new TextClockController() 471 controller2: TextClockController = new TextClockController() 472 473 build() { 474 Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) { 475 Text('Current milliseconds is ' + this.accumulateTime1) 476 .fontSize(20) 477 .margin({ top: 20 }) 478 TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller1 }) 479 .format('aa hh:mm:ss') 480 .onDateChange((value: number) => { 481 this.accumulateTime1 = value 482 }) 483 .margin(20) 484 .fontSize(30) 485 TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller2 }) 486 .format('aa hh:mm:ss') 487 .fontSize(30) 488 .contentModifier(new MyTextClockStyle('ContentModifier:')) 489 Button("start TextClock") 490 .margin({ top: 20, bottom: 10 }) 491 .onClick(() => { 492 // 启动文本时钟 493 this.controller1.start() 494 this.controller2.start() 495 }) 496 Button("stop TextClock") 497 .margin({ bottom: 30 }) 498 .onClick(() => { 499 // 停止文本时钟 500 this.controller1.stop() 501 this.controller2.stop() 502 }) 503 504 } 505 .width('100%') 506 .height('100%') 507 } 508} 509``` 510 511 512### 示例4 513该示例演示了dateTimeOptions属性为小时字段增加或去除前导0的功能。24小时制的小时字段默认带有前导0，可通过dateTimeOptions属性去除前导0，12小时制的小时字段默认不带有前导0，可通过dateTimeOptions属性增加前导0。 514``` ts 515@Entry 516@Component 517struct TextClockExample { 518 build() { 519 Column({ space: 8 }) { 520 Row() { 521 Text("24小时制去除前导0：") 522 .fontSize(20) 523 TextClock() 524 .fontSize(20) 525 .format("HH:mm:ss") 526 .dateTimeOptions({hour: "numeric"}) 527 } 528 Row() { 529 Text("12小时制增加前导0：") 530 .fontSize(20) 531 TextClock() 532 .fontSize(20) 533 .format("aa hh:mm:ss") 534 .dateTimeOptions({hour: "2-digit"}) 535 } 536 } 537 .alignItems(HorizontalAlign.Start) 538 } 539} 540``` 541
