鸿蒙5.0开辟进阶：UI框架-ArkTS组件（TextClock）

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

• 鸿蒙开辟焦点知识点，看这篇文章就够了
  
• 最新版！鸿蒙HarmonyOS Next应用开辟实战学习路线
  
• 鸿蒙HarmonyOS NEXT开辟技术最全学习路线指南
  
• 鸿蒙应用开辟实战项目，看这一篇文章就够了（部分项目附源码）
  

---

TextClock

TextClock组件通过文本将当前系统时间体现在装备上。支持不同时区的时间体现，最高精度到秒级。
在组件不可见时时间变动将停止，组件的可见状态基于onVisibleAreaChange处置惩罚，可见阈值ratios大于0即视为可见状态。
   阐明
  该组件从API Version 8开始支持。后续版本如有新增内容，则接纳上角标单独标志该内容的起始版本。
  子组件

无
接口

TextClock(options?: { timeZoneOffset?: number, controller?: TextClockController })
卡片本领： 从API version 11开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明timeZoneOffsetnumber否 设置时区偏移量。
取值范围为[-14, 12]，表示东十二区到西十二区，此中负值表示东时区，正值表示西时区，比如东八区为-8。设置值为该取值范围内的浮点数时会进行取整，舍弃小数部分。
对横跨国际日界线的国家或地区，用-13（UTC+13）和-14（UTC+14）来保证整个国家大概区域处在雷同的时间，当设置的值不在取值范围内时，将使用当前系统的时区偏移量。
默认值：当前系统的时区偏移量
从API version 11开始，设置值为{ 9.5, 3.5, -3.5, -4.5, -5.5, -5.75, -6.5, -9.5, -10.5, -12.75 }聚集中的浮点数时不再进行取整。
controllerTextClockController否绑定一个控制器，用来控制文本时钟的状态。 属性

除支持通用属性和文本通用属性的fontColor、fontSize、fontStyle、fontWeight、fontFamily外，还支持以下属性：
format

format(value: string)
设置体现时间格式，如“yyyy/MM/dd”、“yyyy-MM-dd”。
y：年（yyyy表示完整年份，yy表示年份后两位）
M：月（若想使用01月则使用MM）
d：日（若想使用01日则使用dd）
E：星期（若想使用星期六则使用EEEE，若想使用周六则使用E、EE、EEE）H：小时（24小时制） h：小时（12小时制）
m：分钟
s：秒
SS：厘秒(format中S个数<3，全部按厘秒处置惩罚)
SSS：毫秒(format中S个数>=3，全部按毫秒处置惩罚)
a：上午/下午（当设置小时制式为H时，该参数不生效）
日期间隔符："年代日"、“/”、"-"、"."（可以自界说间隔符样式，间隔符不可以为字母，汉字则作为间隔符处置惩罚）
允许自行拼接组合体现格式，即：年、月、日、星期、时、分、秒、毫秒可拆分为子元素，可自行排布组合。时间更新频率最高为一秒一次，不建议单独设置厘秒和毫秒格式。
当设置无效字母时（非上述字母被以为是无效字母），该字母会被忽略。如果format满是无效字母时，体现格式跟随系统语言和系统小时制。例如系统语言为中文时，12小时制体现格式为yyyy/MM/dd aa hh:mm:ss.SSS，24小时制体现格式为yyyy/MM/dd HH:mm:ss.SSS。
若format为空大概undefined，则使用默认值。
非卡片中默认值：12小时制：aa hh:mm:ss，24小时制：HH:mm:ss。
卡片中默认值：12小时制：hh:mm，24小时制：HH:mm 。
卡片中使用时，最小时间单位为分钟。如果设置格式中有秒或厘秒按默认值处置惩罚。
卡片本领： 从API version 11开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valuestring是体现时间格式。 以下是format输入的格式样式及对应的体现效果：
输入格式体现效果yyyy年M月d日 EEEE2023年2月4日 星期六yyyy年M月d日2023年2月4日M月d日 EEEE2月4日 星期六M月d日2月4日MM/dd/yyyy02/04/2023EEEE MM月dd日星期六 02月04日yyyy（完整年份）2023年yy（年份后两位）23年MM（完整月份）02月M（月份）2月dd（完整日期）04日d（日期）4日EEEE（完整星期）星期六E、EE、EEE（简写星期）周六yyyy年M月d日2023年2月4日yyyy/M/d2023/2/4yyyy-M-d2023-2-4yyyy.M.d2023.2.4HH:mm:ss（时:分:秒）17:00:04aa hh:mm:ss（时:分:秒）上午 5:00:04hh:mm:ss（时:分:秒）5:00:04HH:mm（时:分）17:00aa hh:mm（时:分）上午 5:00hh:mm（时:分）5:00mm:ss（分:秒）00:04mm:ss.SS（分:秒.厘秒）00:04.91mm:ss.SSS（分:秒.毫秒）00:04.536hh:mm:ss aa5:00:04 上午HH17 fontColor

fontColor(value: ResourceColor)
设置字体颜色。
卡片本领： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueResourceColor是字体颜色。 fontSize

fontSize(value: Length)
设置字体大小。
卡片本领： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueLength是字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。不支持设置百分比字符串。 fontStyle

fontStyle(value: FontStyle)
设置字体样式。
卡片本领： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueFontStyle是 字体样式。
默认值：FontStyle.Normal
  fontWeight

fontWeight(value: number | FontWeight | string)
设置文本的字体粗细，设置过大可能会在不同字体下有截断。
卡片本领： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valuenumber | FontWeight | string是 文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默以为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串情势，例如"400"，以及"bold"、"bolder"、"lighter"、"regular"、"medium"，分别对应FontWeight中相应的枚举值。
默认值：FontWeight.Normal
  fontFamily

fontFamily(value: ResourceStr)
设置字体列表。
卡片本领： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueResourceStr是 字体列表。默认字体'HarmonyOS Sans'。
应用当前支持'HarmonyOS Sans'字体和注册自界说字体。
卡片当前仅支持'HarmonyOS Sans'字体。
  textShadow11+

textShadow(value: ShadowOptions | Array<ShadowOptions>)
设置文字阴影效果。该接口支持以数组情势入参，实现多重文字阴影。不支持fill字段, 不支持智能取色模式。
卡片本领： 从API version 11开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valueShadowOptions | Array<ShadowOptions>是文字阴影效果。 fontFeature11+

fontFeature(value: string)
设置文字特性效果，比如数字等宽的特性。
格式为：normal | <feature-tag-value>
<feature-tag-value>的格式为：<string> [ <integer> | on | off ]
<feature-tag-value>的个数可以有多个，中间用','隔开。
例如，使用等宽时钟数字的输入格式为："ss01" on。
卡片本领： 从API version 11开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valuestring是文字特性效果。 contentModifier12+

contentModifier(modifier: ContentModifier<TextClockConfiguration>)
定制TextClock内容区的方法。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明modifierContentModifier<TextClockConfiguration>是 在TextClock组件上，定制内容区的方法。
modifier: 内容修改器，开辟者需要自界说class实现ContentModifier接口。
  dateTimeOptions12+

dateTimeOptions(dateTimeOptions: Optional<DateTimeOptions>)
设置小时是否体现前导0。
卡片本领： 从API version 12开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明dateTimeOptionsOptional<DateTimeOptions>是 设置小时是否体现前导0，只支持设置hour参数，参数值为{hour: "2-digit"}时表示体现前导0，参数值为{hour: "numeric"}时表示不体现前导0。
默认值：undefined，由组件根据应用设置格式自行判定是否体现前导0。
  事件

除支持通用事件外，还支持以下事件：
onDateChange

onDateChange(event: (value: number) => void)
提供时间变化回调，该事件回调间隔为秒。
组件不可见时不回调。
非卡片中使用时，该事件回调间隔为秒。
卡片中使用时，该事件回调间隔为分钟。
卡片本领： 从API version 11开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填阐明valuenumber是Unix Time Stamp，即自1970年1月1日（UTC）起经过的秒数。 TextClockController

TextClock容器组件的控制器，可以将该控制器绑定到TextClock组件，通过它控制文本时钟的启动与停止。一个TextClock组件仅支持绑定一个控制器。
卡片本领： 从API version 11开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
导入对象

1. controller: TextClockController = new TextClockController();

复制代码

constructor

constructor()
TextClockController的构造函数。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
start

start()
启动文本时钟。
卡片本领： 从API version 11开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
stop

stop()
停止文本时钟。
卡片本领： 从API version 11开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
TextClockConfiguration12+对象阐明

开辟者需要自界说class实现ContentModifier接口。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统本领： SystemCapability.ArkUI.ArkUI.Full
名称类型必填阐明timeZoneOffsetnumber是当前文本时钟时区偏移量。startedboolean是 指示文本时钟是否启动。
默认值：true。
timeValuenumber是当前文本时钟时区的UTC秒数。 示例

示例1（支持启停的文本样式时钟）

该示例展示了TextClock组件的根本使用方法，通过format属性设置时钟文本的格式。
点击"start TextClock"按钮，按钮回调函数会调用TextClockController启动文本时钟。点击"stop TextClock"按钮，会调用TextClockController暂停文本时钟。
示例中的组件通过设置onDateChange回调函数，在文本时钟更新时，持续修改accumulateTime的内容。

1. @Entry
2. @Component
3. struct Second {
4.   @State accumulateTime: number = 0
5.   // 导入对象
6.   controller: TextClockController = new TextClockController()
8.   build() {
9.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
10.       Text('Current milliseconds is ' + this.accumulateTime)
11.         .fontSize(20)
12.       // 以12小时制显示东八区的系统时间，精确到秒。
13.       TextClock({ timeZoneOffset: -8, controller: this.controller })
14.         .format('aa hh:mm:ss')
15.         .onDateChange((value: number) => {
16.           this.accumulateTime = value
17.         })
18.         .margin(20)
19.         .fontSize(30)
20.       Button("start TextClock")
21.         .margin({ bottom: 10 })
22.         .onClick(() => {
23.           // 启动文本时钟
24.           this.controller.start()
25.         })
26.       Button("stop TextClock")
27.         .onClick(() => {
28.           // 停止文本时钟
29.           this.controller.stop()
30.         })
31.     }
32.     .width('100%')
33.     .height('100%')
34.   }
35. }

复制代码

示例2（设定文本阴影样式）

该示例通过textShadow属性设置文本时钟的文本阴影样式。

1. @Entry
2. @Component
3. struct TextClockExample {
4.   @State textShadows: ShadowOptions | Array<ShadowOptions> = [{
5.     radius: 10,
6.     color: Color.Red,
7.     offsetX: 10,
8.     offsetY: 0
9.   }, {
10.     radius: 10,
11.     color: Color.Black,
12.     offsetX: 20,
13.     offsetY: 0
14.   }, {
15.     radius: 10,
16.     color: Color.Brown,
17.     offsetX: 30,
18.     offsetY: 0
19.   }, {
20.     radius: 10,
21.     color: Color.Green,
22.     offsetX: 40,
23.     offsetY: 0
24.   }, {
25.     radius: 10,
26.     color: Color.Yellow,
27.     offsetX: 100,
28.     offsetY: 0
29.   }]
31.   build() {
32.     Column({ space: 8 }) {
33.       TextClock().fontSize(50).textShadow(this.textShadows)
34.     }
35.   }
36. }

复制代码

示例3（设定自界说内容区）

该示例实现了自界说文本时钟样式的功能，自界说样式实现了一个时间选择器组件：通过文本时钟的时区偏移量与UTC秒数，来动态改变时间选择器的选中值，实现时钟效果。同时，根据文本时钟的启动状态，实现文本选择器的12小时制与24小时制的切换。

1. class MyTextClockStyle implements ContentModifier<TextClockConfiguration> {
2.   currentTimeZoneOffset: number = new Date().getTimezoneOffset() / 60
3.   title: string = ''
5.   constructor(title: string) {
6.     this.title = title
7.   }
9.   applyContent(): WrappedBuilder<[TextClockConfiguration]> {
10.     return wrapBuilder(buildTextClock)
11.   }
12. }
14. @Builder
15. function buildTextClock(config: TextClockConfiguration) {
16.   Row() {
17.     Column() {
18.       Text((config.contentModifier as MyTextClockStyle).title)
19.         .fontSize(20)
20.         .margin(20)
21.       TimePicker({
22.         selected: (new Date(config.timeValue * 1000 +
23.           ((config.contentModifier as MyTextClockStyle).currentTimeZoneOffset - config.timeZoneOffset) * 60 * 60 *
24.             1000)),
25.         format: TimePickerFormat.HOUR_MINUTE_SECOND
26.       })
27.         .useMilitaryTime(!config.started)
28.     }
29.   }
30. }
32. @Entry
33. @Component
34. struct TextClockExample {
35.   @State accumulateTime1: number = 0
36.   @State timeZoneOffset: number = -8
37.   controller1: TextClockController = new TextClockController()
38.   controller2: TextClockController = new TextClockController()
40.   build() {
41.     Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
42.       Text('Current milliseconds is ' + this.accumulateTime1)
43.         .fontSize(20)
44.         .margin({ top: 20 })
45.       TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller1 })
46.         .format('aa hh:mm:ss')
47.         .onDateChange((value: number) => {
48.           this.accumulateTime1 = value
49.         })
50.         .margin(20)
51.         .fontSize(30)
52.       TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller2 })
53.         .format('aa hh:mm:ss')
54.         .fontSize(30)
55.         .contentModifier(new MyTextClockStyle('ContentModifier:'))
56.       Button("start TextClock")
57.         .margin({ top: 20, bottom: 10 })
58.         .onClick(() => {
59.           // 启动文本时钟
60.           this.controller1.start()
61.           this.controller2.start()
62.         })
63.       Button("stop TextClock")
64.         .margin({ bottom: 30 })
65.         .onClick(() => {
66.           // 停止文本时钟
67.           this.controller1.stop()
68.           this.controller2.stop()
69.         })
71.     }
72.     .width('100%')
73.     .height('100%')
74.   }
75. }

复制代码

示例4（设置前导零）

该示例演示了dateTimeOptions属性为小时字段增加或去除前导0的功能。24小时制的小时字段默认带有前导0，可通过dateTimeOptions属性去除前导0，12小时制的小时字段默认不带有前导0，可通过dateTimeOptions属性增加前导0。

1. @Entry
2. @Component
3. struct TextClockExample {
4.   build() {
5.     Column({ space: 8 }) {
6.       Row() {
7.         Text("24小时制去除前导0：")
8.           .fontSize(20)
9.         TextClock()
10.           .fontSize(20)
11.           .format("HH:mm:ss")
12.           .dateTimeOptions({ hour: "numeric" })
13.       }
15.       Row() {
16.         Text("12小时制增加前导0：")
17.           .fontSize(20)
18.         TextClock()
19.           .fontSize(20)
20.           .format("aa hh:mm:ss")
21.           .dateTimeOptions({ hour: "2-digit" })
22.       }
23.     }
24.     .alignItems(HorizontalAlign.Start)
25.   }
26. }

复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。