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 | 否 | 是否倒计时。<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| 是 | 是否倒计时。<br> 默认值：false。 | 286| started | boolean | 是 | 是否已经开始了倒计时。 | 287| elapsedTime | number | 是 | 计时器经过的时间，单位为设置格式的最小单位。 | 288 289## 示例 290### 示例1 291```ts 292// xxx.ets 293@Entry 294@Component 295struct TextTimerExample { 296 textTimerController: TextTimerController = new TextTimerController() 297 @State format: string = 'mm:ss.SS' 298 299 build() { 300 Column() { 301 TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController }) 302 .format(this.format) 303 .fontColor(Color.Black) 304 .fontSize(50) 305 .onTimer((utc: number, elapsedTime: number) => { 306 console.info('textTimer notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime) 307 }) 308 Row() { 309 Button("start").onClick(() => { 310 this.textTimerController.start() 311 }) 312 Button("pause").onClick(() => { 313 this.textTimerController.pause() 314 }) 315 Button("reset").onClick(() => { 316 this.textTimerController.reset() 317 }) 318 } 319 } 320 } 321} 322``` 323 324 325 326 327### 示例2 328``` ts 329// xxx.ets 330@Entry 331@Component 332struct TextTimerExample { 333 @State textShadows : ShadowOptions | Array<ShadowOptions> = [{ radius: 10, color: Color.Red, offsetX: 10, offsetY: 0 },{ radius: 10, color: Color.Black, offsetX: 20, offsetY: 0 }, 334 { radius: 10, color: Color.Brown, offsetX: 30, offsetY: 0 },{ radius: 10, color: Color.Green, offsetX: 40, offsetY: 0 }, 335 { radius: 10, color: Color.Yellow, offsetX: 100, offsetY: 0 }] 336 build() { 337 Column({ space: 8 }) { 338 TextTimer().fontSize(50).textShadow(this.textShadows) 339 } 340 } 341} 342``` 343 344 345### 示例3 346该示例实现了两个简易秒表，使用浅灰色背景。计时器开始后，会实时显示时间变化。倒计时器开始后，背景会变成黑色，正计时器开始后，背景会变成灰色。 347``` ts 348// xxx.ets 349class MyTextTimerModifier implements ContentModifier<TextTimerConfiguration> { 350 constructor() { 351 } 352 applyContent() : WrappedBuilder<[TextTimerConfiguration]> 353 { 354 return wrapBuilder(buildTextTimer) 355 } 356} 357 358@Builder function buildTextTimer(config: TextTimerConfiguration) { 359 Column() { 360 Stack({ alignContent: Alignment.Center }) { 361 Circle({ width: 150, height: 150 }).fill(config.started ? (config.isCountDown ? 0xFF232323 : 0xFF717171) : 0xFF929292) 362 Column(){ 363 Text(config.isCountDown ? "倒计时" : "正计时").fontColor(Color.White) 364 Text( 365 (config.isCountDown ? "剩余" : "已经过去了") + (config.isCountDown? 366 (Math.max(config.count / 1000 - config.elapsedTime / 100,0)).toFixed(1) + "/" + (config.count / 1000).toFixed(0) 367 :((config.elapsedTime / 100).toFixed(0)) 368 ) + "秒" 369 ).fontColor(Color.White) 370 } 371 } 372 } 373} 374 375@Entry 376@Component 377struct Index { 378 @State count: number = 10000 379 @State myTimerModifier: MyTextTimerModifier = new MyTextTimerModifier() 380 countDownTextTimerController: TextTimerController = new TextTimerController() 381 countUpTextTimerController: TextTimerController = new TextTimerController() 382 383 build() { 384 Row() { 385 Column() { 386 TextTimer({isCountDown: true, count: this.count, controller: this.countDownTextTimerController}) 387 .contentModifier(this.myTimerModifier) 388 .onTimer((utc: number, elapsedTime: number) => { 389 console.info('textTimer onTimer utc is：' + utc + ', elapsedTime: ' + elapsedTime) 390 }) 391 .margin(10) 392 TextTimer({isCountDown: false, controller: this.countUpTextTimerController}) 393 .contentModifier(this.myTimerModifier) 394 .onTimer((utc: number, elapsedTime: number) => { 395 console.info('textTimer onTimer utc is：' + utc + ', elapsedTime: ' + elapsedTime) 396 }) 397 Row() { 398 Button("start").onClick(()=>{ 399 this.countDownTextTimerController.start() 400 this.countUpTextTimerController.start() 401 }).margin(10) 402 Button("pause").onClick(()=>{ 403 this.countDownTextTimerController.pause() 404 this.countUpTextTimerController.pause() 405 }).margin(10) 406 Button("reset").onClick(()=>{ 407 this.countDownTextTimerController.reset() 408 this.countUpTextTimerController.reset() 409 }).margin(10) 410 }.margin(20) 411 }.width('100%') 412 }.height('100%') 413 } 414} 415``` 416 417 418### 示例4 419TextTimer计时器创建之后立即执行。 420``` ts 421@Entry 422@Component 423struct textTimerStart { 424 textTimerController: TextTimerController = new TextTimerController() 425 @State format: string = 'mm:ss.SS' 426 427 build() { 428 Column() { 429 Scroll() 430 .height('20%') 431 TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController }) 432 .format(this.format) 433 .fontColor(Color.Black) 434 .fontSize(50) 435 .onTimer((utc: number, elapsedTime: number) => { 436 console.info('textTimer notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime) 437 }) 438 .onAppear(()=>{ 439 this.textTimerController.start() 440 }) 441 } 442 } 443} 444``` 445
