TextClock

TextClock組件通過文本將當前系統時間顯示在設備上。支持不同時區的時間顯示，最高精度到秒級。

說明：
開發前請熟悉鴻蒙開發指導文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]
該組件從API Version 8開始支持。后續版本如有新增內容，則采用上角標單獨標記該內容的起始版本。

子組件

無

接口

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

參數：

參數名	參數類型	必填	參數描述
timeZoneOffset	number	否	設置時區偏移量。取值范圍為[-14, 12]，表示東十二區到西十二區，其中負值表示東時區，正值表示西時區，比如東八區為-8。對橫跨國際日界線的國家或地區，用-13（UTC+13）和-14（UTC+14）來保證整個國家或者區域處在相同的時間，當設置的值不在取值范圍內時，將使用當前系統的時區偏移量。默認值：當前系統的時區偏移量
controller	[TextClockController]	否	綁定一個控制器，用來控制文本時鐘的狀態。

屬性

除支持[通用屬性]外，還支持以下屬性：

名稱	參數類型	描述
format	string	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時，該參數不生效）日期間隔符："年月日"、“/”、"-"、"."（可以自定義間隔符樣式，間隔符不可以為字母，漢字則作為間隔符處理）允許自行拼接組合顯示格式，即：年、月、日、星期、時、分、秒、毫秒可拆分為子元素，可自行排布組合。當設置無效字母時（非上述字母被認為是無效字母，多個有效字母會識別其中的有效組合進行匹配，例：yyyyy會匹配其中的yyyy為有效組合，多余的y認為是無效字母），該字母會被忽略。如果format全是無效字母時，顯示為格式yyyy/MM/dd aa hh:mm:ss.SS 若format為空或者undefined，則使用默認值。默認值：aa hh:mm:ss

以下是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

事件

除支持[通用事件]外，還支持以下事件：

名稱	功能描述
onDateChange(event: (value: number) => void)	提供時間變化回調，該事件回調間隔為秒。 - value: Unix Time Stamp，即自1970年1月1日（UTC）起經過的秒數。

TextClockController

TextClock容器組件的控制器，可以將該控制器綁定到TextClock組件，通過它控制文本時鐘的啟動與停止。一個TextClock組件僅支持綁定一個控制器。

導入對象

controller: TextClockController = new TextClockController();

start

start()

啟動文本時鐘。

stop

stop()

停止文本時鐘。HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿

鴻蒙文檔.png

示例

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