鸿蒙HarmonyOS NEXT开发：TextClock（基础组件）

蜀道叁QAQ

于 2024-08-19 21:55:13 发布

阅读量510

点赞数 4

分类专栏：鸿蒙 ArkTS 文章标签： harmonyos 华为 android 驱动开发鸿蒙

本文链接：https://blog.csdn.net/shudaoshanBBQ/article/details/141335833

版权

鸿蒙同时被 2 个专栏收录

125 篇文章 0 订阅

订阅专栏

ArkTS

120 篇文章 0 订阅

订阅专栏

TextClock

TextClock组件通过文本将当前系统时间显示在设备上。支持不同时区的时间显示，最高精度到秒级。

说明：

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

无

接口

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

卡片能力： 从API version 11开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

参数名	参数类型	必填	参数描述
timeZoneOffset	number	否	设置时区偏移量。取值范围为[-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 }集合中的浮点数时不再进行取整。
controller	TextClockController	否	绑定一个控制器，用来控制文本时钟的状态。

属性

除支持通用属性和文本通用属性的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

参数：

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

以下是format输入的格式样式及对应的显示效果：

输入格式	显示效果
yyyy年M月d日 EEEE	2023年2月4日星期六
yyyy年M月d日	2023年2月4日
M月d日 EEEE	2月4日星期六
M月d日	2月4日
MM/dd/yyyy	02/04/2023
EEEE 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/d	2023/2/4
yyyy-M-d	2023-2-4
yyyy.M.d	2023.2.4
HH:mm:ss（时:分:秒）	17:00:04
aa hh:mm:ss（时:分:秒）	上午 5:00:04
hh:mm:ss（时:分:秒）	5:00:04
HH:mm（时:分）	17:00
aa hh:mm（时:分）	上午 5:00
hh:mm（时:分）	5:00
mm:ss（分:秒）	00:04
mm:ss.SS（分:秒.厘秒）	00:04.91
mm:ss.SSS（分:秒.毫秒）	00:04.536
hh:mm:ss aa	5:00:04 上午
HH	17

textShadow11+

textShadow(value: ShadowOptions | Array<ShadowOptions>)

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

卡片能力： 从API version 11开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从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： 从API version 12开始，该接口支持在原子化服务中使用。

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

参数：

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

contentModifier12+

contentModifier(modifier: ContentModifier<TextClockConfiguration>)

定制TextClock内容区的方法。

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

参数：

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

事件

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

onDateChange

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

提供时间变化回调，该事件回调间隔为秒。

组件不可见时不回调。

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

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

卡片能力： 从API version 11开始，该接口支持在ArkTS卡片中使用。

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

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

参数：

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

TextClockController

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

卡片能力： 从API version 11开始，该接口支持在ArkTS卡片中使用。

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

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

导入对象

controller: TextClockController = new TextClockController();
ts

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接口。

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

参数名	类型	默认值	说明
timeZoneOffset	number	-	当前文本时钟时区偏移量。
started	boolean	true	指示文本时钟是否启动。
timeValue	number	-	当前文本时钟时区的UTC秒数。

示例

示例1

@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%')
  }
}
ts

示例2

@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)
    }
  }
}
ts

示例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%')
  }
}
ts

最后

有很多小伙伴不知道学习哪些鸿蒙开发技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？而且学习时频繁踩坑，最终浪费大量时间。所以有一份实用的鸿蒙（HarmonyOS NEXT）资料用来跟着学习是非常有必要的。

这份鸿蒙（HarmonyOS NEXT）资料包含了鸿蒙开发必掌握的核心知识要点，内容包含了（ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、OpenHarmony南向开发、鸿蒙项目实战等等）鸿蒙（HarmonyOS NEXT）技术知识点。

希望这一份鸿蒙学习资料能够给大家带来帮助，有需要的小伙伴自行领取，限时开源，先到先得~无套路领取！！

获取这份完整版高清学习路线，请点击→纯血版全套鸿蒙HarmonyOS NEXT学习资料

鸿蒙（HarmonyOS NEXT）最新学习路线

HarmonOS基础技能

HarmonOS就业必备技能
HarmonOS多媒体技术

鸿蒙NaPi组件进阶

HarmonOS高级技能

初识HarmonOS内核
实战就业级设备开发

有了路线图，怎么能没有学习资料呢，小编也准备了一份联合鸿蒙官方发布笔记整理收纳的一套系统性的鸿蒙（OpenHarmony ）学习手册（共计1236页）与鸿蒙（OpenHarmony ）开发入门教学视频，内容包含：ArkTS、ArkUI、Web开发、应用模型、资源分类…等知识点。

获取以上完整版高清学习路线，请点击→纯血版全套鸿蒙HarmonyOS NEXT学习资料