更新记录

1.0.0（2026-08-26）

新版本发布

1.0.0（2026-08-26）

平台兼容性

uni-app(3.8.2)

su-video-stream 圆角流媒体视频播放器

基于 renderjs + HTML5 video 的自定义圆角视频组件。App 端远程 MP4 直链边下边播（HTTP Range），无需整文件下载；内置播放/暂停、进度、倍速、全屏、3 秒隐藏控件、选集连播。

适合教育、短剧、课程详情、跟读学习等需要自定义控制条的场景。uni-app 原生 <video> 在 App WebView 上圆角、控件、连播都不易做细，本组件专门解决这些问题。

使用方法（完整示例）见同目录 usage.md。 下文也有快速接入说明。

使用方法

1. 安装

从插件市场导入到项目后，目录为：

uni_modules/su-video-stream

无需改 pages.json，符合 easycom，页面里直接写标签。

2. 最简代码

<template>
  <su-round-video-stream
    v-if="src"
    uid="demo"
    :src="src"
    :poster="poster"
    :width="413"
    :height="233"
    :border-radius="16"
    @ended=""
  ></su-round-video-stream>
</template>

<script setup>
  import { ref } from 'vue';

  const src = ref('https://example.com/video.mp4');
  const poster = ref('https://example.com/cover.jpg');

  function () {
    console.log('播放结束');
  }
</script>

3. 主动播放 / 暂停 / 跳转

<su-round-video-stream ref="videoRef" uid="demo" :src="src"></su-round-video-stream>

const videoRef = ref(null);

videoRef.value.play();
videoRef.value.pause();
videoRef.value.stop();
videoRef.value.seek(10);
const info = videoRef.value.getPlaybackInfo(); // { currentTime, duration, playing }

连播、跟读、多实例、大文件自动播等完整示例见 usage.md。

插件优势

1. 流媒体起播更快
   App 端不先 downloadFile 整包，远程 MP4 直接交给 HTML5 video 边下边播，长视频首帧更快。

2. 完整自定义控制条
   播放/暂停、进度拖动、时长、倍速（0.5x～2x）、全屏。可隐藏原生 controls，避免系统大播放按钮。

3. App / H5 一套 UI
   App 端控件在 renderjs 内绘制；H5 用 vue 层控件。对外 props / 事件 / ref 方法一致。

4. 3 秒无操作自动隐藏控件
   点击视频任意区域重新显示，更接近系统播放器体验。

5. 连播能力
   传入 episode-config，App 端在 renderjs 内切下一集，减少逻辑层卡顿。

6. 跟读友好
   支持 muted、@timeupdate、getPlaybackInfo()，方便跟读区间弹窗、静音配音。

7. 圆角裁剪可靠
   用容器 overflow + HTML5 video 实现圆角，避免 App 原生 video 圆角失效。

8. 命令式控制
   ref.play() / pause() / stop() / seek(time)，方便页面与录音、发音互斥。

9. 同页多实例
   通过 uid 隔离 DOM id，一页可放多个播放器。

10. 即插即用
    符合 easycom，导入 uni_modules 后直接写 <su-round-video-stream>。

支持的平台

运行条件：

• uni-app Vue3
• 仅 vue 页面（非 nvue）
• App 端建议真机或自定义基座调试 renderjs
• 远程视频建议 MP4，CDN 支持 HTTP Range，推荐 faststart（moov 在文件头）

Props

episodeConfig 连播

{
  isLooping: true,      // 是否连播下一集
  isDescending: false,
  currentIndex: 0,
  total: 10,
  nextIndex: 1,
  nextSrc: 'https://xxx/ep2.mp4',
  nextPoster: 'https://xxx/ep2.jpg',
}

isLooping: true 且提供 nextSrc 时，当前集结束后 App 端会在 renderjs 内切源并触发 @episodeswitch。

事件

ref 方法

videoRef.value.play();
videoRef.value.pause();
videoRef.value.seek(12);
const info = videoRef.value.getPlaybackInfo();

插槽

overlay（或默认插槽）：盖在视频上的自定义层，pointer-events: none，不拦截点击。

<su-round-video-stream :src="src" uid="1">
  <view>字幕或角标</view>
</su-round-video-stream>

典型场景

1. 课程 / 动画详情

设 src、poster、width/height，听 @ended 提示下一集；连播用 episode-config。

2. 跟读 / 配音

:muted="true" 切无声；@timeupdate 对比跟读起止秒数弹录音。

3. 大文件场景视频（约数 MB 以上）

:autoplay="true" 且 :quick-autoplay="true"，在 canplay 即起播，缩短「加载中」等待。

注意事项

1. 同页多个播放器必须传不同 uid，否则 host DOM id 冲突。
2. 仅 vue 页；App 调试请用真机 / 自定义基座，HBuilder 内置基座对 renderjs 支持不完整。
3. 容器 CSS 高度与 height 对齐，减少黑边。
4. 流式播放依赖 CDN Range 与 MP4 faststart；若听感丢开头（只剩后半段），可改回「先下载再播」方案，或关闭 quick-autoplay。
5. 普通授权版经云打包加密；本地自定义基座可试用，正式包需购买后云打包。
6. 默认图标位于插件 static/，可自行传入 playIcon / pauseIcon 覆盖。

目录结构

uni_modules/su-video-stream/
├── package.json
├── readme.md
├── usage.md              # 完整使用方法
├── changelog.md
├── license.md
├── static/
│   ├── play.png
│   └── pause.png
└── components/
    └── su-round-video-stream/
        └── su-round-video-stream.vue

价格说明

在 package.json → dcloudext.sale 中已预设：

• 普通授权版：9.90 元
• 源码授权版：49.90 元

发布前请按实际定价修改。HBuilderX 发布界面若暂不支持前端组件改价，以 package.json 为准。

发布步骤：HBuilderX 中右键 uni_modules/su-video-stream → 提交到插件市场。