
做电商类鸿蒙应用时,产品提了个需求:用户在桌面卡片上点"立即购买",要能直接跳到 App 的商品详情页;App 没装的话引导去应用市场下载。反过来,App 里要能一键把商品卡片"收藏"到桌面。
这两个方向涉及元服务(Atomic Service)和普通 App 之间的跨 bundle 通信,鸿蒙文档里没有把完整链路串起来讲。我踩了几轮坑后把方案整理出来,涵盖三个互跳场景,每个都给到可运行代码。
为什么不能直接跨 bundle 跳
先说清楚一个容易误解的点:元服务卡片(Form)的 postCardAction 只能 router 到自己所属元服务的 UIAbility,不能跨 bundle 直接拉起另一个 App 的 Ability。
这不是 API 设计的遗漏,而是安全隔离——卡片运行在独立的沙箱里,没有权限直接启动其他应用。所以"卡片 → App"的跳转本质上是一个两步中转:
- 卡片先 router 到自己元服务内的 UIAbility(同 bundle,合法)
- 那个 UIAbility 再通过 Deep Linking 或
startAbility去拉起目标 App(跨 bundle,走系统路由)
理解了这个中转结构,后面的代码就好读了。
场景一:元服务卡片 → App 商品详情页

Step 1:卡片 postCardAction router 到元服务自己的 UIAbility
卡片侧只负责发出意图,具体路由逻辑交给 UIAbility 处理:
// 元服务卡片页面
Button('立即购买')
.onClick(() => {
postCardAction(this, {
action: 'router',
abilityName: 'WidgetEntryAbility', // 元服务自己的 UIAbility
params: {
productId: 'SKU12345',
action: 'buy' // 自定义标记,区分业务
}
});
})
params 里塞了一个自定义的 action: 'buy' 字段,后面在 UIAbility 里用它区分"购买"和"看详情"两种业务路径。这个设计比拆成两个 Ability 更轻,一个 UIAbility 内部分流就够。
Step 2:元服务 UIAbility 中判断 App 是否安装,分流跳转
这是整个链路的核心。UIAbility 收到 router 消息后,先判断目标 App 是否已安装——已装走 Deep Linking 拉起,未装跳应用市场:
// 元服务 WidgetEntryAbility.ets
import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit';
import { bundleManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
const APP_BUNDLE_NAME = 'com.example.shopapp';
const APP_DEEP_LINK_SCHEME = 'shopapp';
export default class WidgetEntryAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
this.handleBuyAction(want);
}
onNewWant(want: Want): void {
this.handleBuyAction(want);
}
private handleBuyAction(want: Want): void {
if (want?.parameters?.params) {
let params: Record<string, string> = JSON.parse(want.parameters.params as string);
if (params.action === 'buy') {
let productId: string = params.productId;
let context = this.context;
// 用 canOpenLink 判断目标 App 是否已安装
// 前提:元服务的 module.json5 里必须声明 querySchemes,否则调不到
let installed: boolean = false;
try {
installed = bundleManager.canOpenLink(`${APP_DEEP_LINK_SCHEME}://product/detail`);
} catch (e) { installed = false; }
if (installed) {
// 已装:通过 Deep Linking 拉起 App 商品详情页
let linkWant: Want = {
action: 'ohos.want.action.viewData',
uri: `${APP_DEEP_LINK_SCHEME}://product/detail?id=${productId}`,
};
context.startAbility(linkWant).catch((err: BusinessError) => {
// 拉起失败,降级去应用市场
this.openAppGallery(context);
});
} else {
// 未装:跳应用市场详情页
this.openAppGallery(context);
}
}
}
}
private openAppGallery(context: UIAbilityContext): void {
let storeWant: Want = {
action: 'ohos.want.action.appdetail',
uri: `store://appgallery.huawei.com/app/detail?id=${APP_BUNDLE_NAME}`,
};
context.startAbility(storeWant);
}
}
几个关键点说明:
canOpenLink 为什么能判断是否安装? 它的原理是向系统查询"有没有已注册的 Ability 能响应这个 URI scheme"。App 在自己的 module.json5 里声明了 shopapp://product/detail 的 skills,系统就记住了。如果 App 没装,没人认领这个 scheme,canOpenLink 返回 false。
为什么要 try-catch? canOpenLink 在元服务未声明 querySchemes 时会直接抛异常而不是返回 false,不接住会 crash。这点文档没明说,我是线上 crash 了一次才知道的。
onCreate 和 onNewWant 都要处理? 是的。onCreate 是冷启动(UIAbility 进程不存在),onNewWant 是热启动(进程已在后台,卡片再次点击)。只写 onCreate 的话,用户第二次点卡片就不响应了。
元服务 module.json5 配置(不配这个 canOpenLink 直接抛异常):
{
"module": {
"querySchemes": ["shopapp"], // 声明要查询的 scheme
// ...
}
}
降级策略的选择
上面代码用了两级降级:startAbility 失败 → 跳应用市场。实际项目里我还遇到过一种情况——App 已装但 Deep Linking 配置有误(scheme 对不上),canOpenLink 返回 true 但 startAbility 抛异常。catch 住后跳市场,用户至少不会卡在白屏上。
如果你需要更精细的处理,可以在 catch 里加一层:先尝试用 bundleName 显式 startAbility(不依赖 scheme 匹配),再失败才跳市场。但大多数场景两级够用,别过度设计。
场景二:App 商品详情页 → "收藏"到元服务卡片
反向场景:用户在 App 里看中一个商品,想把它做成桌面卡片方便随时查看。
方案选型:requestPublishForm vs 引导手动添加
鸿蒙提供了两种方式让用户添加桌面卡片:
| 方式 | API | 体验 | 限制 |
|---|---|---|---|
formHost.requestPublishForm |
API 18+ | App 内一键添加,可携带商品数据 | 需要用户确认弹窗 |
| 引导到卡片管理页 | 通用 | 用户手动找到卡片并添加 | 无法传数据,体验割裂 |
如果目标设备 API ≥ 18,直接用 requestPublishForm,能把商品 ID、名称等数据带过去,卡片添加后立刻显示正确内容。低版本设备只能降级引导。
代码实现
App 商品详情页发起添加请求:
import { formHost } from '@kit.AbilityKit';
import { common } from '@kit.AbilityKit';
// App 商品详情页
Button('收藏到桌面卡片')
.onClick(async () => {
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
// 通过 formHost 请求添加卡片(API 18+)
try {
await formHost.requestPublishForm({
bundleName: 'com.example.shopwidget', // 元服务包名
moduleName: 'entry',
abilityName: 'ProductFormAbility', // 元服务的 FormExtensionAbility
formDimension: 2, // 2×2 卡片
formName: 'productCard',
// 传入商品数据,卡片 onAddForm 时可拿到
data: { 'productId': 'SKU12345', 'productName': '...' }
});
} catch (e) {
// 降级:引导用户到系统卡片添加页(长按桌面 → 添加卡片)
// 此场景无法传数据,卡片需自行拉取默认信息
}
})
元服务 FormExtensionAbility.onAddForm 中接收数据并返回给卡片:
import { formBindingData, FormExtensionAbility } from '@kit.AbilityKit';
export default class ProductFormAbility extends FormExtensionAbility {
onAddForm(want: Want): formBindingData.FormBindingData {
let productId = want.parameters?.productId as string || '';
let productName = want.parameters?.productName as string || '';
return formBindingData.createFormBindingData({
productId, productName
});
}
}
onAddForm 返回的 FormBindingData 会直接刷新卡片 UI。注意这个回调只在卡片首次添加到桌面时触发一次,后续卡片数据更新走 onUpdateForm,需要在 FormExtensionAbility 里定时或事件驱动地刷新。
踩坑提醒
data 字段传递的数据类型有限制。 只支持 string 类型的 key-value,不能直接传对象。如果商品信息复杂(规格、价格、库存),建议只传 productId,卡片侧在 onAddForm 里用这个 ID 去请求接口拿完整数据。我第一版把整个商品对象序列化塞进去,结果数据量超限直接静默失败,卡片添加了但内容空白。
场景三:桌面卡片 → 元服务商品详情页
用户已经把卡片放到桌面了,点一下要进入元服务自己的详情页(不是跳 App,是在元服务内展示)。
// 元服务卡片
@Entry
@Component
struct ProductCard {
@LocalStorageProp('productId') productId: string = '';
build() {
Column() {
Text(this.productName)
// 整卡点击跳转
}
.onClick(() => {
postCardAction(this, {
action: 'router',
abilityName: 'WidgetEntryAbility',
params: {
productId: this.productId,
action: 'detail' // 标记:进详情而非购买
}
});
})
}
}
注意这里复用了场景一的 WidgetEntryAbility,只是 action 从 'buy' 换成了 'detail'。UIAbility 里分支处理:
// WidgetEntryAbility.ets — onCreate / onNewWant 中
onNewWant(want: Want): void {
if (want?.parameters?.params) {
let params: Record<string, string> = JSON.parse(want.parameters.params as string);
if (params.action === 'detail') {
AppStorage.setOrCreate('targetPage', `ProductDetail`);
AppStorage.setOrCreate('productId', params.productId);
}
if (params.action === 'buy') {
// ... 上面的购买逻辑
}
}
}
页面路由为什么用 AppStorage 而不是直接 router? 因为 UIAbility 的 onCreate/onNewWant 执行时页面栈还没初始化,直接调 router.pushUrl 会报错。正确做法是先把目标页标识写进 AppStorage,页面 onPageShow 时读出来再路由。这也是我踩过的一个坑。
App 侧 Deep Linking 配置
场景一里元服务通过 shopapp://product/detail 拉起 App,App 侧必须在 module.json5 声明对应的 skills,否则系统找不到接收方:
{
"module": {
"abilities": [{
"name": "DeepAbility",
"skills": [
{ "actions": ["entity.system.home"], "actions": ["ohos.want.action.home"] },
{
"actions": ["ohos.want.action.viewData"],
"uris": [{
"scheme": "shopapp",
"host": "product",
"path": "/detail"
}]
}
]
}]
}
}
App 的 DeepAbility.onCreate / onNewWant 解析 uri 拿到 id 参数,跳转详情页即可:
// DeepAbility.ets
export default class DeepAbility extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
this.handleDeepLink(want);
}
onNewWant(want: Want): void {
this.handleDeepLink(want);
}
private handleDeepLink(want: Want): void {
let uri = want.uri; // shopapp://product/detail?id=SKU12345
if (uri) {
let url = new URL(uri);
let productId = url.searchParams.get('id');
if (productId) {
AppStorage.setOrCreate('targetPage', 'ProductDetail');
AppStorage.setOrCreate('productId', productId);
}
}
}
}
坑提醒:
skills里的host和path必须和元服务发出的 URI 完全匹配,区分大小写。我有一次path写成/Detail(大写 D),元服务发的是/detail,死活拉不起来,排查了半小时。
踩坑总结
| 场景 | 坑 | 原因 | 解法 |
|---|---|---|---|
| 卡片 → App | canOpenLink 抛异常 |
元服务未声明 querySchemes |
module.json5 里加 querySchemes |
| 卡片 → App | 热启动点击不响应 | 只写了 onCreate,没写 onNewWant |
两个回调都处理 |
| App → 卡片 | 卡片内容空白 | requestPublishForm 的 data 数据量超限 |
只传 productId,卡片侧拉接口补数据 |
| 卡片 → 详情 | router.pushUrl 报错 |
UIAbility 回调执行时页面栈未初始化 | 用 AppStorage 传递目标页,页面 onPageShow 再路由 |
| Deep Linking | scheme 拉不起来 | skills 的 path 大小写不匹配 |
严格对齐大小写 |
这套方案在我们项目里已经稳定跑了三个版本,覆盖了从卡片到 App、从 App 到卡片的双向链路。如果你也在做鸿蒙电商类应用或类似卡片交互场景,希望这些代码和踩坑经验能帮你少走弯路。







































苏公安网备 32011402010933号