#跟着若城学鸿蒙# UI组件篇-TextClock及其属性

Huang兄

935人浏览 · 2025-05-19 20:28:34

Huang兄 · 2025-05-19 20:28:34 发布

TextClock是ArkUI框架中用于显示系统时间的文本组件，它提供了丰富的功能和灵活的配置选项，可以满足各种时间显示需求。本文将全面介绍TextClock组件的特性、接口、属性、事件以及使用示例。

TextClock组件概述

TextClock组件是一个用于在设备上显示当前系统时间的文本组件，支持不同时区的时间显示和秒级精度。该组件从API Version 8开始支持，后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

TextClock组件的主要特点包括：

支持不同时区的时间显示
最高精度到秒级
提供丰富的属性和事件
允许自定义显示格式、字体样式、阴影效果等
通过控制器实现启停功能

在组件不可见时，时间变动将停止。组件的可见状态基于onVisibleAreaChange处理，可见阈值ratios大于0即视为可见状态。

子组件

TextClock组件不支持任何子组件。

接口

TextClock组件提供了以下构造函数：

TextClock(options?: { timeZoneOffset?: number, controller?: TextClockController })

从API version 11开始，该接口支持在ArkTS卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

参数说明：

参数名	类型	必填	说明
timeZoneOffset	number	否	设置时区偏移量。取值范围为[-14, 12]，表示东十二区到西十二区，其中负值表示东时区，正值表示西时区，比如东八区为-8。设置值为该取值范围内的浮点数时会进行取整，舍弃小数部分。对横跨国际日界线的国家或地区，用-13（UTC+13）和-14（UTC+14）来保证整个国家或者区域处在相同的时间，当设置的值不在取值范围内时，将使用当前系统的时区偏移量。默认值：当前系统的时区偏移量。设置值为{ 9.5, 3.5, -3.5, -4.5, -5.5, -5.75, -6.5, -9.5, -10.5, -12.75 }集合中的浮点数时不进行取整。
controller	TextClockController	否	绑定一个控制器，用来控制文本时钟的状态。

属性

TextClock组件除支持通用属性外，还支持以下属性：

format

设置显示时间格式：

format(value: string)

参数说明：

参数名	类型	必填	说明
value	string	是	显示时间格式。

format支持的格式字符：

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卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

format输入的格式样式及对应的显示效果示例：

输入格式	显示效果
yyyy年M月d日 EEEE	2023年2月4日星期六

fontColor

设置字体颜色：

fontColor(value: ResourceColor)

从API version 11开始，该接口支持在ArkTS卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

参数说明：

参数名	类型	必填	说明
value	ResourceColor	是	字体颜色。

参数名	类型	必填	说明
value	Length	是	字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。不支持设置百分比字符串。

fontStyle

设置字体样式：

fontStyle(value: FontStyle)

从API version 11开始，该接口支持在ArkTS卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

参数说明：

参数名	类型	必填	说明
value	FontStyle	是	字体样式。默认值：FontStyle.Normal

fontWeight

设置文本的字体粗细：

fontWeight(value: number | FontWeight | string)

从API version 11开始，该接口支持在ArkTS卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

参数说明：

参数名	类型	必填	说明
value	number	FontWeight	string

fontFamily

设置字体列表：

fontFamily(value: ResourceStr)

从API version 11开始，该接口支持在ArkTS卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

参数说明：

参数名	类型	必填	说明
value	ResourceStr	是	字体列表。默认字体'HarmonyOS Sans'。应用当前支持'HarmonyOS Sans'字体和注册自定义字体。卡片当前仅支持'HarmonyOS Sans'字体。

textShadow11+

设置文字阴影效果：

textShadow(value: ShadowOptions | Array<ShadowOptions>)

该接口支持以数组形式入参，实现多重文字阴影。不支持fill字段，不支持智能取色模式。

从API version 11开始，该接口支持在ArkTS卡片中使用。
从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

参数说明：

参数名	类型	必填	说明
value	ShadowOptions	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 version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

参数说明：

参数名	类型	必填	说明
value	string	是	文字特性效果。

contentModifier12+

定制TextClock内容区的方法：

contentModifier(modifier: ContentModifier<TextClockConfiguration>)

从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

参数说明：

参数名	类型	必填	说明
modifier	ContentModifier<TextClockConfiguration>	是	在TextClock组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

dateTimeOptions12+

设置小时是否显示前导0：

dateTimeOptions(dateTimeOptions: Optional<DateTimeOptions>)

从API version 12开始，该接口支持在ArkTS卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

参数说明：

参数名	类型	必填	说明
dateTimeOptions	Optional<DateTimeOptions>	是	设置小时是否显示前导0，只支持设置hour参数，参数值为{hour: "2-digit"}时表示显示前导0，参数值为{hour: "numeric"}时表示不显示前导0。默认值：undefined，由组件根据应用设置格式自行判断是否显示前导0。

事件

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

onDateChange

提供时间变化回调：

onDateChange(event: (value: number) => void)

该事件回调间隔为秒。组件不可见时不回调。

非卡片中使用时，该事件回调间隔为秒。
卡片中使用时，该事件回调间隔为分钟。

从API version 11开始，该接口支持在ArkTS卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

参数说明：

参数名	类型	必填	说明
value	number	是	Unix Time Stamp，即自1970年1月1日（UTC）起经过的秒数。

TextClockController

TextClock容器组件的控制器，可以将该控制器绑定到TextClock组件，通过它控制文本时钟的启动与停止。一个TextClock组件仅支持绑定一个控制器。

从API version 11开始，该接口支持在ArkTS卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

导入对象

controller: TextClockController = new TextClockController();

constructor

TextClockController的构造函数：

constructor()

从API version 11开始，该接口支持在ArkTS卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

start

启动文本时钟：

start()

从API version 11开始，该接口支持在ArkTS卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

stop

停止文本时钟：

stop()

从API version 11开始，该接口支持在ArkTS卡片和原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

TextClockConfiguration12+对象说明

开发者需要自定义class实现ContentModifier接口。

从API version 12开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
timeZoneOffset	number	是	当前文本时钟时区偏移量。
started	boolean	是	指示文本时钟是否启动。默认值：true，true表示启动文本时钟，false表示关闭文本时钟。
timeValue	number	是	当前文本时钟时区的UTC秒数。

示例

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

该示例展示了TextClock组件的基本使用方法，通过format属性设置时钟文本的格式。

点击"start TextClock"按钮，按钮回调函数会调用TextClockController启动文本时钟。点击"stop TextClock"按钮，会调用TextClockController暂停文本时钟。

示例中的组件通过设置onDateChange回调函数，在文本时钟更新时，持续修改accumulateTime的内容。

@Entry
@Component
struct Second {
  @State accumulateTime: number = 0
  // 导入对象
  controller: TextClockController = new TextClockController()

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Text('Current milliseconds is ' + this.accumulateTime)
        .fontSize(20)
      // 以12小时制显示东八区的系统时间，精确到秒。
      TextClock({ timeZoneOffset: -8, controller: this.controller })
        .format('aa hh:mm:ss')
        .onDateChange((value: number) => {
          this.accumulateTime = value
        })
        .margin(20)
        .fontSize(30)
      Button("start TextClock")
        .margin({ bottom: 10 })
        .onClick(() => {
          // 启动文本时钟
          this.controller.start()
        })
      Button("stop TextClock").onClick(() => {
        // 停止文本时钟
        this.controller.stop()
      })
    }.width('100%').height('100%')
  }
}

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

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

@Entry
@Component
struct TextClockExample {
  @State textShadows: ShadowOptions | Array<ShadowOptions> = [{
    radius: 10,
    color: Color.Red,
    offsetX: 10,
    offsetY: 0
  }, {
    radius: 10,
    color: Color.Black,
    offsetX: 20,
    offsetY: 0
  }, {
    radius: 10,
    color: Color.Brown,
    offsetX: 30,
    offsetY: 0
  }, {
    radius: 10,
    color: Color.Green,
    offsetX: 40,
    offsetY: 0
  }, {
    radius: 10,
    color: Color.Yellow,
    offsetX: 100,
    offsetY: 0
  }]

  build() {
    Column({ space: 8 }) {
      TextClock().fontSize(50).textShadow(this.textShadows)
    }
  }
}

示例3（设定自定义内容区）

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

class MyTextClockStyle implements ContentModifier<TextClockConfiguration> {
  currentTimeZoneOffset: number = new Date().getTimezoneOffset() / 60
  title: string = ''

  constructor(title: string) {
    this.title = title
  }

  applyContent(): WrappedBuilder<[TextClockConfiguration]> {
    return wrapBuilder(buildTextClock)
  }
}

@Builder
function buildTextClock(config: TextClockConfiguration) {
  Row() {
    Column() {
      Text((config.contentModifier as MyTextClockStyle).title).fontSize(20).margin(20)
      TimePicker({
        selected: (new Date(config.timeValue * 1000 +
          ((config.contentModifier as MyTextClockStyle).currentTimeZoneOffset - config.timeZoneOffset) * 60 * 60 *
            1000)),
        format: TimePickerFormat.HOUR_MINUTE_SECOND
      }).useMilitaryTime(!config.started)
    }
  }
}

@Entry
@Component
struct TextClockExample {
  @State accumulateTime1: number = 0
  @State timeZoneOffset: number = -8
  controller1: TextClockController = new TextClockController()
  controller2: TextClockController = new TextClockController()

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Text('Current milliseconds is ' + this.accumulateTime1).fontSize(20).margin({ top: 20 })
      TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller1 })
        .format('aa hh:mm:ss')
        .onDateChange((value: number) => {
          this.accumulateTime1 = value
        })
        .margin(20)
        .fontSize(30)
      TextClock({ timeZoneOffset: this.timeZoneOffset, controller: this.controller2 })
        .format('aa hh:mm:ss')
        .fontSize(30)
        .contentModifier(new MyTextClockStyle('ContentModifier:'))
      Button("start TextClock")
        .margin({ top: 20, bottom: 10 })
        .onClick(() => {
          // 启动文本时钟
          this.controller1.start()
          this.controller2.start()
        })
      Button("stop TextClock")
        .margin({ bottom: 30 })
        .onClick(() => {
          // 停止文本时钟
          this.controller1.stop()
          this.controller2.stop()
        })
    }.width('100%').height('100%')
  }
}

示例4（设置前导零）

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

@Entry
@Component
struct TextClockExample {
  build() {
    Column({ space: 8 }) {
      Row() {
        Text("24小时制去除前导0：").fontSize(20)
        TextClock().fontSize(20).format("HH:mm:ss").dateTimeOptions({ hour: "numeric" })
      }

      Row() {
        Text("12小时制增加前导0：").fontSize(20)
        TextClock().fontSize(20).format("aa hh:mm:ss").dateTimeOptions({ hour: "2-digit" })
      }
    }.alignItems(HorizontalAlign.Start)
  }
}

总结

TextClock组件是ArkUI框架中一个功能强大的时间显示组件，它提供了丰富的自定义选项和灵活的控制方式。通过本文的介绍，我们了解了TextClock组件的各种属性和事件，以及如何通过TextClockController来控制时钟的启停。TextClock组件可以满足各种时间显示需求，从简单的数字时钟到复杂的自定义样式时钟，都能轻松实现。

----

以上