HarmonyOS元服务卡片开发需完成四步闭环:新建Stage模型下的Service Widget模块、配置2×2尺寸及定点刷新、实现日期动态绑定与onUpdate定时更新、通过router.pushUrl跳转并校验路径匹配,缺一不可。

在HarmonyOS中开发元服务卡片功能,需完成卡片创建、数据绑定、动态刷新与页面跳转四步闭环,缺一不可——否则卡片添加后空白、点击无响应或时间不更新。
新建元服务卡片模块
打开DevEco Studio,在已创建的元服务工程根目录右键 → New → Module → 选择“Service Widget”模板 → 命名为“widget_card” → 点击Finish。
这一步必须在Stage模型下进行;若项目为FA模型或未启用Stage,新建选项将不可见。【新建前务必确认工程配置为Stage模型,否则无法生成合法卡片结构】
生成后,自动创建widgets目录,含index.ets(UI)、model.ts(逻辑)、config.json(卡片元信息)三个核心文件。
配置卡片尺寸与生命周期
打开widget_card/src/main/resources/base/profile/widget_config.json,修改以下字段:
"defaultLayout": "2x2",
"isDefault": true,
"updateDuration": 0,
"scheduledUpdateTime": "00:00"
其中updateDuration设为0表示禁用周期刷新,scheduledUpdateTime设为"00:00"表示每日零点定点刷新——这是避免后台频繁唤醒、节省电量的关键设定。
注意:小尺寸(2×2)为必选,若未配置,上架审核会直接驳回。
实现卡片动态日期显示
第一步:在index.ets中声明响应式变量
@State curDate: string = '1990-01-01';
第二步:在onPageShow生命周期中获取当前日期并赋值
onPageShow() { this.curDate = new Date().toISOString().split('T')[0]; }
第三步:在UI中绑定显示
Text(this.curDate).fontSize(14)
这一步仅解决首次加载显示,不处理后续更新——若只做这一步,用户第二天看到的仍是昨天的日期。
让卡片真正“活”起来:定时刷新数据
方法一:使用系统级定点刷新(推荐)
在widget_card/src/main/ets/model/widgetModel.ets中,找到onUpdate函数,添加如下代码:
onUpdate(want: common.Want, formId: number): void { const now = new Date(); const dateStr = now.toISOString().slice(0, 10); formProvider.updateForm(formId, { curDate: dateStr }); }
此函数会在scheduledUpdateTime指定时刻被系统调用,无需手动启停定时器。
方法二:手动启动定时器(慎用)
在onPageShow中调用setInterval(() => { this.curDate = new Date().toISOString().split('T')[0]; }, 60000);
【禁止在卡片中长期运行setInterval,会导致系统强制回收卡片进程,卡片变灰失效】
从卡片跳转到元服务内部页面
第一步:在index.ets中给Text组件添加router事件
Text('进入游戏').onClick(() => { router.pushUrl({ url: 'pages/index', params: { fromCard: true, level: 1 } }); })
第二步:在目标页面pages/index.ets的onPageShow中读取参数
onPageShow() { const params = router.getParams() as Record
第三步:确保pages/index.ets所在模块已在module.json5中声明为Ability,并且abilityName与router.pushUrl中url路径严格匹配——路径错误会导致白屏且无报错提示。











