文档开发者中心
我的

HarmonyOS 元服务卡片与 App 互跳:三种场景的完整实现方案

浏览7发布于1 小时前北京

元服务卡片与 App 互跳三种场景全景:桌面卡片、App 商品详情页与元服务详情页

做电商类鸿蒙应用时,产品提了个需求:用户在桌面卡片上点"立即购买",要能直接跳到 App 的商品详情页;App 没装的话引导去应用市场下载。反过来,App 里要能一键把商品卡片"收藏"到桌面。

这两个方向涉及元服务(Atomic Service)和普通 App 之间的跨 bundle 通信,鸿蒙文档里没有把完整链路串起来讲。我踩了几轮坑后把方案整理出来,涵盖三个互跳场景,每个都给到可运行代码。

为什么不能直接跨 bundle 跳

先说清楚一个容易误解的点:元服务卡片(Form)的 postCardAction 只能 router 到自己所属元服务的 UIAbility,不能跨 bundle 直接拉起另一个 App 的 Ability。

这不是 API 设计的遗漏,而是安全隔离——卡片运行在独立的沙箱里,没有权限直接启动其他应用。所以"卡片 → App"的跳转本质上是一个两步中转:

  1. 卡片先 router 到自己元服务内的 UIAbility(同 bundle,合法)
  2. 那个 UIAbility 再通过 Deep Linking 或 startAbility 去拉起目标 App(跨 bundle,走系统路由)

理解了这个中转结构,后面的代码就好读了。

场景一:元服务卡片 → App 商品详情页

场景一:卡片点击立即购买后,按 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 内一键收藏到桌面卡片,经确认弹窗后卡片出现在桌面 反向场景:用户在 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 到卡片的双向链路。如果你也在做鸿蒙电商类应用或类似卡片交互场景,希望这些代码和踩坑经验能帮你少走弯路。

参考链接

拉起其他元服务

跳转商户鸿蒙App

AppLinking跳转

收藏
0
回复
1
分享
全部评论
authorIcon
lovoyd
学习一下
回复于45 分钟前广西
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
目录 收起
为什么不能直接跨 bundle 跳
场景一:元服务卡片 → App 商品详情页
Step 1:卡片 postCardAction router 到元服务自己的 UIAbility
Step 2:元服务 UIAbility 中判断 App 是否安装,分流跳转
降级策略的选择
场景二:App 商品详情页 → "收藏"到元服务卡片
方案选型:requestPublishForm vs 引导手动添加
代码实现
踩坑提醒
场景三:桌面卡片 → 元服务商品详情页
App 侧 Deep Linking 配置
踩坑总结
参考链接
了解社区公约,与您携手共创和谐专业的开发者社区。