HarmonyOS：TextTimer计时器

ChinaDragon
120 阅读5分钟

一、概述

通过文本显示计时信息并控制其计时器状态的组件。
在组件不可见时时间变动将停止，组件的可见状态基于onVisibleAreaChange处理，可见阈值ratios大于0即视为可见状态。
说明 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

二、TextTimerOptions对象说明

卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
isCountDownboolean否是否倒计时。值为true时，计时器开启倒计时，例如从30秒 ~ 0秒。值为false时，计时器开始计时，例如从0秒 ~ 30秒。默认值：false
countnumber否计时器时间（isCountDown为true时生效），单位为毫秒。最长不超过86400000毫秒（24小时）。 0<count<86400000时，count值为计时器初始值。否则，使用默认值为计时器初始值。
默认值：60000
controllerTextTimerController否TextTimer控制器。

三、属性

除支持通用属性外，还支持以下属性：
format format(value: string)
设置自定义格式，需至少包含一个HH、mm、ss、SS中的关键字。如使用yy、MM、dd等日期格式，则使用默认值。
卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
valuestring是自定义格式。
默认值：'HH:mm:ss.SS'

四、事件

onTimer onTimer(event: (utc: number, elapsedTime: number) => void)
时间文本发生变化时触发。锁屏状态和应用后台状态下不会触发该事件。
设置高精度的format（SSS、SS）时，回调间隔可能会出现波动。
卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名类型必填说明
utcnumber是Linux时间戳，即自1970年1月1日起经过的时间，单位为设置格式的最小单位。
elapsedTimenumber是计时器经过的时间，单位为设置格式的最小单位。

五、TextTimerController

TextTimer组件的控制器，用于控制文本计时器。一个TextTimer组件仅支持绑定一个控制器，组件创建完成后相关指令才能被调用。
卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。

导入对象

textTimerController: TextTimerController = new TextTimerController();

constructor constructor() TextTimerController的构造函数。
start start() 计时开始。
pause pause() 计时暂停。
reset reset() 重置计时器。

六、TextTimerConfiguration对象说明

开发者需要自定义class实现ContentModifier接口。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full

名称类型必填说明
countnumber是计时器时间（isCountDown为true时生效），单位为毫秒。最长不超过86400000毫秒（24小时）。 0<count<86400000时，count值为倒计时初始值。否则，使用默认值为倒计时初始值。
默认值：60000。
isCountDownboolean是是否倒计时。值为true时，计时器开启倒计时，例如从30秒 ~ 0秒。值为false时，计时器开始计时，例如从0秒 ~ 30秒。
默认值：false
startedboolean是是否已经开始了计时。默认值：false， 表示未开始计时。
elapsedTimenumber是计时器经过的时间，单位为设置格式的最小单位。

七、示例

效果图
在这里插入图片描述

示例代码 TestTextTimer.ets


@Component
struct TextTimerExample1 {
  textTimerController1: TextTimerController = new TextTimerController()
  @State format: string = "mm:ss.SS"

  build() {
    Column({ space: 10 }) {
      Text('文本计时器')
        .fontSize(20)
        .fontWeight(FontWeight.Medium)
        .margin({ top: 20 })
      TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController1 })
        .format(this.format)
        .fontColor(Color.Black)
        .fontSize(20)
        .onTimer((utc: number, elapsedTime: number) => {
          console.info('文本计时器 notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime);
        })
      Row({ space: 10 }) {
        Button("start").onClick(() => {
          this.textTimerController1.start();
        })
        Button("pause").onClick(() => {
          this.textTimerController1.pause();
        })
        Button("reset").onClick(() => {
          this.textTimerController1.reset();
        })
      }
    }
  }
}

@Component
struct TextTimerExample2 {
  textTimerController2: TextTimerController = new TextTimerController()
  @State format: string = "mm:ss.SS"
  @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.Green,
    offsetX: 30,
    offsetY: 0
  }, {
    radius: 10,
    color: Color.Blue,
    offsetX: 40,
    offsetY: 0
  }, {
    radius: 10,
    color: Color.Pink,
    offsetX: 100,
    offsetY: 0
  }];

  build() {
    Column({ space: 8 }) {
      Text('设定文本阴影样式')
        .fontSize(20)
        .fontWeight(FontWeight.Medium)
        .margin({ top: 10 })
      TextTimer({ isCountDown: true, count: 30000, controller: this.textTimerController2 })
        .format(this.format)
        .fontColor(Color.Black)
        .fontSize(20)
        .textShadow(this.textShadows)
        .onTimer((utc: number, elapsedTime: number) => {
          console.info('设定文本阴影样式计时器 notCountDown utc is：' + utc + ', elapsedTime: ' + elapsedTime);
        })
      Row({ space: 10 }) {
        Button("start").onClick(() => {
          this.textTimerController2.start();
        })
        Button("pause").onClick(() => {
          this.textTimerController2.pause();
        })
        Button("reset").onClick(() => {
          this.textTimerController2.reset();
        })
      }
    }
  }
}

@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 / 1000 - config.elapsedTime / 100, 0)).toFixed(1) + "/" +
            (config.count / 1000).toFixed(0)
            : ((config.elapsedTime / 100).toFixed(0))
          ) + "秒"
        ).fontColor(Color.White)
      }
    }
  }
}

class MyTextTimerModifier implements ContentModifier<TextTimerConfiguration> {
  constructor() {
  }

  applyContent(): WrappedBuilder<[TextTimerConfiguration]> {
    return wrapBuilder(buildTextTimer);
  }
}

@Component
struct TextTimerExample3 {
  @State count: number = 10000;
  @State myTimerModifier: MyTextTimerModifier = new MyTextTimerModifier();
  countDownTextTimerController: TextTimerController = new TextTimerController();
  countUpTextTimerController: TextTimerController = new TextTimerController();

  build() {
    Row() {
      Column() {
        Text('设定自定义内容区')
          .fontSize(20)
          .fontWeight(FontWeight.Medium)
          .margin({ top: 10 })
        TextTimer({ isCountDown: true, count: this.count, controller: this.countDownTextTimerController })
          .contentModifier(this.myTimerModifier)
          .onTimer((utc: number, elapsedTime: number) => {
            console.info('设定自定义内容区 onTimer utc is：' + utc + ', elapsedTime: ' + elapsedTime);
          })
          .margin(10)
        TextTimer({ isCountDown: false, controller: this.countUpTextTimerController })
          .contentModifier(this.myTimerModifier)
          .onTimer((utc: number, elapsedTime: number) => {
            console.info('设定自定义内容区 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%')
    }
  }
}

@Entry
@Component
struct TestTextTimer {
  build() {
    Column({ space: 16 }) {
      TextTimerExample1()
      TextTimerExample2()
      TextTimerExample3()
    }
    .height('100%')
    .width('100%')
  }
}
avatar
文章
阅读
粉丝