HarmonyOS鸿蒙Next中万能卡片显示时间如何实现

HarmonyOS鸿蒙Next中万能卡片显示时间如何实现 比如时钟卡片，能显示精确到秒的时间，想集成在自己的卡片上，如何更新时间呢？

4 回复

开发者您好，系统时钟应用使用AnalogClock组件，该组件为系统组件，暂不对三方应用开放。

受卡片系统规格约束，三方应用不支持秒级刷新卡片。由于卡片被动刷新的次数有限，也无法直接在服务卡片上实现分钟级刷新的效果。如果引入TextClock组件后，可通过onDateChange回调函数间接实现服务卡片刷新。示例卡片采用动态时间显示（每分钟刷新并记录日志）和模拟时钟指针旋转（每次刷新旋转30度），同时实时展示刷新次数统计。示例代码如下：

@Entry
@Component
struct DiawidgetCard {
  @State num: number = 0;

  // 记录刷新次数
  build() {
    Column() {
      Text(`当前刷新次数为：${this.num}`);
      TextClock()
        .onDateChange((value: number) => {
          const unixTimestamp = value;
          const milliseconds = unixTimestamp * 1000; // 转换为毫秒
          const date = new Date(milliseconds); // 获取时间各部分
          const year = date.getFullYear(); // 年份
          const month = date.getMonth() + 1; // 月份(0-11→1-12)
          const day = date.getDate(); // 日期
          const hours = date.getHours(); // 小时
          const minutes = date.getMinutes(); // 分钟
          console.info('当前卡片时间更新为', `${year}-${month}-${day} ${hours}:${minutes}`);
          this.num++;
        })
        .visibility(Visibility.Visible); // 用于控制组件是否展示
      Stack() {
        Image($r('sys.media.ohos_ic_public_clock')) // 'sys.media.ohos_ic_public_clock'仅作示例，请替换为实际使用的资源
          .width(100).offset({ x: -1, y: 20 });
        Row()
          .rotate({
            x: 0,
            y: 0,
            z: 1,
            centerX: '0%',
            centerY: '100%',
            angle: this.num * 30
          })
          .width(2)
          .height(40)
          .backgroundColor(Color.Black);
      };
    }.width('100%').height('100%');
  }
}

如果以上方案不能解决您的问题，请问您是在什么样的业务场景中使用该能力，交互流程是怎样的，在哪一个环节遇到了问题？另外请您说明能力不满足可能带来的影响：什么时间用到？是否高频？有无三方库可以做到？若提供该能力，是否会造成大工作量返工？请您注意提供的内容不要包含您或第三方的非公开信息，如给您带来不便，敬请谅解。

更多关于HarmonyOS鸿蒙Next中万能卡片显示时间如何实现的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


使用TextClock组件

https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-textclock

在HarmonyOS Next中，万能卡片显示时间主要通过ArkTS声明式UI开发。使用@Entry和@Component装饰器定义卡片UI，通过@State装饰器管理时间数据状态。利用系统调度器定时更新，例如使用setInterval函数每秒刷新时间显示。卡片布局使用Flex、Text等组件构建，时间格式化可通过Intl.DateTimeFormat实现。最终打包为.hsp模块，在卡片的form_config.json中配置更新策略。

在HarmonyOS Next中，万能卡片显示实时时间（如精确到秒）主要通过以下核心机制实现：

  1. 使用FormExtensionAbility和FormBindingData：这是卡片数据更新的基础框架。你需要在卡片的FormExtensionAbility中，通过updateForm方法，使用FormBindingData对象来更新卡片上绑定的时间数据。

  2. 关键：定时触发更新
    要实现秒级更新，不能在卡片本身进行setInterval或setTimeout这类循环。正确做法是：

    • 在FormExtensionAbility的onCreate或onCastToNormalForm生命周期中，启动一个后台服务或使用系统调度。
    • 强烈建议使用**reminderAgent（提醒代理）** 或 workScheduler（后台任务调度） 来每分钟触发一次更新。对于秒级显示，卡片通常采用“前端倒计时”结合“分钟级后台同步”的策略： a. 后台每分钟准时更新一次卡片数据（提供精确的分钟和秒初值）。 b. 卡片UI层（hml/js）在收到新数据后，启动一个前端秒级计时器（setInterval）进行本地UI刷新，直到下一分钟的后台更新到达。

  3. 代码示例要点

    • 卡片Provider（FormExtensionAbility） 中调度周期性任务：
      // 使用reminderAgent设置每分钟触发一次的提醒
import reminderAgent from '@ohos.reminderAgent';
// ... 在适当生命周期设置提醒，触发`onUpdateForm`回调
    • onUpdateForm回调中更新数据：
      onUpdateForm(formId) {
    let date = new Date();
    let obj = {
        'hour': date.getHours(),
        'minute': date.getMinutes(),
        'second': date.getSeconds() // 提供当前秒数作为初始值
    };
    let formData = formBindingData.createFormBindingData(obj);
    formProvider.updateForm(formId, formData).then(...);
}
    • 卡片页面（hml/js） 收到数据后启动前端计时：
      // 在js中接收数据
onFormDataChange(obj) {
    this.hour = obj.hour;
    this.minute = obj.minute;
    this.second = obj.second;
    // 清除旧计时器，启动新的一分钟倒计时
    this.startSecondTick();
},
startSecondTick() {
    let interval = setInterval(() => {
        this.second++;
        if (this.second >= 60) {
            this.second = 0;
            this.minute++;
            // 等待下一分钟后台更新
        }
        // 更新UI显示
    }, 1000);
}

  4. 配置卡片更新频率
    在config.json中配置卡片的updateDuration为1（分钟），这是允许的最小值，它决定了后台触发onUpdateForm的最小间隔。

  5. 优化考虑

    • 为节省系统资源，如果卡片不可见（例如被遮挡或划走），应在FormExtensionAbility的onVisibilityChange回调中暂停或调整更新策略。
    • 确保前端计时器在卡片销毁时被正确清理，防止内存泄漏。

这种“后台分钟级同步 + 前端秒级倒计时”的模式，是HarmonyOS Next上实现时钟类卡片秒级显示的标准且高效的做法，它平衡了实时性、功耗和系统性能。

回到顶部