目录

ArkTS卡片被动刷新

本文主要提供被动刷新的开发指导,刷新流程请参考被动刷新概述。

卡片定时刷新

当前卡片框架提供了如下两种按时间刷新卡片的方式:

在触发定时、下次刷新后,系统会调用FormExtensionAbility的onUpdateForm生命周期回调,在回调中,可以使用updateForm接口刷新卡片内容。onUpdateForm生命周期回调的使用请参见卡片生命周期管理。

约束限制:

  1. 定时刷新有配额限制,每张卡片每天最多通过定时方式触发刷新50次,定时刷新次数可以通过修改卡片配置项updateDuration字段、或调用setFormNextRefreshTime接口两种方式进行设置,当达到50次配额后,无法通过定时方式再次触发刷新,刷新次数会在每天的0点重置。
  2. 当前定时刷新使用同一个计时器进行计时,因此卡片定时刷新的第一次刷新会有最多30分钟的偏差。比如第一张卡片A(每隔半小时刷新一次)在3点20分添加成功,定时器启动并每隔半小时触发一次事件,第二张卡片B(每隔半小时刷新一次)在3点40分添加成功,在3点50分定时器事件触发时,卡片A触发定时刷新,卡片B会在下次事件(4点20分)中才会触发。
  3. 定时刷新在卡片可见情况下才会触发,在卡片不可见时仅会记录刷新动作和刷新数据,待可见时统一刷新布局。
  4. 在API版本26.0.0之前,使能卡片代理刷新时,定时刷新和下次刷新不生效。从API版本26.0.0开始,卡片代理刷新、定时刷新和下次刷新可以同时生效。

卡片定点刷新

当前卡片框架提供了如下两种定点刷新卡片的方式:

在触发定点刷新后,系统会调用FormExtensionAbility的onUpdateForm生命周期回调,在回调中,可以使用updateForm接口刷新卡片内容。onUpdateForm生命周期回调的使用请参见卡片生命周期管理。

  1. 当同时配置了定时刷新updateDuration和定点刷新scheduledUpdateTime时,定时刷新的优先级更高且定点刷新不会执行。如果想要配置定点刷新,则需要将updateDuration配置为0。
  2. multiScheduledUpdateTime的配置最多可设置24个时间。
  3. 同时配置了单定点和多定点刷新,多定点刷新配置生效,单定点刷新配置不生效。
  4. 考虑到向前兼容的问题,尽量保留scheduledUpdateTime字段,不要直接删除。

约束限制:

  1. 定点刷新在卡片可见情况下才会触发,在卡片不可见时仅会记录刷新动作和刷新数据,待可见时统一刷新布局。

卡片条件刷新

当前卡片框架提供了如下按条件刷新卡片的方式:

  1. 当从无网络到有网络连接时会触发刷新。而网络间切换(例如:WiFi间切换,WiFi到流量,流量到WiFi),或从有网络连接到无网络连接时不会触发刷新。

  2. 为减少卡片在频繁开关网络场景进程启动次数,无网判定需要网络连续断开十分钟后,才会认为无网,下次联网后触发网络刷新。

{
  "forms": [
    {
      "name": "UpdateDuration",
      "description": "$string:widget_updateduration_desc",
      "src": "./ets/updateduration/pages/UpdateDurationCard.ets",
      "uiSyntax": "arkts",
      "window": {
        "designWidth": 720,
        "autoDesignWidth": true
      },
      "isDefault": true,
      "updateEnabled": true,
      "scheduledUpdateTime": "10:30",
      "updateDuration": 2,
      "defaultDimension": "2*2",
      "supportDimensions": [
        "2*2"
      ],
      "conditionUpdate": [
        "network"
      ]
    }
  ]
}