Merge branch 'dev/1.0' into custom/common

2026-01-08 15:10:46 +08:00
parent aa2f13f3b2
commit 23c954981b
92 changed files with 1975 additions and 382 deletions
--- a/docs/WECHAT_CHANNEL_INTEGRATION.md
+++ b/docs/WECHAT_CHANNEL_INTEGRATION.md
@@ -0,0 +1,452 @@
+# 微信视频号集成指南
+
+## 1. 概述
+
+本文档提供了在UniApp项目中集成微信视频号的详细指导，包括组件实现、配置修改和使用方法。
+
+## 2. 准备工作
+
+### 2.1 微信小程序配置
+
+在 `manifest.json` 文件中，需要确保微信小程序配置正确：
+
+```json
+"mp-weixin": {
+    "appid": "你的小程序appid",
+    "setting": {
+        "urlCheck": false,
+        "postcss": false,
+        "es6": true,
+        "minified": true
+    },
+    "usingComponents": true,
+    "permission": {
+        "scope.userLocation": {
+            "desc": "为了更好地为您提供服务"
+        }
+    },
+    "requiredPrivateInfos": ["chooseLocation", "getLocation", "chooseAddress"],
+    "__usePrivacyCheck__": true,
+    "optimization": {
+        "subPackages": true
+    }
+}
+```
+
+### 2.2 微信视频号API权限与关联
+
+#### 2.2.1 权限说明
+
+`wx.openChannelsActivity` API 是小程序的基础能力，不需要单独开通权限，但需要满足以下条件：
+
+- **跳转打开视频号视频**：无主体限制，基础库版本 2.19.2 及以上
+- **内嵌视频号视频**：
+  - 从基础库版本 2.25.1 至 2.31.1，小程序需与视频号视频相同主体或关联主体
+  - 从基础库版本 2.31.1 开始，非个人主体小程序可内嵌非同主体/关联主体视频号视频
+
+#### 2.2.2 小程序与视频号关联（可选）
+
+虽然跳转打开视频号视频无主体限制，但如果需要内嵌非同主体视频号视频（基础库 2.31.1 以下），则需要关联小程序与视频号：
+
+1. **小程序管理员操作**
+   - 登录微信小程序后台
+   - 左侧菜单：设置 → 基本设置
+   - 向下滚动找到「关联设置」部分
+   - 点击「关联视频号」按钮
+   - 输入视频号名称或视频号ID
+   - 点击「搜索」找到对应的视频号
+   - 点击「发送关联邀请」
+
+2. **视频号管理员操作**
+   - 视频号管理员需要在24小时内确认关联邀请
+   - 视频号管理员登录 [视频号助手](https://channels.weixin.qq.com/)
+   - 进入「设置」→「关联设置」→「小程序关联」
+   - 找到待确认的关联邀请
+   - 点击「同意」完成关联
+
+3. **关联失败处理**
+   - 检查视频号是否已完成实名认证
+   - 检查小程序是否已发布上线
+   - 检查视频号名称或ID是否输入正确
+   - 如超过24小时未确认，需要重新发送关联邀请
+
+#### 2.2.3 关联条件
+
+- **小程序要求**：必须已经发布上线，未被处罚或限制
+- **视频号要求**：必须已经完成实名认证，状态正常
+- **数量限制**：同一个小程序最多可以关联50个视频号，同一个视频号最多可以关联50个小程序
+- **权限要求**：关联操作需要小程序管理员和视频号管理员共同确认
+- **主体要求**：小程序和视频号的主体可以不同，但需要双方管理员确认
+
+#### 2.2.4 功能验证
+
+可以通过以下方式验证视频号功能是否可用：
+
+1. **在微信开发者工具中验证**
+   - 在微信开发者工具中打开小程序
+   - 在控制台执行以下代码：
+     ```javascript
+     console.log('是否支持视频号API:', typeof wx !== 'undefined' && typeof wx.openChannelsActivity === 'function');
+     ```
+   - 如果返回 `true`，则表示API可用
+
+2. **在真机环境中验证**
+   - 使用微信扫码打开小程序
+   - 触发视频号相关功能
+   - 检查是否能正常打开视频号内容
+
+3. **功能验证失败处理**
+   - 检查微信小程序基础库版本是否满足要求（跳转打开需要 2.19.2+，内嵌打开需要 2.25.1+）
+   - 对于内嵌打开，检查主体是否满足要求或是否已关联
+   - 检查 `feedId` 等参数是否正确
+
+## 3. 组件使用
+
+### 3.1 单个视频号组件 (diy-wechat-channel.vue)
+
+#### 基本用法
+
+```vue
+<diy-wechat-channel :value="channelData" />
+```
+
+#### 属性说明
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| channelName | String | "" | 视频号名称 |
+| avatarUrl | String | "" | 视频号头像URL |
+| videoTitle | String | "" | 视频标题 |
+| coverUrl | String | "" | 视频封面URL |
+| feedId | String | "" | 视频号内容ID，用于播放视频 |
+| viewCount | Number | 0 | 视频观看次数 |
+| showFollow | Boolean | false | 是否显示关注按钮 |
+| componentAngle | String | "" | 组件圆角类型，可选值：round |
+| topAroundRadius | Number | 0 | 顶部圆角半径 |
+| bottomAroundRadius | Number | 0 | 底部圆角半径 |
+
+#### 事件说明
+
+| 事件名 | 说明 | 参数 |
+|--------|------|------|
+| channel-tap | 点击视频号头像或名称时触发 | 视频号数据对象 |
+| video-play | 点击视频播放时触发 | 视频号数据对象 |
+
+### 3.2 视频号列表组件 (diy-wechat-channel-list.vue)
+
+#### 基本用法
+
+```vue
+<diy-wechat-channel-list :value="channelListData" />
+```
+
+#### 属性说明
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| list | Array | [] | 视频号列表数据 |
+| rowCount | Number | 2 | 每行显示的视频号数量 |
+| showStyle | String | "fixed" | 显示样式，可选值：fixed, singleSlide |
+| mode | String | "" | 显示模式 |
+| font | Object | {} | 字体样式配置 |
+| componentBgColor | String | "#fff" | 组件背景颜色 |
+| componentAngle | String | "" | 组件圆角类型，可选值：round |
+| topAroundRadius | Number | 0 | 顶部圆角半径 |
+| bottomAroundRadius | Number | 0 | 底部圆角半径 |
+| ornament | Object | {} | 装饰样式配置 |
+
+#### list数组项说明
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| channelName | String | "" | 视频号名称 |
+| coverUrl | String | "" | 视频封面URL |
+| videoTitle | String | "" | 视频标题 |
+| feedId | String | "" | 视频号内容ID，用于播放视频 |
+| viewCount | Number | 0 | 视频观看次数 |
+
+## 4. 视频播放实现
+
+小程序提供两种打开视频号视频的方式：跳转打开和内嵌打开。
+
+### 4.1 跳转打开视频号视频
+
+组件内部使用微信小程序的 `wx.openChannelsActivity` API 来打开视频号内容：
+
+```javascript
+if (typeof wx !== 'undefined' && wx.openChannelsActivity) {
+    wx.openChannelsActivity({
+        feedId: item.feedId, // 视频号内容ID，必填
+        finderUserName: item.finderUserName, // 视频号ID（可选）
+        success: (res) => {
+            console.log('打开视频号成功', res);
+        },
+        fail: (err) => {
+            console.error('打开视频号失败', err);
+            // 常见错误处理
+            if (err.errCode === 40001) {
+                console.error('未授权，请检查小程序是否与视频号关联');
+            } else if (err.errCode === 40002) {
+                console.error('参数错误，请检查feedId是否正确');
+            } else if (err.errCode === 40003) {
+                console.error('视频号内容不存在或已被删除');
+            }
+        }
+    });
+} else {
+    console.error('当前环境不支持微信视频号');
+}
+```
+
+### 4.2 内嵌视频号视频
+
+从基础库 2.25.1 开始支持，小程序可以通过 `channel-video` 组件在小程序中内嵌视频号视频，且支持无弹窗跳转打开视频号对应视频，使用该组件时需注意：
+
+- 组件调用无资质要求
+- 暂不支持纯图片视频号内容
+- 在 UniApp 中使用时，需要用 `<native-component>` 包裹以确保组件正确显示
+
+```vue
+<!-- #ifdef MP-WEIXIN -->
+<native-component>
+  <channel-video
+    feed-id="{{feedId}}"
+    finder-user-name="{{finderUserName}}"
+    feed-token="{{feedToken}}"
+    bindenterfullscreen="enterFullscreen"
+    bindexitfullscreen="exitFullscreen"
+    binderror="videoError"
+  ></channel-video>
+</native-component>
+<!-- #endif -->
+```
+
+### 4.3 API参数说明
+
+- **feedId**：视频号内容ID，必填，必须是有效的视频号内容ID
+- **finderUserName**：视频号ID，可选
+- **feedToken**：非同主体视频号视频的标识，从基础库 2.31.1 开始支持，非个人主体小程序可使用
+- **success**：调用成功的回调函数
+- **fail**：调用失败的回调函数
+- **complete**：调用完成的回调函数（无论成功或失败）
+
+### 4.4 错误码说明
+
+| 错误码 | 说明 | 解决方案 |
+|--------|------|----------|
+| 40001 | 未授权 | 对于内嵌打开，检查主体是否满足要求或是否已关联 |
+| 40002 | 参数错误 | 检查feedId是否正确，确保是有效的视频号内容ID |
+| 40003 | 视频号内容不存在或已被删除 | 确认feedId对应的视频号内容是否仍然存在 |
+| 40004 | 系统错误 | 稍后重试，或联系微信公众平台客服 |
+
+### 4.5 获取参数方法
+
+1. **获取finderUserName（视频号ID）**
+   - 登录视频号助手
+   - 在首页可以查看自己的视频号ID
+
+2. **获取feedId（视频号内容ID）**
+   - 登录视频号助手
+   - 在「动态管理」模块可以复制自己发表的每个视频对应的feedId
+
+3. **获取feed-token（非同主体视频号视频标识）**
+   - 登录MP平台，在「设置-基本设置-隐私与安全」找到「获取视频号视频ID权限」，并将开关打开
+   - 移动端找到想要内嵌的视频号视频，并复制该视频的feed-token
+   - 注意：打开开关后24小时内生效，失效后需要再次打开开关；开关打开状态仅对当前操作者生效
+
+### 4.6 主体判断逻辑
+
+#### 主体信息查询
+小程序主体信息可通过小程序资料页-开发团队进行查询，视频号主体信息可通过视频号首页-认证进行查询。
+
+#### 主体判断逻辑
+- **跳转打开视频号视频**：无主体限制，基础库版本 2.19.2 及以上
+- **内嵌视频号视频**：
+  - 从基础库版本 2.25.1 至 2.31.1，小程序需与视频号视频相同主体或关联主体
+  - 从基础库版本 2.31.1 开始，非个人主体小程序可内嵌非同主体/关联主体视频号视频
+
+关联主体申请流程可以参考：https://kf.qq.com/faq/190726e6JFja190726qMJBn6.html
+
+
+
+## 5. 注意事项
+
+### 5.1 环境限制
+
+- 微信视频号API只能在微信小程序环境中使用，其他环境（如H5、App）不支持
+- 跳转打开视频号视频需要微信小程序基础库版本 2.19.2 及以上
+- 内嵌视频号视频需要微信小程序基础库版本 2.25.1 及以上
+- 小程序与视频号关联仅在需要内嵌非同主体视频号视频（基础库 2.31.1 以下）时需要
+- 必须确保在 `manifest.json` 中设置 `usingComponents: true` 以启用组件支持
+
+### 5.2 数据格式
+
+确保传递给组件的数据格式正确，特别是 `feedId` 必须是有效的视频号内容ID
+
+### 5.3 图片资源
+
+- 视频号头像和封面图片建议使用CDN地址，确保加载速度
+- 图片尺寸建议：
+  - 头像：200x200px
+  - 封面：640x360px
+
+### 5.4 权限和关联
+
+- 确保在微信小程序后台开通了「打开视频号内容」权限
+- 确保小程序已与视频号成功关联
+- 关联操作需要小程序管理员和视频号管理员共同确认
+
+## 6. 常见问题
+
+### 6.1 视频无法播放
+
+- 检查 `feedId` 是否正确，确保是有效的视频号内容ID
+- 检查微信小程序基础库版本是否满足要求（跳转打开需要 2.19.2+，内嵌打开需要 2.25.1+）
+- 对于内嵌打开，检查主体是否满足要求（基础库 2.31.1 以下需要相同主体或关联主体）
+- 检查视频号内容是否仍然存在（未被删除）
+
+### 6.2 功能不可用
+
+- 确认当前环境是否为微信小程序环境
+- 检查微信小程序基础库版本是否满足要求
+- 对于内嵌打开，检查主体条件是否满足
+- 检查 `feedId` 等参数是否正确
+
+### 6.3 关联失败
+
+- 检查视频号是否已完成实名认证
+- 检查小程序是否已发布上线
+- 检查视频号名称或ID是否输入正确
+- 确认视频号管理员是否在24小时内确认关联邀请
+- 如超过24小时未确认，需要重新发送关联邀请
+
+### 6.4 组件显示异常
+
+- 检查传递给组件的数据格式是否正确
+- 确认图片资源是否可访问
+- 检查微信小程序基础库版本是否支持视频号API
+
+### 6.5 样式问题
+
+- 可通过组件的 `componentAngle`、`topAroundRadius`、`bottomAroundRadius` 等属性调整组件样式
+- 可通过 `componentBgColor` 属性调整组件背景颜色
+- 可通过 `font` 属性调整字体样式
+
+### 6.6 环境兼容性问题
+
+- 微信视频号API只能在微信小程序环境中使用
+- 在其他环境中，组件会显示但无法播放视频
+- 建议在非小程序环境中添加友好的提示信息
+
+### 6.7 在uni-app中使用原生组件时，可能会遇到组件不显示的问题
+
+在uni-app中使用原生组件时，可能会遇到组件不显示的问题。以下是已验证的解决方案：
+
+#### 解决方案
+
+**方法一：使用 `<native-component>` 包裹**
+
+在 UniApp 中使用 `channel-video` 组件时，必须用 `<native-component>` 包裹以确保组件正确显示：
+
+``` vue
+<template>
+  <view>
+    <!-- #ifdef MP-WEIXIN -->
+    <native-component>
+      <channel-video 
+        feed-id="{{feedId}}" 
+        finder-user-name="{{finderUserName}}" 
+        feed-token="{{feedToken}}"
+        style="width: 100%; height: 320rpx;"
+      ></channel-video>
+    </native-component>
+    <!-- #endif -->
+  </view>
+</template>
+```
+
+**方法二：检查 `manifest.json` 配置**
+
+确保在 `manifest.json` 文件中正确设置了 `usingComponents: true`，特别是在 `mp-weixin` 部分：
+
+``` json
+"mp-weixin": {
+  "appid": "你的小程序appid",
+  "usingComponents": true,
+  // 其他配置...
+}
+```
+
+**方法三：检查微信小程序基础库版本**
+
+确保微信小程序基础库版本满足要求：
+- 跳转打开视频号视频需要基础库版本 2.19.2 及以上
+- 内嵌视频号视频需要基础库版本 2.25.1 及以上
+
+**方法四：检查参数是否正确**
+
+确保传递给 `channel-video` 组件的参数正确：
+- `feedId`：视频号内容ID，必填
+- `finderUserName`：视频号ID，可选
+- `feedToken`：非同主体视频号视频的标识，可选（基础库 2.31.1+）
+
+## 7. 示例代码
+
+### 7.1 单个视频号示例
+
+```javascript
+// 单个视频号数据
+const channelData = {
+    channelName: "示例视频号",
+    avatarUrl: "https://example.com/avatar.jpg",
+    videoTitle: "这是一个示例视频",
+    coverUrl: "https://example.com/cover.jpg",
+    feedId: "v02004g10000c3f7l7j5u87l33n8f160",
+    viewCount: 12345,
+    showFollow: true,
+    componentAngle: "round",
+    topAroundRadius: 10,
+    bottomAroundRadius: 10
+};
+```
+
+### 7.2 视频号列表示例
+
+```javascript
+// 视频号列表数据
+const channelListData = {
+    list: [
+        {
+            channelName: "示例视频号1",
+            coverUrl: "https://example.com/cover1.jpg",
+            videoTitle: "这是示例视频1",
+            feedId: "v02004g10000c3f7l7j5u87l33n8f160",
+            viewCount: 12345
+        },
+        {
+            channelName: "示例视频号2",
+            coverUrl: "https://example.com/cover2.jpg",
+            videoTitle: "这是示例视频2",
+            feedId: "v02004g10000c3f7m7j5u87l33n8f161",
+            viewCount: 67890
+        }
+    ],
+    rowCount: 2,
+    showStyle: "fixed",
+    font: {
+        size: 14,
+        weight: "normal",
+        color: "#333"
+    },
+    componentBgColor: "#fff",
+    componentAngle: "round",
+    topAroundRadius: 10,
+    bottomAroundRadius: 10
+};
+```
+
+## 8. 总结
+
+通过本文档提供的组件和配置指导，你可以在UniApp项目中轻松集成微信视频号功能，为用户提供更加丰富的内容体验。
+
+如果在集成过程中遇到问题，请参考本文档的常见问题部分，或查阅微信官方文档获取更多帮助。