hzdyjs/mobile/README-wechat-integration.md

微信JS-SDK集成文档

🎯 项目概述

本文档介绍如何在智慧校园移动应用（mobile工程）中集成微信JS-SDK功能，实现微信浏览器内的原生功能调用。

📋 技术架构

• 技术栈: uni-app 2.x + Vue 2.6.14 + TypeScript + uview-ui 2.0.38
• 微信JS-SDK版本: 1.6.0
• 支持平台: H5（微信浏览器环境）
• 集成方式: 官方CDN + 本地工具类封装

🚀 快速开始

1. 前置条件

1.1 微信公众平台配置

• 已认证的微信服务号
• 已配置JS接口安全域名
• 获取AppID和AppSecret

1.2 后端接口支持

确保后端已实现以下接口：

POST /system/wechat/config      # 获取JS-SDK配置
POST /system/wechat/upload      # 上传微信媒体文件
GET  /system/wechat/download    # 下载微信媒体文件
GET  /system/wechat/userinfo    # 获取微信用户信息

2. 项目文件结构

mobile/
├── public/
│   └── index.html              # 已添加微信JS-SDK脚本引用
├── src/
│   ├── api/
│   │   └── wechat.ts          # 微信API接口定义
│   ├── utils/
│   │   └── wechat.js          # 微信JS-SDK工具类
│   └── components/
│       └── WeChatDemo.vue     # 功能演示组件
└── README-wechat-integration.md  # 本文档

3. 基础使用示例

3.1 在页面中使用微信SDK

<template>
  <view>
    <button @click="initWeChatSDK">初始化微信SDK</button>
    <button @click="scanQRCode" :disabled="!isInitialized">扫一扫</button>
    <button @click="shareToFriends" :disabled="!isInitialized">分享给朋友</button>
  </view>
</template>

<script>
import weChatSDK from '@/utils/wechat.js';

export default {
  data() {
    return {
      isInitialized: false
    };
  },
  methods: {
    async initWeChatSDK() {
      try {
        await weChatSDK.init();
        this.isInitialized = true;
        console.log('微信SDK初始化成功');
      } catch (error) {
        console.error('初始化失败:', error);
      }
    },
    
    async scanQRCode() {
      try {
        const result = await weChatSDK.scanQRCode();
        console.log('扫码结果:', result.resultStr);
      } catch (error) {
        console.error('扫码失败:', error);
      }
    },
    
    async shareToFriends() {
      try {
        await weChatSDK.shareAppMessage({
          title: '智慧校园',
          desc: '校园管理系统',
          link: window.location.href,
          imgUrl: 'https://example.com/logo.png'
        });
        console.log('分享配置成功');
      } catch (error) {
        console.error('分享失败:', error);
      }
    }
  }
};
</script>

📚 API文档

微信工具类 (wechat.js)

初始化方法

init(options)

初始化微信JS-SDK配置

参数:

• options.url (String, 可选): 当前页面URL，默认自动获取
• options.jsApiList (Array, 可选): 需要使用的API列表，默认使用全部
• options.debug (Boolean, 可选): 是否开启调试模式，默认根据环境

返回: Promise

await weChatSDK.init({
  debug: false,
  jsApiList: ['chooseImage', 'scanQRCode']
});

环境检测方法

isWeChatBrowser()

检查是否在微信浏览器中

返回: Boolean

getCurrentUrl()

获取当前页面URL（去除hash部分）

返回: String

分享功能

shareTimeline(shareData)

分享到朋友圈

参数:

• shareData.title (String): 分享标题
• shareData.link (String): 分享链接
• shareData.imgUrl (String): 分享图标

shareAppMessage(shareData)

分享给朋友

参数:

• shareData.title (String): 分享标题
• shareData.desc (String): 分享描述
• shareData.link (String): 分享链接
• shareData.imgUrl (String): 分享图标

扫码功能

scanQRCode(options)

微信扫一扫

参数:

• options.needResult (Number, 可选): 是否返回扫描结果，默认1
• options.scanType (Array, 可选): 扫码类型，默认['qrCode', 'barCode']

返回: Promise<{resultStr: string}>

图片功能

chooseImage(options)

选择图片

参数:

• options.count (Number, 可选): 图片数量，默认1
• options.sizeType (Array, 可选): 图片尺寸，默认['original', 'compressed']
• options.sourceType (Array, 可选): 图片来源，默认['album', 'camera']

返回: Promise<{localIds: string[]}>

previewImage(options)

预览图片

参数:

• options.current (String): 当前显示图片的http链接
• options.urls (Array): 需要预览的图片http链接列表

地理位置

getLocation(options)

获取地理位置

参数:

• options.type (String, 可选): 坐标类型，默认'gcj02'

返回: Promise<{latitude: number, longitude: number, accuracy: number}>

openLocation(location)

打开地图

参数:

• location.latitude (Number): 纬度
• location.longitude (Number): 经度
• location.name (String, 可选): 位置名称
• location.address (String, 可选): 地址详情
• location.scale (Number, 可选): 地图缩放级别，默认14

设备信息

getNetworkType()

获取网络状态

返回: Promise<{networkType: string}>

支付功能

chooseWXPay(payInfo)

微信支付

参数:

• payInfo.timestamp (String): 时间戳
• payInfo.nonceStr (String): 随机字符串
• payInfo.package (String): 订单详情扩展字符串
• payInfo.signType (String, 可选): 签名方式，默认'MD5'
• payInfo.paySign (String): 签名

其他功能

checkJsApi(jsApiList)

检查当前客户端版本是否支持指定JS接口

closeWindow()

关闭当前网页窗口

API接口 (wechat.ts)

getWeChatConfig(url: string)

获取微信JS-SDK配置信息

uploadWeChatMedia(mediaId: string, type: string)

上传微信临时素材

downloadWeChatMedia(mediaId: string)

下载微信临时素材

getWeChatUserInfo(code: string)

获取微信用户信息

createWeChatPay(orderData: any)

生成微信支付订单

🔧 配置说明

1. 微信公众平台配置

1. 登录微信公众平台
2. 进入"设置" → "公众号设置" → "功能设置"
3. 配置"JS接口安全域名"
4. 填入你的网站域名（不需要协议头，不需要www）

2. 后端配置要求

后端需要实现微信JS-SDK配置接口，返回格式：

{
  "code": 200,
  "data": {
    "appId": "wx1234567890abcdef",
    "timestamp": 1640995200,
    "nonceStr": "Wm3WZYTPz0wzccnW",
    "signature": "0f9de62fce790f9a083d5c99e95740ceb90c27ed"
  },
  "msg": "success"
}

3. 环境配置

确保项目配置文件中的API地址正确：

// mobile/src/common/config.js
export const REQUEST_CONFIG = {
  baseURL: process.env.NODE_ENV === 'development' ? '/api' : '/prod-api'
};

🎨 功能演示组件

项目提供了完整的功能演示组件 WeChatDemo.vue，包含：

• ✅ 微信环境检测
• ✅ SDK初始化状态
• ✅ 分享功能（朋友圈/朋友）
• ✅ 扫码功能
• ✅ 图片选择和预览
• ✅ 地理位置获取
• ✅ 设备信息查询
• ✅ 接口支持检查

使用方法：

<template>
  <view>
    <WeChatDemo />
  </view>
</template>

<script>
import WeChatDemo from '@/components/WeChatDemo.vue';

export default {
  components: {
    WeChatDemo
  }
};
</script>

🚀 部署注意事项

1. 域名配置

• 确保生产环境域名已在微信公众平台配置
• 域名必须通过ICP备案
• 支持绑定最多5个域名

2. HTTPS要求

• 生产环境必须使用HTTPS协议
• 本地开发可以使用HTTP

3. 跨域处理

微信JS-SDK不存在跨域问题，但需要确保：

• 配置获取接口可以正常访问
• 分享的链接在安全域名内

🔍 调试指南

1. 开启调试模式

await weChatSDK.init({
  debug: true  // 开启调试模式
});

2. 常见问题排查

问题1: invalid signature 签名失败

原因: 签名验证失败 解决:

• 检查后端签名算法
• 确认URL参数正确（不包含#hash部分）
• 验证时间戳和随机字符串

问题2: permission denied 权限拒绝

原因: 接口未授权或不在jsApiList中 解决:

• 确认服务号权限
• 检查jsApiList配置
• 验证config是否正确执行

问题3: the permission value is offline verifying

原因: config配置有误 解决:

• 检查config参数完整性
• 确保在wx.ready回调中调用JSAPI
• 验证jsApiList包含所需接口

3. 调试工具

使用微信开发者工具进行调试：

1. 打开微信开发者工具
2. 新建项目，选择"网页"
3. 输入你的网站URL
4. 在控制台查看调试信息

📱 兼容性说明

支持的微信版本

• iOS: 6.0.2及以上
• Android: 6.0.2及以上

支持的功能

• ✅ 基础分享功能
• ✅ 图像处理
• ✅ 地理位置
• ✅ 设备信息
• ✅ 扫一扫
• ✅ 微信支付

平台限制

• 仅支持微信浏览器环境
• 部分接口需要服务号认证
• 支付功能需要开通微信支付

🔗 相关资源

官方文档

• 微信JS-SDK说明文档
• 微信公众平台

项目文档

• 移动端开发规范
• API开发规范
• 项目部署文档

📝 更新日志

v1.0.0 (2025-01-03)

• ✅ 完成微信JS-SDK基础集成
• ✅ 实现常用API功能封装
• ✅ 创建功能演示组件
• ✅ 编写完整使用文档

---

维护者: 开发团队
最后更新: 2025-01-03
文档版本: v1.0.0