Uniapp/lucky_shop

Fork 0

Files

ZF sun 7fde30063b chore(微信视频号): 优化channel-video组件的显示，更新技术文档

2026-01-07 17:27:42 +08:00

16 KiB

Raw Permalink Blame History

微信视频号集成指南

1. 概述

本文档提供了在UniApp项目中集成微信视频号的详细指导，包括组件实现、配置修改和使用方法。

2. 准备工作

2.1 微信小程序配置

在 manifest.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 以下），则需要关联小程序与视频号：

小程序管理员操作
- 登录微信小程序后台
- 左侧菜单：设置 → 基本设置
- 向下滚动找到「关联设置」部分
- 点击「关联视频号」按钮
- 输入视频号名称或视频号ID
- 点击「搜索」找到对应的视频号
- 点击「发送关联邀请」
视频号管理员操作
- 视频号管理员需要在24小时内确认关联邀请
- 视频号管理员登录视频号助手
- 进入「设置」→「关联设置」→「小程序关联」
- 找到待确认的关联邀请
- 点击「同意」完成关联
关联失败处理
- 检查视频号是否已完成实名认证
- 检查小程序是否已发布上线
- 检查视频号名称或ID是否输入正确
- 如超过24小时未确认，需要重新发送关联邀请

2.2.3 关联条件

小程序要求：必须已经发布上线，未被处罚或限制
视频号要求：必须已经完成实名认证，状态正常
数量限制：同一个小程序最多可以关联50个视频号，同一个视频号最多可以关联50个小程序
权限要求：关联操作需要小程序管理员和视频号管理员共同确认
主体要求：小程序和视频号的主体可以不同，但需要双方管理员确认

2.2.4 功能验证

可以通过以下方式验证视频号功能是否可用：

在微信开发者工具中验证
- 在微信开发者工具中打开小程序
- 在控制台执行以下代码：
```
console.log('是否支持视频号API:', typeof wx !== 'undefined' && typeof wx.openChannelsActivity === 'function');
```
- 如果返回 true，则表示API可用
在真机环境中验证
- 使用微信扫码打开小程序
- 触发视频号相关功能
- 检查是否能正常打开视频号内容
功能验证失败处理
- 检查微信小程序基础库版本是否满足要求（跳转打开需要 2.19.2+，内嵌打开需要 2.25.1+）
- 对于内嵌打开，检查主体是否满足要求或是否已关联
- 检查 feedId 等参数是否正确

3. 组件使用

3.1 单个视频号组件 (diy-wechat-channel.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)

基本用法

<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 来打开视频号内容：

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> 包裹以确保组件正确显示

<!-- #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 获取参数方法

获取finderUserName（视频号ID）
- 登录视频号助手
- 在首页可以查看自己的视频号ID
获取feedId（视频号内容ID）
- 登录视频号助手
- 在「动态管理」模块可以复制自己发表的每个视频对应的feedId
获取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> 包裹以确保组件正确显示：

<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 部分：

"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 单个视频号示例

// 单个视频号数据
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 视频号列表示例

// 视频号列表数据
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项目中轻松集成微信视频号功能，为用户提供更加丰富的内容体验。

如果在集成过程中遇到问题，请参考本文档的常见问题部分，或查阅微信官方文档获取更多帮助。

16 KiB Raw Permalink Blame History Unescape Escape

微信视频号集成指南

1. 概述

2. 准备工作

2.1 微信小程序配置

2.2 微信视频号API权限与关联

2.2.1 权限说明

2.2.2 小程序与视频号关联（可选）

2.2.3 关联条件

2.2.4 功能验证

3. 组件使用

3.1 单个视频号组件 (diy-wechat-channel.vue)

基本用法

属性说明

事件说明

3.2 视频号列表组件 (diy-wechat-channel-list.vue)

基本用法

属性说明

list数组项说明

4. 视频播放实现

4.1 跳转打开视频号视频

4.2 内嵌视频号视频

4.3 API参数说明

4.4 错误码说明

4.5 获取参数方法

4.6 主体判断逻辑

主体信息查询

主体判断逻辑

5. 注意事项

5.1 环境限制

5.2 数据格式

5.3 图片资源

5.4 权限和关联

6. 常见问题

6.1 视频无法播放

6.2 功能不可用

6.3 关联失败

6.4 组件显示异常

6.5 样式问题

6.6 环境兼容性问题

6.7 在uni-app中使用原生组件时，可能会遇到组件不显示的问题

解决方案

7. 示例代码

7.1 单个视频号示例

7.2 视频号列表示例

8. 总结

16 KiB

Raw Permalink Blame History