diff --git a/components-diy/diy-group.vue b/components-diy/diy-group.vue index 41541b4..16eebc3 100644 --- a/components-diy/diy-group.vue +++ b/components-diy/diy-group.vue @@ -251,6 +251,16 @@ + + + + @@ -260,8 +270,8 @@ + + \ No newline at end of file diff --git a/components-diy/diy-wechat-channel.vue b/components-diy/diy-wechat-channel.vue new file mode 100644 index 0000000..b0c856b --- /dev/null +++ b/components-diy/diy-wechat-channel.vue @@ -0,0 +1,231 @@ + + + + + \ No newline at end of file diff --git a/docs/WECHAT_CHANNEL_INTEGRATION.md b/docs/WECHAT_CHANNEL_INTEGRATION.md new file mode 100644 index 0000000..dfd987e --- /dev/null +++ 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 + +``` + +#### 属性说明 + +| 属性名 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| 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 + +``` + +#### 属性说明 + +| 属性名 | 类型 | 默认值 | 说明 | +|--------|------|--------|------| +| 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 中使用时,需要用 `` 包裹以确保组件正确显示 + +```vue + + + + + +``` + +### 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中使用原生组件时,可能会遇到组件不显示的问题。以下是已验证的解决方案: + +#### 解决方案 + +**方法一:使用 `` 包裹** + +在 UniApp 中使用 `channel-video` 组件时,必须用 `` 包裹以确保组件正确显示: + +``` vue + +``` + +**方法二:检查 `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项目中轻松集成微信视频号功能,为用户提供更加丰富的内容体验。 + +如果在集成过程中遇到问题,请参考本文档的常见问题部分,或查阅微信官方文档获取更多帮助。 \ No newline at end of file diff --git a/docs/example/wechat-channel-demo.vue b/docs/example/wechat-channel-demo.vue new file mode 100644 index 0000000..045beba --- /dev/null +++ b/docs/example/wechat-channel-demo.vue @@ -0,0 +1,165 @@ + + + + + \ No newline at end of file