luojianingfix: add beta notes in markdown

TextTimer

Note:

Currently in the beta phase.

A component that displays timing information through text and controls its timer state.

Time changes will stop when the component is invisible. The component's visibility state is based on onVisibleAreaChange handling, where a visibility threshold ratio greater than 0 is considered visible.

Import Module

import kit.ArkUI.*

Child Components

None

Create Component

init(?Bool, ?Int64, ?TextTimerController)

public init(isCountDown!: ?Bool = None, count!: ?Int64 = None,
    controller!: ?TextTimerController = None)

Function: Creates a TextTimer object with countdown settings, timing duration, and controller.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
isCountDown	?Bool	No	None	Named parameter. Whether to count down. Initial value: false.
count	?Int64	No	None	Named parameter. Timer duration (effective when isCountDown is true), in milliseconds. Initial value: 60000.
controller	?TextTimerController	No	None	Named parameter. TextTimer controller.

Common Attributes/Common Events

Common Attributes: All supported.

Common Events: All supported.

Component Attributes

func fontColor(?ResourceColor)

public func fontColor(value: ?ResourceColor): This

Function: Sets the font color.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
value	?ResourceColor	Yes	-	Font color.

func fontFamily(?ResourceStr)

public func fontFamily(value: ?ResourceStr): This

Function: Sets the font list.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
value	?ResourceStr	Yes	-	Font list. Default font: 'HarmonyOS Sans'. Initial value: "HarmonyOS Sans".

func fontSize(?Length)

public func fontSize(value: ?Length): This

Function: Sets the font size.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
value	?Length	Yes	-	Font size. Initial value: 16.0.fp.

func fontStyle(?FontStyle)

public func fontStyle(value: ?FontStyle): This

Function: Sets the font style.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
value	?FontStyle	Yes	-	Font style. Initial value: FontStyle.Normal.

func fontWeight(?FontWeight)

public func fontWeight(value: ?FontWeight): This

Function: Sets the font weight.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
value	?FontWeight	Yes	-	Font weight. Initial value: FontWeight.Normal

func format(?String)

public func format(value: ?String): This

Function: Sets the custom format.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
value	?String	Yes	-	Custom format. Default value: 'HH:mm:ss.SS'. Initial value: "HH:mm:ss.SS".

func textShadow(?Array<ShadowOptions>)

public func textShadow(value: ?Array<ShadowOptions>): This

Function: Sets the text shadow.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
value	?Array<ShadowOptions>	Yes	-	Array of shadow options.

func textShadow(?ShadowOptions)

public func textShadow(value: ?ShadowOptions): This

Function: Sets the text shadow.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
value	?ShadowOptions	Yes	-	Shadow option.

Component Events

func onTimer(?(Int64, Int64) -> Unit)

public func onTimer(event: ?(Int64, Int64) -> Unit): This

Function: Triggered when the time text changes.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Parameters:

Parameter Name	Type	Required	Default Value	Description
event	?(Int64, Int64) -> Unit	Yes	-	Callback function when the time text changes. Initial value: { _, _ => }.

Basic Type Definitions

class TextTimerController

public class TextTimerController {
    public init()
}

Function: TextTimerController is the controller for the TextTimer component. An object of this type can be defined and bound to the TextTimer component to control it.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

init()

public init()

Function: Constructor for TextTimerController.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

func pause()

public func pause(): Unit

Function: Provides the pause event for the timer.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

func reset()

public func reset(): Unit

Function: Provides the reset event for the timer.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

func start()

public func start(): Unit

Function: Provides the start event for the timer.

System Capability: SystemCapability.ArkUI.ArkUI.Full

Since: 22

Example Code

Example 1 (Text Timer with Manual Start/Stop)

This example demonstrates the basic usage of the TextTimer component, setting the timer's text display format via the format attribute.

Users can start, pause, and reset the timer by clicking the "start", "pause", and "reset" buttons.

package ohos_app_cangjie_entry
import kit.ArkUI.*
import ohos.hilog.*
import ohos.arkui.state_macro_manage.*

@Entry
@Component
class EntryView {
    var textTimerController: TextTimerController = TextTimerController()
    @State var format: String = 'mm:ss.SS'
    func build() {
        Column {
            TextTimer(isCountDown: true, count: 30000, controller: this.textTimerController)
                .format(this.format)
                .fontColor(Color.Black)
                .fontSize(50)
                .onTimer({utc, elapsedTime =>
                    Hilog.info(0, "AppLogCj", "time has been changed")
                })
            Row() {
                Button("start").onClick({ evt =>
                  this.textTimerController.start()
                })
                Button("pause").onClick({ evt =>
                  this.textTimerController.pause()
                })
                Button("reset").onClick({ evt =>
                    this.textTimerController.reset()
                })
            }
        }
    }
}

texttimer

Example 2 (Setting Text Shadow Style)

This example sets the text shadow style for the timer via the textShadow attribute.

package ohos_app_cangjie_entry

import kit.ArkUI.*
import ohos.arkui.state_macro_manage.*

@Entry
@Component
class EntryView {
    @State var textShadows: Array<ShadowOptions> = [
        ShadowOptions(
            radius: 10.0,
            color: Color.Red,
            offsetX: 10.0,
            offsetY: 0.0
        ),
        ShadowOptions(
            radius: 10.0,
            color: Color.Black,
            offsetX: 20.0,
            offsetY: 0.0
        ),
        ShadowOptions(
            radius: 10.0,
            color: Color.Gray,
            offsetX: 30.0,
            offsetY: 0.0
        ),
        ShadowOptions(
        radius: 10.0,
        color: Color.Green,
        offsetX: 40.0,
        offsetY: 0.0
        ),
        ShadowOptions(
        radius: 10.0,
        color: Color.Blue,
        offsetX: 100.0,
        offsetY: 0.0
        )]
    func build() {
        Column(space: 8) {
            TextTimer().fontSize(50).textShadow(this.textShadows)
        }
    }
}

texttimer

Example 3 (Starting Timer Immediately After Creation)

This example demonstrates how the TextTimer starts timing immediately after creation.

package ohos_app_cangjie_entry

import kit.ArkUI.*
import ohos.hilog.*
import ohos.arkui.state_macro_manage.*

@Entry
@Component
class EntryView {
    var textTimerController: TextTimerController = TextTimerController()
    @State var format: String = 'mm:ss.SS'

    func build() {
        Column(space: 8) {```markdown
            Scroll().height(20.percent)
            Button("openTextTimer").onClick({
                evt =>

            })
            TextTimer( isCountDown: true, count: 30000, controller: this.textTimerController )
                .format(this.format)
                .fontColor(Color.Black)
                .fontSize(50)
                .onTimer({
                    utc: Int64, elapsedTime: Int64 =>
                        Hilog.info(0, "AppLogCj", 'textTimer notCountDown utc is：${utc.toString()}, elapsedTime: ${elapsedTime.toString()}')
                })
                .onAppear({ =>
                    this.textTimerController.start()
                })
        }
    }
}

texttimer