TextClock

The <TextClock> component displays the current system time in text format for different time zones. The time is accurate to seconds.

NOTE

This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.

Child Components

Not supported

APIs

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

Parameters

Name	Type	Mandatory	Description
timeZoneOffset	number	No	Time zone offset. The value range is [-14, 12], indicating UTC+12 to UTC-12. A negative value indicates Eastern Standard Time, and a positive value indicates Western Standard Time. For example, -8 indicates UTC+8. For countries or regions crossing the International Date Line, use -13 (UTC+13) and -14 (UTC+14) to ensure consistent time within the entire country or region. If the set value is not within the valid range, the time zone offset of the current system will be used. Default value: time zone offset of the current system
controller	TextClockController	No	Controller to control the status of the <TextClock> component.

Attributes

In addition to the universal attributes, the following attributes are supported.

Name	Type	Description
format	string	Time format. The date separator is a slash (/), and the time separator is a colon (:). For example, yyyyMMdd and yyyy-MM-dd are displayed as yyyy/MM/dd, and hhmmss is displayed as hh:mm:ss. Only one digit is required for the time format. This means that "hhmmss" is equivalent to "hms". Supported time format strings: - YYYY/yyyy: four-digit year - YY/yy: last two digits of year - M: one-digit month (MM for two-digit month, for example, 01) - d: one-digit day (dd for two-digit day, for example, 01) - D: number of days that have elapsed in the year - H: 24-hour format - h: 12-hour format - m: minute - s: second - SSS: millisecond If the specified format does not match the supported formats, the default value is used. Default value: 'hms'

Events

In addition to the universal events, the following events are supported.

Name	Description
onDateChange(event: (value: number) => void)	Called when the time changes in seconds at minimum. - value: Unix time stamp, which is the number of milliseconds that have elapsed since the Unix epoch.

TextClockController

Implements the controller of the <TextClock> component. You can bind the controller to the component to control its start and stop. A <TextClock> component can be bound to only one controller.

Objects to Import

controller: TextClockController = new TextClockController();

start

start()

Starts the <TextClock> component.

stop

stop()

Stops the <TextClock> component.

Example

@Entry
@Component
struct Second {
  @State accumulateTime: number = 0;
  // Objects to import
  controller: TextClockController = new TextClockController();
  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Text('Current milliseconds is ' + this.accumulateTime)
        .fontSize(20)
      // Display the system time in 12-hour format for the UTC+8 time zone, accurate to seconds.
      TextClock({ timeZoneOffset: -8, controller: this.controller })
        .format('hms')
        .onDateChange((value: number) => {
          this.accumulateTime = value;
        })
        .margin(20)
        .fontSize(30)
      Button("start TextClock")
        .margin({ bottom: 10 })
        .onClick(() => {
          // Start the text clock.
          this.controller.start();
        })
      Button("stop TextClock")
        .onClick(() => {
          // Stop the text clock.
          this.controller.stop();
        })
    }
    .width('100%')
    .height('100%')
  }
}