更新记录

0.1.0（2026-03-18） 下载此版本

首个正式版本，基于 uni-app 官方 video 组件封装，提供面向业务场景的视频播放能力。

新增

组件与结构

• 初始化 uni_modules/yvibe-play 插件结构
• 新增 YvVideo 核心组件，支持 easycom 规范
• 使用 Vue3 + <script setup> + TypeScript 实现

播放与控制

• 基础播放：播放、暂停、停止、跳转、全屏、退出全屏
• 倍速切换：支持 0.5 / 0.75 / 1 / 1.25 / 1.5 / 2 倍速
• 静音切换：支持初始静音与动态切换
• 全屏方向：支持横屏(90)、竖屏(0)、退出全屏，可自定义传参

展示状态

• 空态、加载态、错误态
• 封面播放态（poster + 播放按钮）
• 播放结束重播态
• 错误重试与加载超时兜底

业务能力

• 播放进度记忆与恢复（本地存储，可配置 key）
• 同组视频互斥播放（playbackGroupKey 分组）
• 统一播放器状态透出（idle / poster / loading / playing / paused / ended / error）

文档与示例

• 完整 Props / Events / Methods / States 文档
• 平台说明、使用提示与发布前检查清单
• 演示页（基础播放、全屏方向、倍速、静音、互斥播放）

适配

• 目标平台：小程序、app-vue、app-nvue、Android、iOS、鸿蒙
• 已验证：微信小程序（基础播放、全屏、倍速、静音、互斥）、Android

平台兼容性

uni-app(4.04)

YVibePlay

YVibePlay 是一个面向 uni-app 的视频播放业务组件插件，当前以 YvVideo 为核心组件，底层基于官方 video 组件封装，优先保证多端一致性、业务可用性和后续可扩展性。

当前定位

• 组件名称：YvVideo
• 技术栈：Vue3 + <script setup> + TypeScript
• 组织方式：uni_modules/yvibe-play
• 适用场景：内容播放页、课程视频、短视频详情、列表页单视频卡片

适配目标

• 小程序
• app-vue
• app-nvue
• Android
• iOS
• 鸿蒙

当前能力

• 基础播放：播放、暂停、停止、跳转、全屏、退出全屏
• 展示状态：空态、加载态、错误态、封面播放态、结束重播态
• 控制能力：倍速切换、静音切换、全屏方向控制
• 业务能力：进度记忆恢复、加载超时兜底、同组互斥播放
• 状态能力：统一播放器状态透出

使用示例

<template>
  <view class="page">
    <YvVideo
      ref="videoRef"
      src="https://www.w3schools.com/html/mov_bbb.mp4"
      poster="https://dummyimage.com/750x420/000/fff.png&text=YVibePlay"
      :controls="true"
      :autoplay="false"
      :enable-progress-memory="true"
      :playback-rate="1.25"
      @play="handlePlay"
      @pause="handlePause"
      @statechange="handleStatechange"
    />
  </view>
</template>

<script setup lang="ts">
import { ref } from "vue";
import type {
  YvVideoInstance,
  YvVideoPlayerState,
} from "@/uni_modules/yvibe-play/components/YvVideo";

const videoRef = ref<YvVideoInstance | null>(null);

const handlePlay = () => {
  console.log("play");
};

const handlePause = () => {
  console.log("pause");
};

const handleStatechange = (state: YvVideoPlayerState) => {
  console.log("state", state);
};
</script>

Props

Events

Methods

通过 ref 调用：

States

播放器对外透出的统一状态 YvVideoPlayerState：

平台说明

• 小程序中 video 属于原生组件，复杂浮层和层级覆盖能力有限。
• 微信小程序全屏横屏能力依赖基础库、机型和系统旋转设置，建议真机验证。
• requestFullScreen({ direction }) 在部分平台支持方向参数，H5 等平台可能忽略该参数。
• 进度记忆默认使用本地存储，建议业务层在切换账号或更换内容时按需清理。
• 多实例互斥播放依赖 playbackGroupKey 分组，同组内才会互斥。

当前验证记录

已知限制

• 当前默认以官方 video 组件能力为主，不包含自定义复杂控制栏。
• 原生 video 组件在小程序和部分 App 场景下层级较高，不适合做复杂浮层覆盖。
• 加载超时、倍速、全屏方向等能力在不同平台和基础库上的表现可能存在差异。
• 文档中的能力说明基于当前实现版本，发布前建议再次做目标平台回归验证。

演示说明

当前仓库首页演示已覆盖：

• 基础播放、暂停、跳转
• 全屏方向切换
• 倍速切换
• 静音切换
• 统一状态展示
• 双视频同组互斥播放

发布前检查清单

• [ ] 确认 uni_modules/yvibe-play/package.json 中版本号与发布内容一致
• [ ] 确认 README、CHANGELOG、示例代码与当前实现一致
• [ ] 清理调试性代码、临时资源和无效文案
• [ ] 在目标平台完成至少一轮真实运行验证
• [ ] 重点验证全屏、重试、进度恢复、互斥播放、倍速和静音切换
• [ ] 如需上插件市场，补充作者信息、封面图、版本说明和平台截图

版本记录

• 版本变更请维护在 uni_modules/yvibe-play/CHANGELOG.md

目录说明

• 当前目录采用 uni_modules/yvibe-play 规范组织。
• displayName 保持为 YVibePlay，便于品牌展示。
• 实际发布到插件市场前，可按作者标识调整为更完整的插件 id。
• 插件市场发布文案草稿请查看 uni_modules/yvibe-play/PLUGIN_MARKET_COPY.md