UniApp (Vue3 非CLI项目) 配置鸿蒙 (HarmonyOS) 的Deep Linking指南

概述

Deep Linking（深度链接）允许用户通过点击一个自定义的 URL Scheme（如 myapp://path?key=value）直接唤醒您的鸿蒙应用，并传递参数。这在营销推广、社交分享、消息推送等场景中至关重要。

在鸿蒙平台，实现此功能主要涉及两个步骤：

1. 配置 Scheme：在鸿蒙原生配置文件中声明您的应用可以响应的 URL 协议。
2. 解析参数：在应用启动时（冷启动）或被再次唤醒时（热启动）获取并处理链接中携带的参数。

前置条件

在开始之前，请确保已准备好以下环境与资源：

1. 开发工具： HBuilderX (最新版)：用于 uni-app 部分的开发、调试和最终资源打包。 DevEco Studio (最新版)：用于鸿蒙原生部分的工程管理、依赖配置、签名打包和真机调试。 请确保两个 IDE 均已正确安装并配置好基础环境 (如 Node.js)。
2. 项目前提： 一个可正常在 HBuilderX 中运行、编译的 uni-app (Vue3) 项目。 项目结构应为标准的 HBuilderX 非 CLI 结构 (通常包含 manifest.json, pages.json, App.vue等文件，但无 package.json或由 HBuilderX 管理依赖)。

参考文档

一些官方介绍和api的链接：
https://uniapp.dcloud.net.cn/tutorial/harmony/runbuild.html#config-dir
https://doc.dcloud.net.cn/uni-app-x/plugin/uts-plugin.html#%E5%89%8D%E7%AB%AF%E4%BD%BF%E7%94%A8%E6%8F%92%E4%BB%B6
https://uniapp.dcloud.net.cn/tutorial/harmony/url-scheme.html

第一步：配置 Deep Linking (URL Scheme)

此步骤是在鸿蒙原生工程中注册您的应用能够处理的 URL 模式。

• 定位配置文件

  打开项目根目录下的 harmony-configs/entry/src/main/module.json5文件。如果此文件不存在，请先运行一次项目到鸿蒙，HBuilderX 会自动生成基础模板。

• 修改 skills配置

  在 module.json5文件中，找到 abilities数组下的第一个 ability（通常是 EntryAbility），在其 skills数组中添加一个新的 Skill 对象 。

  // harmony-configs/entry/src/main/module.json5
  {
    "module": {
      // ... 其他配置 ...
      "abilities": [
        {
          "name": "EntryAbility",
          "srcEntry": "./ets/entryability/EntryAbility.ets",
          // ... 其他配置 ...
          "skills": [
            {
              // 这是原有的默认 Skill，用于正常启动应用，请勿删除或修改。
              "entities": ["entity.system.home"],
              "actions": ["ohos.want.action.home"]
            },
            {
              // 【新增】这是用于响应 Deep Link 的 Skill
              "actions": [
                "ohos.want.action.viewData" // 固定值
              ],
              "uris": [
                {
                  "scheme": "yourapp", // 【必填】
                  "host": "open",       // 【必填】
                }
              ]
            }
          ]
        }
      ]
    }
  }
  

  参数说明：

  • scheme: 您应用的唯一标识符，建议使用简短、易记的英文，避免与主流应用冲突。例如 weixin。

  • host: 路径。

  • url这个数组可以有多个对象，也就是说可以设置“yourapp://open/home”同时设置“yourapp://use”

  • 文档：deeplink的uniapp官方文档

• 配置生效

• 保存 module.json5文件。下次运行或发行应用时，此配置将自动合并到鸿蒙工程中并生效。

第二步：在外部触发 Deep Link

配置完成后，您可以在以下场景使用链接唤起应用：

• 网页中：

• <a href="yourapp://open/home">打开我的应用</a>
  <a href="yourapp://open/detail?id=123&from=share">打开详情页</a>
  

• 其他应用中：通过系统的 Intent 机制或调用鸿蒙的 want能力。

• 二维码：将 yourapp://open/?data=xxx生成二维码，用户扫码即可唤起。

当用户点击此类链接时，系统会弹出提示框询问是否用您的应用打开，确认后即会唤起应用。

第三步：在 UniApp 中获取启动参数

应用被唤起后，您需要在代码中获取链接携带的参数。UniApp 提供了标准 API，也支持通过 UTS 插件获取更底层的生命周期信息。

方案一：使用 UniApp 标准 API（推荐，简单直接）

从 HBuilderX 3.6.18+ 版本开始，uni.getLaunchOptionsSync()和 uni.onShow()已支持获取鸿蒙平台的启动参数 。

1. 在 App.vue的 onLaunch或 onShow中获取（适用于冷启动和热启动）

但我发现uni.getLaunchOptionsSync()无法获取热启动的时候传递的参数。

2. 在任意页面监听 onShow

但我发现uni.getLaunchOptionsSync()无法获取热启动的时候传递的参数。

方案二：通过 UTS 插件监听原生生命周期

如果需要更早地（在 UniApp 框架初始化前）获取参数，或需要区分 onCreate和 onNewWant生命周期，可以创建 UTS 插件 。

1. 创建 UTS 插件 在项目 uni_modules目录上右键 -> 新建插件-> 选择 UTS插件，命名为 uni-deeplink-listener。

2. 编写鸿蒙平台代码 在插件目录下创建文件 utssdk/app-harmony/index.uts： `
   

// utssdk/app-harmony/index.uts
import { Want } from "@kit.AbilityKit";

UTSHarmony.onAppAbilityCreate((want: Want) => {
  //  实际上立即执行了，但是通信通道还没有建立，延迟一秒打印可以看到数据
  //  延迟是为了看到打印，业务逻辑不需要延迟
  setTimeout(() => {
    // console.log("开始了吗开始了吗", want);
	  uni.$emit('onAppAbilityCreate', want);
  }, 1000);
});
UTSHarmony.onAppAbilityNewWant((want: Want) => {
  // console.log("收到收到收到", want);
  uni.$emit('onAppAbilityCreate', want);
});

export const geturlFunction: any = function (thisfn:any): void {
uni.$on('onAppAbilityCreate', (want: Want) => {
	// console.log("打印下打印下", want);
	if (typeof thisfn === 'function') {
		thisfn(want);
	}
})
}

3. 在 UniApp 中使用插件

   // 在 main.js 或 App.vue 中尽早引入
   import { geturlFunction } from '@/uni_modules/nc-harmurl';
   
   export default {
     onLaunch() {
       // 调用 UTS 插件方法获取原生层的 Want 对象
      geturlFunction((want)=>{
      onsole.log('看看打印看看传递',want);
      if(!want.uri)return this.toRemoveTheKey();
      console.log('出来了出来了',want.uri);
      })
     }
   }

注意事项与常见问题

应用中唤起有两个不同的场景：

• 冷启动-通过网页第一次唤起应用，对应鸿蒙中的 onCreate 生命周期
• 热启动-应用已经启动，重新从后台唤起应用，对应鸿蒙中的 onNewWant 生命周期
• 应用启动时候获取参数，自定义业务逻辑，在应用加载时候监听参数，具体如何跳转是应用自己处理的。

总结

在 UniApp 中为鸿蒙配置 Deep Linking 并获取参数，主要流程如下：

1. 配置：在 harmony-configs/entry/src/main/module.json5中正确添加包含 actions和 uris的 skill。
2. 触发：使用 yourScheme://yourHost/yourPath?key=value格式的链接从外部唤起应用。
3. 获取参数： 推荐：通过创建 UTS 插件监听 onAppAbilityCreate和 onAppAbilityNewWant生命周期，获取原始的 Want对象进行更精细的控制 。

按照以上步骤，您即可在 UniApp 鸿蒙应用中实现完整的 Deep Linking 功能。