更新记录

1.0.1（2026-05-07）

• 插件更名为 zzc-wechat-hm
• 升级微信开放 SDK 依赖至 ^1.0.16
• 完善文档，新增二次开发指南（检查微信安装、网页分享、微信客服扩展示例）
• 新增 SDK 各版本变更对照表

1.0.0（2026-02-15）

基于微信开放 SDK 的 HarmonyOS 跳转微信小程序 UTS 插件，支持 uni-app 和 uni-app x 项目。

平台兼容性

uni-app(4.76)

uni-app x(4.76)

zzc-***-hm

基于微信开放 SDK（微信 Open SDK for HarmonyOS Next）的 HarmonyOS 跳转微信小程序 UTS 插件，支持 uni-app 和 uni-app x 项目。

功能特性

• 支持 HarmonyOS 系统跳转微信小程序
• 支持正式版、开发版、体验版小程序
• 支持自定义小程序页面路径
• 完整的错误处理机制

环境要求

• HBuilderX >= 3.6.8
• uni-app >= 3.1.0 或 uni-app-x >= 3.1.0
• HarmonyOS SDK（DevEco Studio）

快速开始

1. 安装插件

将 zzc-***-hm 目录复制到项目的 src/uni_modules/ 下。

2. 调用

import { launchMiniProgram } from "@/uni_modules/zzc-***-hm";

launchMiniProgram({
  appId: "your_***_appid",       // 微信开放平台 AppID
  userName: "gh_ff02937dbaec",       // 小程序原始ID
  path: "/pages/index/index",        // 小程序页面路径（可选）
  miniprogramType: 0,                // 0-正式版 1-开发版 2-体验版
}).then((result) => {
  if (result.success) {
    console.log("跳转成功");
  } else {
    console.error("跳转失败:", result.error);
  }
});

3. 参数说明

4. 返回值

interface LaunchMiniProgramResult {
  success: boolean;    // 是否成功
  error?: string;      // 错误信息
  errorCode?: number;  // 错误代码
}

错误代码：

二次开发

如需二次开发（修改功能、升级 SDK 等），按以下步骤操作：

1. 获取微信 Open SDK

前往微信开放文档下载最新版 SDK：

https://developers.weixin.qq.com/doc/oplatform/Mobile_App/Downloads/HarmonyOS_Resource.html

当前插件使用的 SDK 版本为 1.0.16（通过 ohpm 依赖 @tencent/***_open_sdk 自动拉取）。

各版本主要变更（摘自微信官方文档）：

2. 扩展示例

核心源码位于 utssdk/app-harmony/index.uts，下面是几个常见扩展场景的代码示例。

示例一：导出「检查微信是否安装」

在 index.uts 底部添加导出：

// 检查微信是否已安装
export function checkWXInstalled(appId: string): boolean {
  if (!initWXAPI(appId)) {
    return false;
  }
  return isWXAppInstalled();
}

调用方：

import { checkWXInstalled } from "@/uni_modules/zzc-***-hm";

const installed = checkWXInstalled("your_***_appid");
if (!installed) {
  console.log("请先安装微信");
}

同时在 interface.uts 中添加类型声明：

export function checkWXInstalled(appId: string): boolean;

示例二：分享网页到微信好友

// 分享网页链接到微信会话
export const shareWebpageToWX = async (options: {
  appId: string;
  webpageUrl: string;
  title: string;
  description: string;
}): Promise<LaunchMiniProgramResult> => {
  try {
    if (!initWXAPI(options.appId)) {
      return { success: false, error: "微信 API 初始化失败", errorCode: -3 };
    }
    if (!isWXAppInstalled()) {
      return { success: false, error: "未安装微信客户端", errorCode: -4 };
    }

    const context = getAppContext();
    if (!context) {
      return { success: false, error: "无法获取应用上下文", errorCode: -5 };
    }

    // 构造分享内容
    const webpageObj = new wxopensdk.WXWebpageObject();
    webpageObj.webpageUrl = options.webpageUrl;

    const mediaMessage = new wxopensdk.WXMediaMessage();
    mediaMessage.mediaObject = webpageObj;
    mediaMessage.title = options.title;
    mediaMessage.description = options.description;

    // 发送分享请求
    const req = new wxopensdk.SendMessageToWXReq();
    req.message = mediaMessage;
    req.scene = 0; // 0-会话 1-朋友圈

    const result = await wxApiInstance!.sendReq(context, req as Object);
    return result ? { success: true } : { success: false, error: "分享失败", errorCode: -6 };
  } catch (error) {
    return { success: false, error: error.toString(), errorCode: -999 };
  }
};

调用方：

import { shareWebpageToWX } from "@/uni_modules/zzc-***-hm";

shareWebpageToWX({
  appId: "your_***_appid",
  webpageUrl: "https://example.com",
  title: "分享标题",
  description: "分享描述",
});

示例三：拉起微信客服（需 SDK >= 1.0.15）

export const openWXCustomerService = async (options: {
  appId: string;
  corpId: string;
  url: string;
}): Promise<LaunchMiniProgramResult> => {
  try {
    if (!initWXAPI(options.appId)) {
      return { success: false, error: "微信 API 初始化失败", errorCode: -3 };
    }
    const context = getAppContext();
    if (!context) {
      return { success: false, error: "无法获取应用上下文", errorCode: -5 };
    }

    const req = new wxopensdk.OpenCustomerServiceReq();
    req.corpId = options.corpId;
    req.url = options.url;

    const result = await wxApiInstance!.sendReq(context, req as Object);
    return result ? { success: true } : { success: false, error: "拉起客服失败", errorCode: -6 };
  } catch (error) {
    return { success: false, error: error.toString(), errorCode: -999 };
  }
};

扩展步骤总结

1. 在 utssdk/app-harmony/index.uts 中编写新功能函数并 export
2. 在 utssdk/interface.uts 中添加对应的类型声明
3. 在 src/types/uni_modules.d.ts 中补充 TypeScript 类型
4. 在 HBuilderX 中重新构建鸿蒙工程

微信 Open SDK 接入文档：https://developers.weixin.qq.com/doc/oplatform/Mobile_App/Access_Guide/ohos.html

3. 升级 SDK 版本

修改 utssdk/app-harmony/config.json 中的版本号：

{
  "dependencies": {
    "@tencent/***_open_sdk": "^1.0.16"
  }
}

4. 重新构建

修改源码后，在 HBuilderX 中重新构建鸿蒙工程即可生效（运行 > 运行到手机或模拟器 > HarmonyOS）。

注意事项

1. 微信客户端：确保用户已安装微信客户端
2. AppID：必须在 微信开放平台 注册应用并获取 AppID
3. 小程序 ID：userName 是小程序原始ID（以 gh_ 开头），不是小程序 AppID
4. 权限：插件已自动配置 ohos.permission.INTERNET 网络权限
5. 真机测试：建议在真机上测试，模拟器可能无法正常跳转

参考文档

• 微信 Open SDK for HarmonyOS Next 下载
• 微信 Open SDK 接入文档
• 微信开放平台