TextTimer
通过文本显示计时信息并控制其计时器状态的组件。
说明:
该组件从API Version 8开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
子组件
无
接口
TextTimer(options?: TextTimerOptions)
卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
参数:
参数名 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
options | TextTimerOptions | 否 | 通过文本显示计时信息并控制其计时器状态的组件参数。 |
TextTimerOptions对象说明
卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
参数名 | 参数类型 | 必填 | 参数描述 |
---|---|---|---|
isCountDown | boolean | 否 | 是否倒计时。 默认值:false |
count | number | 否 | 倒计时时间(isCountDown为true时生效),单位为毫秒。最长不超过86400000毫秒(24小时)。 0<count<86400000时,count值为倒计时初始值。否则,使用默认值为倒计时初始值。 默认值:60000 |
controller | TextTimerController | 否 | TextTimer控制器。 |
属性
除支持通用属性和文本通用属性的fontColor、fontSize、fontStyle、fontWeight、fontFamily外,还支持以下属性:
format
format(value: string)
设置自定义格式,需至少包含一个HH、mm、ss、SS中的关键字。如使用yy、MM、dd等日期格式,则使用默认值。
卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | string | 是 | 自定义格式。 默认值:‘HH:mm:ss.SS’ |
textShadow11+
textShadow(value: ShadowOptions | Array<ShadowOptions>)
设置文字阴影效果。该接口支持以数组形式入参,实现多重文字阴影。不支持fill字段, 不支持智能取色模式。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
value | ShadowOptions | Array<ShadowOptions> | 是 | 文字阴影效果。 |
contentModifier12+
contentModifier(modifier: ContentModifier<TextTimerConfiguration>)
定制TextTimer内容区的方法。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
modifier | ContentModifier<TextTimerConfiguration> | 是 | 在TextTimer组件上,定制内容区的方法。 modifier: 内容修改器,开发者需要自定义class实现ContentModifier接口。 |
事件
onTimer
onTimer(event: (utc: number, elapsedTime: number) => void)
时间文本发生变化时触发。锁屏状态和应用后台状态下不会触发该事件。
卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
utc | number | 是 | Linux时间戳,即自1970年1月1日起经过的时间,单位为设置格式的最小单位。 |
elapsedTime | number | 是 | 计时器经过的时间,单位为设置格式的最小单位。 |
TextTimerController
TextTimer组件的控制器,用于控制文本计时器。一个TextTimer组件仅支持绑定一个控制器。
卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
导入对象
textTimerController: TextTimerController = new TextTimerController()
start
start()
计时开始。
卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
pause
pause()
计时暂停。
卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
reset
reset()
重置计时器。
卡片能力: 从API version 10开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
TextTimerConfiguration12+对象说明
开发者需要自定义class实现ContentModifier接口。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数名 | 类型 | 默认值 | 说明 |
---|---|---|---|
count | number | 60000 | 倒计时时间(isCountDown为true时生效),单位为毫秒。最长不超过86400000毫秒(24小时)。 0<count<86400000时,count值为倒计时初始值。否则,使用默认值为倒计时初始值。 |
isCountDown | boolean | false | 是否倒计时。 |
started | boolean | - | 是否已经开始了倒计时。 |
elapsedTime | number | - | 计时器经过的时间,单位为设置格式的最小单位。 |
示例
示例1
// xxx.ets
@Entry
@Component
struct TextTimerExample {
textTimerController: TextTimerController = new TextTimerController()
@State format: string = 'mm:ss.SS'
build() {
Column() {
TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController })
.format(this.format)
.fontColor(Color.Black)
.fontSize(50)
.onTimer((utc: number, elapsedTime: number) => {
console.info('textTimer notCountDown utc is:' + utc + ', elapsedTime: ' + elapsedTime)
})
Row() {
Button("start").onClick(() => {
this.textTimerController.start()
})
Button("pause").onClick(() => {
this.textTimerController.pause()
})
Button("reset").onClick(() => {
this.textTimerController.reset()
})
}
}
}
}
示例2
// xxx.ets
@Entry
@Component
struct TextTimerExample {
@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 }) {
TextTimer().fontSize(50).textShadow(this.textShadows)
}
}
}
示例3
该示例实现了两个简易秒表,使用浅灰色背景。计时器开始后,会实时显示时间变化。倒计时器开始后,背景会变成黑色,正计时器开始后,背景会变成灰色。
// xxx.ets
class MyTextTimerModifier implements ContentModifier<TextTimerConfiguration> {
constructor() {
}
applyContent() : WrappedBuilder<[TextTimerConfiguration]>
{
return wrapBuilder(buildTextTimer)
}
}
@Builder function buildTextTimer(config: TextTimerConfiguration) {
Column() {
Stack({ alignContent: Alignment.Center }) {
Circle({ width: 150, height: 150 }).fill(config.started ? (config.isCountDown ? 0xFF232323 : 0xFF717171) : 0xFF929292)
Column(){
Text(config.isCountDown ? "倒计时" : "正计时").fontColor(Color.White)
Text(
(config.isCountDown ? "剩余" : "已经过去了") + (config.isCountDown?
(Math.max((config.count - config.elapsedTime) / 1000,0)).toFixed(1) + "/" + (config.count / 1000).toFixed(0)
:((config.elapsedTime / 1000).toFixed(0))
) + "秒"
).fontColor(Color.White)
}
}
}
}
@Entry
@Component
struct Index {
@State count: number = 10000
@State myTimerModifier: MyTextTimerModifier = new MyTextTimerModifier()
countDownTextTimerController: TextTimerController = new TextTimerController()
countUpTextTimerController: TextTimerController = new TextTimerController()
build() {
Row() {
Column() {
TextTimer({isCountDown: true, count: this.count, controller: this.countDownTextTimerController})
.contentModifier(this.myTimerModifier)
.onTimer((utc: number, elapsedTime: number) => {
console.info('textTimer onTimer utc is:' + utc + ', elapsedTime: ' + elapsedTime)
})
.margin(10)
TextTimer({isCountDown: false, controller: this.countUpTextTimerController})
.contentModifier(this.myTimerModifier)
.onTimer((utc: number, elapsedTime: number) => {
console.info('textTimer onTimer utc is:' + utc + ', elapsedTime: ' + elapsedTime)
})
Row() {
Button("start").onClick(()=>{
this.countDownTextTimerController.start()
this.countUpTextTimerController.start()
}).margin(10)
Button("pause").onClick(()=>{
this.countDownTextTimerController.pause()
this.countUpTextTimerController.pause()
}).margin(10)
Button("reset").onClick(()=>{
this.countDownTextTimerController.reset()
this.countUpTextTimerController.reset()
}).margin(10)
}.margin(20)
}.width('100%')
}.height('100%')
}
}