输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
管理中心

HarmonyOS 5.0.1(13)

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
API参考
高级筛选
元服务API集不筛选
您当前浏览的HarmonyOS 5.0.1(API 13)文档归档不再维护，推荐您使用最新版本。详细请参考文档维护策略变更。
API参考应用框架ArkUI（方舟UI框架）ArkTS组件信息展示TextTimer

TextTimer

更新时间: 2025-03-14 09:23
本文导读
展开章节

通过文本显示计时信息并控制其计时器状态的组件。

在组件不可见时时间变动将停止，组件的可见状态基于onVisibleAreaChange处理，可见阈值ratios大于0即视为可见状态。

说明

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

子组件

无

接口

TextTimer(options?: TextTimerOptions)

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

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

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

参数：

展开
参数名 类型 必填 说明
options TextTimerOptions 否 通过文本显示计时信息并控制其计时器状态的组件参数。

TextTimerOptions对象说明

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

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

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

展开
名称 类型 必填 说明
isCountDown boolean 否

是否倒计时。值为true时，计时器开启倒计时，例如从30秒 ~ 0秒。值为false时，计时器开始计时，例如从0秒 ~ 30秒。

默认值：false
count number 否

计时器时间（isCountDown为true时生效），单位为毫秒。最长不超过86400000毫秒（24小时）。 0<count<86400000时，count值为计时器初始值。否则，使用默认值为计时器初始值。

默认值：60000
controller TextTimerController 否 TextTimer控制器。

属性

除支持通用属性外，还支持以下属性：

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'

fontColor

fontColor(value: ResourceColor)

设置字体颜色。

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

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

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

参数：

展开
参数名 类型 必填 说明
value ResourceColor 是 字体颜色。

fontSize

fontSize(value: Length)

设置字体大小。

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

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

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

参数：

展开
参数名 类型 必填 说明
value Length 是 字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。不支持设置百分比字符串。

fontStyle

fontStyle(value: FontStyle)

设置字体样式。

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

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

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

参数：

展开
参数名 类型 必填 说明
value FontStyle 是

字体样式。

默认值：FontStyle.Normal

fontWeight

fontWeight(value: number | FontWeight | string)

设置文本的字体粗细，设置过大可能会在不同字体下有截断。

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

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

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

参数：

展开
参数名 类型 必填 说明
value number | FontWeight | string 是

文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、"bolder"、"lighter"、"regular"、"medium"，分别对应FontWeight中相应的枚举值。

默认值：FontWeight.Normal

fontFamily

fontFamily(value: ResourceStr)

设置字体列表。

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

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

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

参数：

展开
参数名 类型 必填 说明
value ResourceStr 是

字体列表。默认字体'HarmonyOS Sans'。

应用当前支持'HarmonyOS Sans'字体和注册自定义字体。

卡片当前仅支持'HarmonyOS Sans'字体。

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内容区的方法。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

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

参数：

展开
参数名 类型 必填 说明
modifier ContentModifier<TextTimerConfiguration> 是

在TextTimer组件上，定制内容区的方法。

modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

事件

onTimer

onTimer(event: (utc: number, elapsedTime: number) => void)

时间文本发生变化时触发。锁屏状态和应用后台状态下不会触发该事件。

设置高精度的format（SSS、SS）时，回调间隔可能会出现波动。

卡片能力： 从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开始，该接口支持在元服务中使用。

导入对象

收起
自动换行
深色代码主题
复制
  1. textTimerController: TextTimerController = new TextTimerController()

constructor

constructor()

TextTimerController的构造函数。

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

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

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

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

元服务API： 从API version 12开始，该接口支持在元服务中使用。

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

展开
名称 类型 必填 说明
count number 是

计时器时间（isCountDown为true时生效），单位为毫秒。最长不超过86400000毫秒（24小时）。 0<count<86400000时，count值为倒计时初始值。否则，使用默认值为倒计时初始值。

默认值：60000。
isCountDown boolean 是

是否倒计时。值为true时，计时器开启倒计时，例如从30秒 ~ 0秒。值为false时，计时器开始计时，例如从0秒 ~ 30秒。

默认值：false
started boolean 是 是否已经开始了计时。
elapsedTime number 是 计时器经过的时间，单位为设置格式的最小单位。

示例

示例1（支持手动启停的文本计时器）

该示例展示了TextTimer组件的基本使用方法，通过format属性设置计时器的文本显示格式。

用户可以通过点击"start"、"pause"、"reset"按钮，开启、暂停、重置计时器。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextTimerExample {
  5.   textTimerController: TextTimerController = new TextTimerController()
  6.   @State format: string = 'mm:ss.SS'
  7. 

  8.   build() {
  9.     Column() {
  10.       TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController })
  11.         .format(this.format)
  12.         .fontColor(Color.Black)
  13.         .fontSize(50)
  14.         .onTimer((utc: number, elapsedTime: number) => {
  15.           console.info('textTimer notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime)
  16.         })
  17.       Row() {
  18.         Button("start").onClick(() => {
  19.           this.textTimerController.start()
  20.         })
  21.         Button("pause").onClick(() => {
  22.           this.textTimerController.pause()
  23.         })
  24.         Button("reset").onClick(() => {
  25.           this.textTimerController.reset()
  26.         })
  27.       }
  28.     }
  29.   }
  30. }

示例2（设定文本阴影样式）

该示例通过textShadow属性设置计时器的文本阴影样式。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextTimerExample {
  5.   @State textShadows: ShadowOptions | Array<ShadowOptions> = [{
  6.     radius: 10,
  7.     color: Color.Red,
  8.     offsetX: 10,
  9.     offsetY: 0
  10.   }, {
  11.     radius: 10,
  12.     color: Color.Black,
  13.     offsetX: 20,
  14.     offsetY: 0
  15.   }, {
  16.     radius: 10,
  17.     color: Color.Brown,
  18.     offsetX: 30,
  19.     offsetY: 0
  20.   }, {
  21.     radius: 10,
  22.     color: Color.Green,
  23.     offsetX: 40,
  24.     offsetY: 0
  25.   }, {
  26.     radius: 10,
  27.     color: Color.Yellow,
  28.     offsetX: 100,
  29.     offsetY: 0
  30.   }]
  31. 

  32.   build() {
  33.     Column({ space: 8 }) {
  34.       TextTimer().fontSize(50).textShadow(this.textShadows)
  35.     }
  36.   }
  37. }

示例3（设定自定义内容区）

该示例实现了两个简易秒表，使用浅灰色背景。计时器开始后，会实时显示时间变化。倒计时器开始后，背景会变成黑色，正计时器开始后，背景会变成灰色。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. class MyTextTimerModifier implements ContentModifier<TextTimerConfiguration> {
  3.   constructor() {
  4.   }
  5. 

  6.   applyContent(): WrappedBuilder<[TextTimerConfiguration]> {
  7.     return wrapBuilder(buildTextTimer)
  8.   }
  9. }
  10. 

  11. @Builder
  12. function buildTextTimer(config: TextTimerConfiguration) {
  13.   Column() {
  14.     Stack({ alignContent: Alignment.Center }) {
  15.       Circle({ width: 150, height: 150 })
  16.         .fill(config.started ? (config.isCountDown ? 0xFF232323 : 0xFF717171) : 0xFF929292)
  17.       Column() {
  18.         Text(config.isCountDown ? "倒计时" : "正计时").fontColor(Color.White)
  19.         Text(
  20.           (config.isCountDown ? "剩余" : "已经过去了") + (config.isCountDown ?
  21.             (Math.max(config.count / 1000 - config.elapsedTime / 100, 0)).toFixed(1) + "/" +
  22.             (config.count / 1000).toFixed(0)
  23.             : ((config.elapsedTime / 100).toFixed(0))
  24.           ) + "秒"
  25.         ).fontColor(Color.White)
  26.       }
  27.     }
  28.   }
  29. }
  30. 

  31. @Entry
  32. @Component
  33. struct Index {
  34.   @State count: number = 10000
  35.   @State myTimerModifier: MyTextTimerModifier = new MyTextTimerModifier()
  36.   countDownTextTimerController: TextTimerController = new TextTimerController()
  37.   countUpTextTimerController: TextTimerController = new TextTimerController()
  38. 

  39.   build() {
  40.     Row() {
  41.       Column() {
  42.         TextTimer({ isCountDown: true, count: this.count, controller: this.countDownTextTimerController })
  43.           .contentModifier(this.myTimerModifier)
  44.           .onTimer((utc: number, elapsedTime: number) => {
  45.             console.info('textTimer onTimer utc is：' + utc + ', elapsedTime: ' + elapsedTime)
  46.           })
  47.           .margin(10)
  48.         TextTimer({ isCountDown: false, controller: this.countUpTextTimerController })
  49.           .contentModifier(this.myTimerModifier)
  50.           .onTimer((utc: number, elapsedTime: number) => {
  51.             console.info('textTimer onTimer utc is：' + utc + ', elapsedTime: ' + elapsedTime)
  52.           })
  53.         Row() {
  54.           Button("start").onClick(() => {
  55.             this.countDownTextTimerController.start()
  56.             this.countUpTextTimerController.start()
  57.           }).margin(10)
  58.           Button("pause").onClick(() => {
  59.             this.countDownTextTimerController.pause()
  60.             this.countUpTextTimerController.pause()
  61.           }).margin(10)
  62.           Button("reset").onClick(() => {
  63.             this.countDownTextTimerController.reset()
  64.             this.countUpTextTimerController.reset()
  65.           }).margin(10)
  66.         }.margin(20)
  67.       }.width('100%')
  68.     }.height('100%')
  69.   }
  70. }

示例4（创建之后立即执行计时）

该示例展示了TextTimer计时器如何在创建完成之后立即开始计时。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct TextTimerStart {
  5.   textTimerController: TextTimerController = new TextTimerController()
  6.   @State format: string = 'mm:ss.SS'
  7. 

  8.   build() {
  9.     Column() {
  10.       Scroll()
  11.         .height('20%')
  12.       TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController })
  13.         .format(this.format)
  14.         .fontColor(Color.Black)
  15.         .fontSize(50)
  16.         .onTimer((utc: number, elapsedTime: number) => {
  17.           console.info('textTimer notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime)
  18.         })
  19.         .onAppear(() => {
  20.           this.textTimerController.start()
  21.         })
  22.     }
  23.   }
  24. }

TextClock
TreeView
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 API参考 中进行搜索
请输入您想要搜索的关键词