diff --git a/docs/WECHAT_MINIPROGRAM_PERMISSIONS.md b/docs/WECHAT_MINIPROGRAM_PERMISSIONS.md new file mode 100644 index 0000000..4a84df6 --- /dev/null +++ b/docs/WECHAT_MINIPROGRAM_PERMISSIONS.md @@ -0,0 +1,199 @@ +# 微信小程序权限配置文档 + +## 1. 权限体系概述 + +微信小程序权限体系是微信为保护用户隐私和数据安全而设计的一套权限管理机制。小程序在使用某些功能时,需要向用户申请相应的权限,用户可以选择授权或拒绝。 + +## 2. 权限分类 + +微信小程序权限分为两大类: + +### 2.1 需要单独申请的权限 + +这类权限需要通过 `wx.requestAuthorization` 或相关 API 向用户主动申请,用户会看到授权弹窗,必须明确同意后才能使用。 + +### 2.2 不需要单独申请的权限 + +这类权限不需要通过 API 主动申请,小程序在使用相关功能时会自动触发系统授权提示,或在某些场景下默认授权。 + +## 3. 详细权限列表 + +### 3.1 需要单独申请的权限 + +| 权限名称 | 权限标识 | 描述 | 使用场景 | +|---------|---------|------|----------| +| 地理位置 | `scope.userLocation` | 获取用户地理位置 | 地图定位、附近商家等 | +| 后台定位 | `scope.userLocationBackground` | 后台持续获取地理位置 | 外卖配送、打车等需要后台定位的场景 | +| 录音 | `scope.record` | 录制音频 | 语音消息、语音识别等 | +| 摄像头 | `scope.camera` | 使用摄像头 | 扫码、拍照、视频通话等 | +| 通讯地址 | `scope.address` | 获取用户通讯地址 | 填写收货地址等 | +| 发票抬头 | `scope.invoiceTitle` | 获取用户发票抬头 | 填写发票信息等 | +| 微信运动步数 | `scope.werun` | 获取微信运动步数 | 步数统计、运动排名等 | +| 保存到相册 | `scope.writePhotosAlbum` | 保存图片到相册 | 保存分享图片、截图等 | +| 添加到日历 | `scope.addPhoneCalendar` | 添加事件到日历 | 预约提醒、活动安排等 | +| 读取日历 | `scope.readPhoneCalendar` | 读取日历事件 | 日程管理、智能提醒等 | + +### 3.2 不需要单独申请的权限 + +| 权限名称 | 权限标识 | 描述 | 使用场景 | +|---------|---------|------|----------| +| 剪贴板 | `scope.userClipboard` | 读写剪贴板 | 复制链接、粘贴内容等 | +| 选择地址 | `scope.chooseAddress` | 选择收货地址 | 下单时选择地址 | +| 选择发票 | `scope.chooseInvoice` | 选择发票 | 填写发票信息时选择 | +| 选择发票抬头 | `scope.chooseInvoiceTitle` | 选择发票抬头 | 填写发票信息时选择 | +| 获取网络状态 | - | 获取网络状态 | 网络请求、状态检测等 | +| 获取设备信息 | - | 获取设备型号、操作系统等 | 适配不同设备、统计分析等 | +| 获取窗口信息 | - | 获取窗口尺寸等 | 布局适配、响应式设计等 | + +## 4. 权限申请流程 + +### 4.1 需要单独申请的权限 + +1. 在 `manifest.json` 中配置权限描述 +2. 在代码中调用相关 API 前,先检查是否已授权 +3. 未授权时,调用 `wx.requestAuthorization` 申请权限 +4. 根据用户授权结果执行相应操作 + +### 4.2 不需要单独申请的权限 + +1. 在 `manifest.json` 中配置权限描述 +2. 直接调用相关 API,系统会自动处理授权逻辑 + +## 5. 权限配置示例 + +### 5.1 manifest.json 配置示例 + +```json +"mp-weixin": { + "appid": "wx29215aa1bd97bbd6", + "permission": { + "scope.userLocation": { + "desc": "为了更好地为您提供服务" + }, + "scope.writePhotosAlbum": { + "desc": "为了更好地为您提供服务" + }, + "scope.userClipboard": { + "desc": "为了方便您复制信息" + }, + "scope.record": { + "desc": "用于语音录制功能" + }, + "scope.camera": { + "desc": "用于拍摄照片或视频" + }, + "scope.address": { + "desc": "用于获取您的通讯地址" + }, + "scope.chooseAddress": { + "desc": "用于选择收货地址" + }, + "scope.chooseInvoice": { + "desc": "用于选择发票" + }, + "scope.chooseInvoiceTitle": { + "desc": "用于选择发票抬头" + } + }, + "requiredPrivateInfos": ["chooseLocation", "getLocation", "chooseAddress"] +} +``` + +### 5.2 权限申请代码示例 + +```javascript +// 申请地理位置权限 +wx.getSetting({ + success: (res) => { + if (!res.authSetting['scope.userLocation']) { + wx.requestAuthorization({ + scope: 'scope.userLocation', + success: (authRes) => { + if (authRes.authSetting['scope.userLocation']) { + // 用户授权成功,可以使用地理位置相关功能 + wx.getLocation({ + type: 'wgs84', + success: (locationRes) => { + console.log('获取位置成功', locationRes); + } + }); + } + }, + fail: (err) => { + console.log('授权失败', err); + } + }); + } else { + // 已经授权,可以直接使用 + wx.getLocation({ + type: 'wgs84', + success: (locationRes) => { + console.log('获取位置成功', locationRes); + } + }); + } + } +}); +``` + +## 6. 注意事项和最佳实践 + +### 6.1 注意事项 + +1. **权限申请时机**:在真正需要使用权限时再申请,不要在小程序启动时就申请所有权限 +2. **权限描述**:在 `manifest.json` 中为每个权限提供清晰、准确的描述,说明为什么需要该权限 +3. **用户体验**:在申请权限前,先向用户解释为什么需要该权限,提高授权成功率 +4. **权限拒绝处理**:当用户拒绝授权时,提供合理的降级方案,不要直接阻断用户操作 +5. **隐私政策**:在小程序中提供隐私政策,说明如何使用用户数据 + +### 6.2 最佳实践 + +1. **按需申请**:只申请小程序真正需要的权限 +2. **逐步申请**:根据用户使用流程,逐步申请所需权限 +3. **合理降级**:当权限被拒绝时,提供替代方案 +4. **定期检查**:定期检查权限使用情况,移除不再需要的权限 +5. **权限管理**:在小程序设置中提供权限管理入口,方便用户查看和修改授权状态 + +## 7. 相关 API + +### 7.1 权限相关 API + +- `wx.getSetting`:获取用户当前的授权状态 +- `wx.requestAuthorization`:请求用户授权 +- `wx.openSetting`:打开设置页面,引导用户修改授权状态 + +### 7.2 常用功能 API + +- `wx.getLocation`:获取用户地理位置 +- `wx.chooseAddress`:选择收货地址 +- `wx.chooseInvoice`:选择发票 +- `wx.chooseInvoiceTitle`:选择发票抬头 +- `wx.getRecorderManager`:获取录音管理器 +- `wx.createCameraContext`:创建摄像头上下文 + +## 8. 常见问题 + +### 8.1 权限申请失败 + +- **原因**:用户拒绝授权、系统限制、权限配置错误 +- **解决方法**:检查权限配置、提供合理的权限说明、引导用户在设置中开启权限 + +### 8.2 权限被禁用 + +- **原因**:用户在设置中关闭了权限 +- **解决方法**:使用 `wx.openSetting` 引导用户重新开启权限 + +### 8.3 权限申请弹窗不显示 + +- **原因**:用户之前拒绝过授权且选择了"不再询问" +- **解决方法**:引导用户在设置中开启权限 + +## 9. 总结 + +合理配置和使用微信小程序权限,不仅可以保护用户隐私和数据安全,还能提升用户体验和小程序的可信度。开发者应该根据小程序的实际功能需求,按需申请权限,并为用户提供清晰、透明的权限使用说明。 + +--- + +**更新时间**:2026-01-06 +**适用微信版本**:最新版本 +**参考文档**:[微信小程序官方权限文档](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/authorize.html) \ No newline at end of file diff --git a/manifest.json b/manifest.json index 80879e7..f82b4ad 100644 --- a/manifest.json +++ b/manifest.json @@ -72,6 +72,9 @@ }, "scope.writePhotosAlbum" : { "desc" : "为了更好地为您提供服务" + }, + "scope.userClipboard" : { + "desc" : "为了方便您复制信息" } }, "requiredPrivateInfos" : [ "chooseLocation", "getLocation", "chooseAddress" ],