chore(视频号组件): 更新文档及注释内容

2026-01-10 17:38:13 +08:00
parent 13166132c7
commit 68bc853dff
3 changed files with 417 additions and 68 deletions
--- a/docs/WECHAT_CHANNEL_INTEGRATION.md
+++ b/docs/WECHAT_CHANNEL_INTEGRATION.md
@@ -102,12 +102,73 @@

 ## 3. 组件使用

-### 3.1 单个视频号组件 (diy-wechat-channel.vue)
+### 3.1 视频号头部组件 (diy-channel-header.vue)

 #### 基本用法

 ```vue
-<diy-wechat-channel :value="channelData" />
+<diy-channel-header :value="headerData" @header-tap="handlerHeaderClick" />
+```
+
+#### 属性说明
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| channelName | String | "" | 视频号名称 |
+| avatarUrl | String | "" | 视频号头像URL |
+| showFollow | Boolean | false | 是否显示关注按钮 |
+
+#### 事件说明
+
+| 事件名 | 说明 | 参数 |
+|--------|------|------|
+| header-tap | 点击头部区域时触发 | 视频号数据对象 |
+
+### 3.2 视频号视频卡片组件 (diy-channel-video.vue)
+
+#### 基本用法
+
+```vue
+<diy-channel-video :value="videoData" @video-play="handlerVideoPlay" />
+```
+
+#### 属性说明
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| value | Object | {} | 视频数据对象 |
+| listMode | Boolean | false | 是否为列表模式 |
+| videoHeight | Number | 220 | 视频高度（仅适用于嵌入式播放） |
+| titleLineClamp | Number | 1 | 标题显示行数 |
+| showPlayBtn | Boolean | true | 是否显示播放按钮 |
+| coverStyle | Object | {} | 视频封面图样式 |
+| playBtnStyle | Object | {} | 播放按钮样式 |
+
+#### value对象属性说明
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| feedId | String | "" | 视频 feedId |
+| finderUserName | String | "" | 视频号用户名 |
+| feedToken | String | "" | 视频 token |
+| coverUrl | String | "" | 视频封面图 |
+| videoTitle | String | "" | 视频标题 |
+| viewCount | Number | 0 | 观看次数 |
+| showViewCount | Boolean | false | 是否显示观看次数 |
+| embedMode | Boolean | false | 是否启用嵌入式播放 |
+
+#### 事件说明
+
+| 事件名 | 说明 | 参数 |
+|--------|------|------|
+| video-play | 点击视频播放时触发 | 视频数据对象 |
+
+### 3.3 单个视频号组件 (diy-channel.vue)
+
+#### 基本用法
+
+```vue
+<diy-channel :value="channelData" />
 ```

 #### 属性说明
@@ -124,6 +185,14 @@
 | componentAngle | String | "" | 组件圆角类型，可选值：round |
 | topAroundRadius | Number | 0 | 顶部圆角半径 |
 | bottomAroundRadius | Number | 0 | 底部圆角半径 |
+| embedMode | Boolean | false | 是否启用嵌入式播放 |
+| showViewCount | Boolean | false | 是否显示观看次数 |
+| finderUserName | String | "" | 视频号ID，用于嵌入式播放 |
+| feedToken | String | "" | 视频token，用于嵌入式播放 |
+| titleLineClamp | Number | 1 | 标题显示行数 |
+| showPlayBtn | Boolean | true | 是否显示播放按钮 |
+| coverStyle | Object | {} | 视频封面图样式 |
+| playBtnStyle | Object | {} | 播放按钮样式 |

 #### 事件说明

@@ -132,12 +201,12 @@
 | channel-tap | 点击视频号头像或名称时触发 | 视频号数据对象 |
 | video-play | 点击视频播放时触发 | 视频号数据对象 |

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

 #### 基本用法

 ```vue
-<diy-wechat-channel-list :value="channelListData" />
+<diy-channel-list :value="channelListData" />
 ```

 #### 属性说明
@@ -154,6 +223,18 @@
 | topAroundRadius | Number | 0 | 顶部圆角半径 |
 | bottomAroundRadius | Number | 0 | 底部圆角半径 |
 | ornament | Object | {} | 装饰样式配置 |
+| titleLineClamp | Number | 1 | 标题显示行数 |
+| showPlayBtn | Boolean | true | 是否显示播放按钮 |
+| coverStyle | Object | {} | 视频封面图样式 |
+| playBtnStyle | Object | {} | 播放按钮样式 |
+| imageSize | Number | 0 | 图片尺寸（仅在特定模式下使用） |
+| pageCount | Number | 1 | 每页显示的视频数量 |
+| carousel | Object | {} | 轮播配置 |
+| carousel.type | String | "" | 轮播类型，可选值：default, hide |
+| carousel.autoplay | Boolean | false | 是否自动播放 |
+| carousel.interval | Number | 3000 | 自动播放间隔，单位毫秒 |
+| carousel.duration | Number | 500 | 切换动画时长，单位毫秒 |
+| carousel.circular | Boolean | false | 是否循环播放 |

 #### list数组项说明

@@ -164,6 +245,10 @@
 | videoTitle | String | "" | 视频标题 |
 | feedId | String | "" | 视频号内容ID，用于播放视频 |
 | viewCount | Number | 0 | 视频观看次数 |
+| embedMode | Boolean | false | 是否启用嵌入式播放 |
+| showViewCount | Boolean | false | 是否显示观看次数 |
+| finderUserName | String | "" | 视频号ID，用于嵌入式播放 |
+| feedToken | String | "" | 视频token，用于嵌入式播放 |

 ## 4. 视频播放实现

@@ -290,7 +375,19 @@ if (typeof wx !== 'undefined' && wx.openChannelsActivity) {
  - 头像：200x200px
  - 封面：640x360px

-### 5.4 权限和关联
+### 5.4 播放按钮图标
+
+- 组件支持两种播放按钮图标方式：
+  1. **图片图标**：通过 `playIcon` 属性设置，优先级较高
+  2. **纯 CSS 图标**：当 `playIcon` 不可用时，组件会自动使用纯 CSS 生成的播放图标，确保播放按钮始终可见
+
+- 纯 CSS 图标特点：
+  - 不依赖外部图片资源，加载更快
+  - 支持响应式调整大小
+  - 具有与图片图标相同的悬停效果
+  - 在所有环境中都能正常显示
+
+### 5.5 权限和关联

 - 确保在微信小程序后台开通了「打开视频号内容」权限
 - 确保小程序已与视频号成功关联
@@ -392,25 +489,82 @@ if (typeof wx !== 'undefined' && wx.openChannelsActivity) {

 ## 7. 示例代码

-### 7.1 单个视频号示例
+### 7.1 视频号头部组件示例
+
+```javascript
+// 视频号头部数据
+const headerData = {
+    channelName: "示例视频号",
+    avatarUrl: "https://example.com/avatar.jpg",
+    showFollow: true
+};
+
+// 头部点击事件处理
+function handlerHeaderClick(data) {
+    console.log("头部被点击", data);
+    // 可以在这里处理跳转到视频号主页等逻辑
+}
+```
+
+### 7.2 视频号视频卡片组件示例
+
+```javascript
+// 视频卡片数据
+const videoData = {
+    channelName: "示例视频号",
+    coverUrl: "https://example.com/cover.jpg",
+    videoTitle: "这是一个示例视频，标题可能会很长，需要测试多行显示效果",
+    feedId: "v02004g10000c3f7l7j5u87l33n8f160",
+    viewCount: 12345,
+    embedMode: false,
+    showViewCount: true,
+    finderUserName: "example_finder",
+    feedToken: "example_feed_token"
+};
+
+// 视频播放事件处理
+function handlerVideoPlay(data) {
+    console.log("视频播放", data);
+    // 可以在这里处理视频播放逻辑
+}
+```
+
+### 7.3 单个视频号示例

 ```javascript
 // 单个视频号数据
 const channelData = {
    channelName: "示例视频号",
    avatarUrl: "https://example.com/avatar.jpg",
-    videoTitle: "这是一个示例视频",
+    videoTitle: "这是一个示例视频，标题可能会很长，需要测试多行显示效果",
    coverUrl: "https://example.com/cover.jpg",
    feedId: "v02004g10000c3f7l7j5u87l33n8f160",
    viewCount: 12345,
    showFollow: true,
    componentAngle: "round",
    topAroundRadius: 10,
-    bottomAroundRadius: 10
+    bottomAroundRadius: 10,
+    embedMode: false,
+    showViewCount: true,
+    finderUserName: "example_finder",
+    feedToken: "example_feed_token",
+    titleLineClamp: 2,
+    showPlayBtn: true,
+    coverStyle: {
+        width: "100%",
+        height: "0",
+        paddingTop: "56.25%" // 16:9 比例
+    },
+    playBtnStyle: {
+        width: "60rpx",
+        height: "60rpx",
+        borderRadius: "30rpx",
+        backgroundColor: "rgba(0, 0, 0, 0.6)"
+    }
 };
 ```

-### 7.2 视频号列表示例
+### 7.4 视频号列表示例

 ```javascript
 // 视频号列表数据
@@ -419,20 +573,29 @@ const channelListData = {
        {
            channelName: "示例视频号1",
            coverUrl: "https://example.com/cover1.jpg",
-            videoTitle: "这是示例视频1",
+            videoTitle: "这是示例视频1，标题可能会很长，需要测试多行显示效果",
            feedId: "v02004g10000c3f7l7j5u87l33n8f160",
-            viewCount: 12345
+            viewCount: 12345,
+            embedMode: false,
+            showViewCount: true,
+            finderUserName: "example_finder1",
+            feedToken: "example_feed_token1"
        },
        {
            channelName: "示例视频号2",
            coverUrl: "https://example.com/cover2.jpg",
-            videoTitle: "这是示例视频2",
+            videoTitle: "这是示例视频2，标题可能会很长，需要测试多行显示效果",
            feedId: "v02004g10000c3f7m7j5u87l33n8f161",
-            viewCount: 67890
+            viewCount: 67890,
+            embedMode: false,
+            showViewCount: true,
+            finderUserName: "example_finder2",
+            feedToken: "example_feed_token2"
        }
    ],
    rowCount: 2,
    showStyle: "fixed",
+    mode: "",
    font: {
        size: 14,
        weight: "normal",
@@ -441,7 +604,30 @@ const channelListData = {
    componentBgColor: "#fff",
    componentAngle: "round",
    topAroundRadius: 10,
-    bottomAroundRadius: 10
+    bottomAroundRadius: 10,
+    ornament: {},
+    titleLineClamp: 2,
+    showPlayBtn: true,
+    coverStyle: {
+        width: "100%",
+        height: "0",
+        paddingTop: "56.25%" // 16:9 比例
+    },
+    playBtnStyle: {
+        width: "60rpx",
+        height: "60rpx",
+        borderRadius: "30rpx",
+        backgroundColor: "rgba(0, 0, 0, 0.6)"
+    },
+    imageSize: 150,
+    pageCount: 1,
+    carousel: {
+        type: "default",
+        autoplay: true,
+        interval: 3000,
+        duration: 500,
+        circular: true
+    }
 };
 ```