428 lines
9.6 KiB
Markdown
428 lines
9.6 KiB
Markdown
# 微信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
|
||
|
||
```vue
|
||
<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
|
||
|
||
```javascript
|
||
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配置接口，返回格式：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"appId": "wx1234567890abcdef",
|
||
"timestamp": 1640995200,
|
||
"nonceStr": "Wm3WZYTPz0wzccnW",
|
||
"signature": "0f9de62fce790f9a083d5c99e95740ceb90c27ed"
|
||
},
|
||
"msg": "success"
|
||
}
|
||
```
|
||
|
||
### 3. 环境配置
|
||
|
||
确保项目配置文件中的API地址正确：
|
||
|
||
```javascript
|
||
// mobile/src/common/config.js
|
||
export const REQUEST_CONFIG = {
|
||
baseURL: process.env.NODE_ENV === 'development' ? '/api' : '/prod-api'
|
||
};
|
||
```
|
||
|
||
## 🎨 功能演示组件
|
||
|
||
项目提供了完整的功能演示组件 `WeChatDemo.vue`，包含：
|
||
|
||
- ✅ 微信环境检测
|
||
- ✅ SDK初始化状态
|
||
- ✅ 分享功能（朋友圈/朋友）
|
||
- ✅ 扫码功能
|
||
- ✅ 图片选择和预览
|
||
- ✅ 地理位置获取
|
||
- ✅ 设备信息查询
|
||
- ✅ 接口支持检查
|
||
|
||
使用方法：
|
||
|
||
```vue
|
||
<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. 开启调试模式
|
||
|
||
```javascript
|
||
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说明文档](https://developers.weixin.qq.com/doc/service/guide/h5/jssdk.html)
|
||
- [微信公众平台](https://mp.weixin.qq.com/)
|
||
|
||
### 项目文档
|
||
- [移动端开发规范](../.cursor/cursorrules-mobile.md)
|
||
- [API开发规范](../docs/开发文档/API/)
|
||
- [项目部署文档](../docs/部署文档/)
|
||
|
||
## 📝 更新日志
|
||
|
||
### v1.0.0 (2025-01-03)
|
||
- ✅ 完成微信JS-SDK基础集成
|
||
- ✅ 实现常用API功能封装
|
||
- ✅ 创建功能演示组件
|
||
- ✅ 编写完整使用文档
|
||
|
||
---
|
||
|
||
**维护者**: 开发团队
|
||
**最后更新**: 2025-01-03
|
||
**文档版本**: v1.0.0 |