1# TextTimer 2 3通过文本显示计时信息并控制其计时器状态的组件。 4 5在组件不可见时时间变动将停止，组件的可见状态基于[onVisibleAreaChange](./ts-universal-component-visible-area-change-event.md#onvisibleareachange)处理，可见阈值ratios大于0即视为可见状态。 6 7> **说明：** 8> 9> 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 10 11## 子组件 12 13无 14 15## 接口 16 17TextTimer(options?: TextTimerOptions) 18 19**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 20 21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| -------- | -------- | -------- | -------- | 29| options | [TextTimerOptions](#texttimeroptions对象说明)| 否 | 通过文本显示计时信息并控制其计时器状态的组件参数。 | 30 31## TextTimerOptions对象说明 32 33**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 34 35**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 36 37**系统能力：** SystemCapability.ArkUI.ArkUI.Full 38 39| 名称 | 类型 | 必填 | 说明 | 40| ----------- | -------- | -------- | -------- | 41| isCountDown | boolean | 否 | 是否倒计时。值为true时，计时器开启倒计时，值为false时，计时器开始计时。<br/>默认值：false | 42| count | number | 否 | 计时器时间（isCountDown为true时生效），单位为毫秒。最长不超过86400000毫秒（24小时）。 0<count<86400000时，count值为计时器初始值。否则，使用默认值为计时器初始值。<br/>默认值：60000 | 43| controller | [TextTimerController](#texttimercontroller) | 否 | TextTimer控制器。 | 44 45## 属性 46 47除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 48 49### format 50 51format(value: string) 52 53设置自定义格式，需至少包含一个HH、mm、ss、SS中的关键字。如使用yy、MM、dd等日期格式，则使用默认值。 54 55**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 56 57**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 58 59**系统能力：** SystemCapability.ArkUI.ArkUI.Full 60 61**参数：** 62 63| 参数名 | 类型 | 必填 | 说明 | 64| ------ | ------ | ---- | -------------------------------------- | 65| value | string | 是 | 自定义格式。<br/>默认值：'HH:mm:ss.SS' | 66 67 68### fontColor 69 70fontColor(value: ResourceColor) 71 72设置字体颜色。 73 74**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 75 76**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 77 78**系统能力：** SystemCapability.ArkUI.ArkUI.Full 79 80**参数：** 81 82| 参数名 | 类型 | 必填 | 说明 | 83| ------ | ------------------------------------------ | ---- | ---------- | 84| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 字体颜色。 | 85 86### fontSize 87 88fontSize(value: Length) 89 90设置字体大小。 91 92**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 93 94**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 95 96**系统能力：** SystemCapability.ArkUI.ArkUI.Full 97 98**参数：** 99 100| 参数名 | 类型 | 必填 | 说明 | 101| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 102| value | [Length](ts-types.md#length) | 是 | 字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。不支持设置百分比字符串。 | 103 104### fontStyle 105 106fontStyle(value: FontStyle) 107 108设置字体样式。 109 110**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 111 112**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 113 114**系统能力：** SystemCapability.ArkUI.ArkUI.Full 115 116**参数：** 117 118| 参数名 | 类型 | 必填 | 说明 | 119| ------ | ------------------------------------------- | ---- | --------------------------------------- | 120| value | [FontStyle](ts-appendix-enums.md#fontstyle) | 是 | 字体样式。<br/>默认值：FontStyle.Normal | 121 122### fontWeight 123 124fontWeight(value: number | FontWeight | string) 125 126设置文本的字体粗细，设置过大可能会在不同字体下有截断。 127 128**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 129 130**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 131 132**系统能力：** SystemCapability.ArkUI.ArkUI.Full 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| ------ | ---------- | ------ | ----------------- | 138| value | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | 是 | 文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、"bolder"、"lighter"、"regular"、"medium"，分别对应FontWeight中相应的枚举值。<br/>默认值：FontWeight.Normal | 139 140### fontFamily 141 142fontFamily(value: ResourceStr) 143 144设置字体列表。 145 146**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 147 148**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 149 150**系统能力：** SystemCapability.ArkUI.ArkUI.Full 151 152**参数：** 153 154| 参数名 | 类型 | 必填 | 说明 | 155| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | 156| value | [ResourceStr](ts-types.md#resourcestr) | 是 | 字体列表。默认字体'HarmonyOS Sans'。<br>应用当前支持'HarmonyOS Sans'字体和[注册自定义字体](../js-apis-font.md)。<br>卡片当前仅支持'HarmonyOS Sans'字体。 | 157 158### textShadow<sup>11+</sup> 159 160textShadow(value: ShadowOptions | Array<ShadowOptions>) 161 162设置文字阴影效果。该接口支持以数组形式入参，实现多重文字阴影。不支持fill字段, 不支持智能取色模式。 163 164**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 165 166**系统能力：** SystemCapability.ArkUI.ArkUI.Full 167 168**参数：** 169 170| 参数名 | 类型 | 必填 | 说明 | 171| ------ | ------------------------------------------------------------ | ---- | -------------- | 172| value | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明) \| Array<[ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions对象说明)> | 是 | 文字阴影效果。 | 173 174### contentModifier<sup>12+</sup> 175 176contentModifier(modifier: ContentModifier\<TextTimerConfiguration>) 177 178定制TextTimer内容区的方法。 179 180**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 181 182**系统能力：** SystemCapability.ArkUI.ArkUI.Full 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 188| modifier | [ContentModifier\<TextTimerConfiguration>](#texttimerconfiguration12对象说明) | 是 | 在TextTimer组件上，定制内容区的方法。<br/>modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。 | 189 190## 事件 191 192### onTimer 193 194onTimer(event: (utc: number, elapsedTime: number) => void) 195 196时间文本发生变化时触发。锁屏状态和应用后台状态下不会触发该事件。 197设置高精度的format（SSS、SS）时，回调间隔可能会出现波动。 198 199**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 200 201**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 202 203**系统能力：** SystemCapability.ArkUI.ArkUI.Full 204 205**参数：** 206 207| 参数名 | 类型 | 必填 | 说明 | 208| ----------- | ------ | ---- | ------------------------------------------------------------ | 209| utc | number | 是 | Linux时间戳，即自1970年1月1日起经过的时间，单位为设置格式的最小单位。 | 210| elapsedTime | number | 是 | 计时器经过的时间，单位为设置格式的最小单位。 | 211 212## TextTimerController 213 214TextTimer组件的控制器，用于控制文本计时器。一个TextTimer组件仅支持绑定一个控制器，组件创建完成后相关指令才能被调用。 215 216**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 217 218**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 219 220### 导入对象 221 222``` 223textTimerController: TextTimerController = new TextTimerController() 224``` 225 226### constructor 227 228constructor() 229 230TextTimerController的构造函数。 231 232**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 233 234**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 235 236**系统能力：** SystemCapability.ArkUI.ArkUI.Full 237 238### start 239 240start() 241 242计时开始。 243 244**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 245 246**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 247 248**系统能力：** SystemCapability.ArkUI.ArkUI.Full 249 250### pause 251 252pause() 253 254计时暂停。 255 256**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 257 258**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 259 260**系统能力：** SystemCapability.ArkUI.ArkUI.Full 261 262### reset 263 264reset() 265 266重置计时器。 267 268**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 269 270**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 271 272**系统能力：** SystemCapability.ArkUI.ArkUI.Full 273 274## TextTimerConfiguration<sup>12+</sup>对象说明 275 276开发者需要自定义class实现ContentModifier接口。 277 278**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 279 280**系统能力：** SystemCapability.ArkUI.ArkUI.Full 281 282| 名称 | 类型 | 必填 | 说明 | 283| ------ | ------ | ------ |-------------------------------- | 284| count | number | 是 | 计时器时间（isCountDown为true时生效），单位为毫秒。最长不超过86400000毫秒（24小时）。 0<count<86400000时，count值为倒计时初始值。否则，使用默认值为倒计时初始值。<br> 默认值：60000。 | 285| isCountDown | boolean| 是 | 是否倒计时。值为true时，计时器开启倒计时，值为false时，计时器开始计时。<br> 默认值：false | 286| started | boolean | 是 | 是否已经开始了计时。 | 287| elapsedTime | number | 是 | 计时器经过的时间，单位为设置格式的最小单位。 | 288 289## 示例 290### 示例1（支持手动启停的文本计时器） 291 292该示例展示了TextTimer组件的基本使用方法，通过format属性设置计时器的文本显示格式。 293 294用户可以通过点击"start"、"pause"、"reset"按钮，开启、暂停、重置计时器。 295 296```ts 297// xxx.ets 298@Entry 299@Component 300struct TextTimerExample { 301 textTimerController: TextTimerController = new TextTimerController() 302 @State format: string = 'mm:ss.SS' 303 304 build() { 305 Column() { 306 TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController }) 307 .format(this.format) 308 .fontColor(Color.Black) 309 .fontSize(50) 310 .onTimer((utc: number, elapsedTime: number) => { 311 console.info('textTimer notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime) 312 }) 313 Row() { 314 Button("start").onClick(() => { 315 this.textTimerController.start() 316 }) 317 Button("pause").onClick(() => { 318 this.textTimerController.pause() 319 }) 320 Button("reset").onClick(() => { 321 this.textTimerController.reset() 322 }) 323 } 324 } 325 } 326} 327``` 328 329 330 331 332### 示例2（设定文本阴影样式） 333 334该示例通过textShadow属性设置计时器的文本阴影样式。 335 336``` ts 337// xxx.ets 338@Entry 339@Component 340struct TextTimerExample { 341 @State textShadows: ShadowOptions | Array<ShadowOptions> = [{ 342 radius: 10, 343 color: Color.Red, 344 offsetX: 10, 345 offsetY: 0 346 }, { 347 radius: 10, 348 color: Color.Black, 349 offsetX: 20, 350 offsetY: 0 351 }, { 352 radius: 10, 353 color: Color.Brown, 354 offsetX: 30, 355 offsetY: 0 356 }, { 357 radius: 10, 358 color: Color.Green, 359 offsetX: 40, 360 offsetY: 0 361 }, { 362 radius: 10, 363 color: Color.Yellow, 364 offsetX: 100, 365 offsetY: 0 366 }] 367 368 build() { 369 Column({ space: 8 }) { 370 TextTimer().fontSize(50).textShadow(this.textShadows) 371 } 372 } 373} 374``` 375 376 377### 示例3（设定自定义内容区） 378 379该示例实现了两个简易秒表，使用浅灰色背景。计时器开始后，会实时显示时间变化。倒计时器开始后，背景会变成黑色，正计时器开始后，背景会变成灰色。 380 381``` ts 382// xxx.ets 383class MyTextTimerModifier implements ContentModifier<TextTimerConfiguration> { 384 constructor() { 385 } 386 387 applyContent(): WrappedBuilder<[TextTimerConfiguration]> { 388 return wrapBuilder(buildTextTimer) 389 } 390} 391 392@Builder 393function buildTextTimer(config: TextTimerConfiguration) { 394 Column() { 395 Stack({ alignContent: Alignment.Center }) { 396 Circle({ width: 150, height: 150 }) 397 .fill(config.started ? (config.isCountDown ? 0xFF232323 : 0xFF717171) : 0xFF929292) 398 Column() { 399 Text(config.isCountDown ? "倒计时" : "正计时").fontColor(Color.White) 400 Text( 401 (config.isCountDown ? "剩余" : "已经过去了") + (config.isCountDown ? 402 (Math.max(config.count / 1000 - config.elapsedTime / 100, 0)).toFixed(1) + "/" + 403 (config.count / 1000).toFixed(0) 404 : ((config.elapsedTime / 100).toFixed(0)) 405 ) + "秒" 406 ).fontColor(Color.White) 407 } 408 } 409 } 410} 411 412@Entry 413@Component 414struct Index { 415 @State count: number = 10000 416 @State myTimerModifier: MyTextTimerModifier = new MyTextTimerModifier() 417 countDownTextTimerController: TextTimerController = new TextTimerController() 418 countUpTextTimerController: TextTimerController = new TextTimerController() 419 420 build() { 421 Row() { 422 Column() { 423 TextTimer({ isCountDown: true, count: this.count, controller: this.countDownTextTimerController }) 424 .contentModifier(this.myTimerModifier) 425 .onTimer((utc: number, elapsedTime: number) => { 426 console.info('textTimer onTimer utc is：' + utc + ', elapsedTime: ' + elapsedTime) 427 }) 428 .margin(10) 429 TextTimer({ isCountDown: false, controller: this.countUpTextTimerController }) 430 .contentModifier(this.myTimerModifier) 431 .onTimer((utc: number, elapsedTime: number) => { 432 console.info('textTimer onTimer utc is：' + utc + ', elapsedTime: ' + elapsedTime) 433 }) 434 Row() { 435 Button("start").onClick(() => { 436 this.countDownTextTimerController.start() 437 this.countUpTextTimerController.start() 438 }).margin(10) 439 Button("pause").onClick(() => { 440 this.countDownTextTimerController.pause() 441 this.countUpTextTimerController.pause() 442 }).margin(10) 443 Button("reset").onClick(() => { 444 this.countDownTextTimerController.reset() 445 this.countUpTextTimerController.reset() 446 }).margin(10) 447 }.margin(20) 448 }.width('100%') 449 }.height('100%') 450 } 451} 452``` 453 454 455### 示例4（创建之后立即执行计时） 456 457该示例展示了TextTimer计时器如何在创建完成之后立即开始计时。 458 459``` ts 460// xxx.ets 461@Entry 462@Component 463struct TextTimerStart { 464 textTimerController: TextTimerController = new TextTimerController() 465 @State format: string = 'mm:ss.SS' 466 467 build() { 468 Column() { 469 Scroll() 470 .height('20%') 471 TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController }) 472 .format(this.format) 473 .fontColor(Color.Black) 474 .fontSize(50) 475 .onTimer((utc: number, elapsedTime: number) => { 476 console.info('textTimer notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime) 477 }) 478 .onAppear(() => { 479 this.textTimerController.start() 480 }) 481 } 482 } 483} 484``` 485
