更新记录

1.0.0（2026-07-20） 下载此版本

1. 首次发布 v-videos 视频播放器组件。
2. 支持播放、暂停、进度拖动、循环播放、全屏及自定义控制栏。
3. 支持弹幕发送、弹幕设置、多清晰度切换和倍速播放。
4. 支持剧集选集、直播模式、加载状态及自定义操作面板。
5. 支持 Props、事件、实例方法和 CSS 变量配置。
6. 支持 Vue 3 和 TypeScript 类型提示。

平台兼容性

uni-app(4.84)

v-videos (uniapp-video-next) 🎬

基于 Vue 3 + TypeScript 的高性能、轻量级、跨平台 uni-app 自定义视频播放器组件

English Document | 中文文档

✨ 特性

• 🚀 Vue 3 Composition API & TypeScript：模块化 Composables 拆分，提供完备的类型声明与类型推导。
• 🔴 直播源模式支持 (Live Streaming Support)：支持 :is-live="true" 模式，自动隐藏总时长与进度条，提供动态脉冲 LIVE 状态 Tag 标识（支持自定义 :live-text）。
• 💬 高性能弹幕引擎 (Danmaku Engine)：
  • 平滑动画、自动轨道排版。
  • 支持弹幕显示区域、不透明度、字体大小、弹幕速度自定义调整。
  • 内置 Emoji 表情盘与多彩弹幕选择器。
• 📺 多清晰度无缝切换：支持多档清晰度（如 1080P, 720P, 480P, 自动），切换时自动记录并恢复播放进度。
• ⚡ 海量自定义 Action 面板：支持传入自定义操作列表（2 项、10 项、20+ 项网格扩展），带有点击回调代理 @moreactionclick。
• 🚀 播放倍速配置与选择：支持自定义倍速列表 :rates="[0.5, 0.75, 1.0, 1.25, 1.5, 2.0]"，支持实例方法切换。
• ⏳ 网络 Loading 加载浮层：自动与手动支持卡顿缓冲状态浮层 :loading、:loading-text 与 :loading-icon。
• 🎨 CSS 变量与灵活主题：基于 CSS Custom Properties (--vp-*)，轻松定制色彩、阴影、圆角与毛玻璃面板样式。
• 📱 全平台兼容 (Cross-Platform)：适配 H5、微信小程序 (WeChat Mini Program)、App (iOS / Android) 及 鸿蒙 (HarmonyOS)。
• 👆 触控手势支持：进度条平滑拖拽预览、音量调节面板与滑块手势。

🌐 在线预览与 H5 打包 (Online Preview & Build)

• 🚀 GitHub Pages 在线 H5 预览：https://mhxy13867806343.github.io/uniapp-video-next/
• 💻 本地 H5 编译预览：

  npm run dev:h5

• 📦 编译并打包 H5 静态产物 (导出至 dist/build/h5)：

  npm run build:h5

📦 安装与快速上手

1. 引用组件

直接在页面中引入 v-videos 组件：

<template>
  <view class="container">
    <v-videos
      ref="playerRef"
      :src="videoSrc"
      title="uni-app 视频播放演示"
      :custom-controls="true"
      :is-live="false"
      :qualities="qualities"
      :danmus="danmus"
      :more-actions="moreActions"
      @play="onPlay"
      @timeupdate=""
      @moreactionclick="onMoreActionClick"
    />
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import VVideos, {
  defaultDanmus,
  defaultQualities,
  defaultMoreActions,
  defaultRates,
  formatTime,
  type MoreActionItem,
} from '@/components/v-videos'

const playerRef = ref<InstanceType<typeof VVideos> | null>(null)
const videoSrc = ref('https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/2minute-demo.mp4')

// 直接复用预设配置，也可自定义传入
const qualities = defaultQualities
const danmus = defaultDanmus
const moreActions = defaultMoreActions
const rates = defaultRates

function onPlay() {
  console.log('开始播放')
}

function (payload: { currentTime: number; duration: number }) {
  console.log('当前进度：', formatTime(payload.currentTime))
}

function onMoreActionClick(payload: { item: MoreActionItem; index: number; key: string }) {
  console.log('点击更多操作：', payload.item.label)
}
</script>

⚙️ 属性声明 (Props)

🔔 事件声明 (Emits)

🛠 组件方法 (Exposed Methods)

通过 ref 可以调用组件暴露的原生与高级控制方法：

const playerRef = ref<InstanceType<typeof VVideos> | null>(null)

// 调用播放
playerRef.value?.play()

// 调用暂停
playerRef.value?.pause()

// 跳转进度（秒）
playerRef.value?.seek(30)

// 发送实时弹幕
playerRef.value?.sendDanmu({ text: '动态发送弹幕', color: '#ff0000' })

// 切换弹幕开关
playerRef.value?.toggleDanmaku()

// 切换清晰度
playerRef.value?.selectQuality(0)

// 切换倍速
playerRef.value?.playbackRate(1.5)

🎨 样式定制 (CSS Variables)

组件使用 CSS 变量进行主题定制，你可以在项目全局或页面样式中进行覆盖：

.video-player {
  --vp-primary-color: #22c55e;        /* 主色调 */
  --vp-primary-gradient: linear-gradient(135deg, #22c55e, #16a34a);
  --vp-bg-black: #000000;              /* 背景底色 */
  --vp-panel-bg: rgba(15, 23, 42, 0.9);/* 面板背景色 */
  --vp-radius-xl: 24rpx;               /* 圆角尺寸 */
}

📂 项目文件结构

src/
├── components/v-videos/             # v-videos 播放器核心组件
│   ├── v-videos.vue                 # SFC 视图模板与逻辑入口
│   ├── index.ts                     # 模块导出统一入口
│   ├── types.ts                     # 完备的 TypeScript 接口声明
│   ├── config.ts                    # 预设配置与 formatTime 工具函数
│   ├── styles/                      # CSS 独立样式目录
│   │   ├── vars.css                 # CSS 自定义变量主题定义
│   │   ├── common.css               # 公共重复 CSS 样式类
│   │   └── video-player.css         # 播放器组件主样式表
│   └── composables/                 # TS 核心逻辑模块化抽离
│       ├── useVideoPlayer.ts        # 主 Hook 装配与调度
│       ├── useVideoControls.ts     # 播放状态、清晰度、倍速与 VideoContext
│       ├── useDanmaku.ts           # 弹幕动画引擎与弹幕设置
│       ├── useVideoGestures.ts     # 进度条与滑块触摸手势
│       ├── useVideoEvents.ts       # 视频原生 DOM/小程序事件句柄
│       └── useVideoOptions.ts      # 参数合并与图标配置
└── pages/                           # 页面与功能测试中心
    ├── index/index.vue              # 导航主页面与基础演示
    ├── demo-live/demo-live.vue      # 直播源功能测试页面
    ├── demo-more/demo-more.vue      # 更多操作面板测试页面
    ├── demo-rate/demo-rate.vue      # 播放倍速切换测试页面
    └── demo-loading/demo-loading.vue# 网络 Loading 状态测试页面

📄 License

MIT