更新记录

1.4.1（2026-10-11）

• 修复清晰度切换后进度跳转失效的问题：改为等待新视频源 loadedmetadata 就绪后再跳转进度，避免固定延时导致的竞态
• 修复同页面存在多个播放器时键盘快捷键互相干扰的问题：键盘监听改为绑定到播放器容器，点击视频获得焦点后生效
• 修复 App 端 renderjs 在渲染层未挂载时无限重试创建 video 的问题，改为有限次重试
• 修复全屏切换后测量尺寸的定时器未回收的问题，组件销毁时统一清理
• 修复桌面端滚轮监听解除时可能因重新查询元素失败而残留的问题

平台兼容性

uni-app(5.0)

其他

hy-video-player 视频播放器

hy-video-player 是一个功能完整、开箱即用的视频播放器组件，基于 uni-app 编写，兼容 Vue2 / Vue3。内置自定义控制层与全套手势交互：长按倍速、双击左右快进/快退、水平滑动调节进度、左侧上下滑动调节亮度、右侧上下滑动调节音量，并支持播放暂停、进度拖拽、全屏、倍速、清晰度切换等常用功能。

功能特性

• 自定义控制层：播放/暂停、时间显示、进度条拖拽（支持点击/拖动、触摸与桌面鼠标）、缓冲进度、全屏、倍速、清晰度、循环播放开关
• 菜单自动收起：倍速/清晰度菜单在点击播放、音量、循环、全屏、进度条等其它功能或控制层自动隐藏时自动关闭
• 控制栏自动隐藏：播放时控制栏延时自动隐藏（autoHideDelay，默认 4000ms）；打开菜单或拖拽进度条等操作过程中不会自动隐藏，操作结束或关闭菜单后重新计时；设为 0 可禁用自动隐藏
• 桌面端交互（H5/PC）：鼠标按住拖动可调节亮度（左半屏上下）/ 音量（右半屏上下）/ 进度（水平）；鼠标滚轮调节音量（Ctrl / Alt + 滚轮调节亮度）；键盘快捷键：空格播放/暂停、← / → 快退/快进、↑ / ↓ 调音量、Esc 退出全屏（可通过 enableWheel、enableKeyboard 关闭）
• 宽屏自适应：未设置 height 时按 aspectRatio（默认 16:9）随容器宽度自适应高度，电脑宽屏下高度自动缩放；显式设置 height 时以 height 为准
• 长按倍速：长按视频临时提升倍速播放，松手恢复（倍速与长按时长可配置）
• 双击快进 / 快退：双击左半屏快退、右半屏快进（步长可配置）
• 水平滑动调节进度：左右滑动实时预览目标时间，松手生效
• 垂直滑动调节亮度：左半屏上下滑动调节屏幕亮度（App / 小程序调用系统亮度，H5 用遮罩模拟）
• 垂直滑动调节音量：右半屏上下滑动调节音量（App / H5 生效，其他平台降级）
• 多清晰度切换：传入 sources 即可在控制层切换，切换时自动保持播放进度
• App 端 renderjs 渲染：使用 HTML5 video 渲染，绕开原生组件层级限制，自定义 UI 可完整覆盖
• 零第三方依赖：图标全部使用内联 CSS 绘制

安装

将 hy-video-player 目录放入项目的 uni_modules 目录即可，组件已支持 easycom，无需手动 import。

基本用法

<template>
    <view>
        <hy-video-player
            :src="src"
            poster="https://example.com/poster.png"
            title="演示视频"
            height="420rpx"
            :autoplay="false"
            :seek-step="10"
            :long-press-rate="3"
            theme-color="#3b7cff"
            @play="onPlay"
            @timeupdate=""
            @ended=""
        />
    </view>
</template>

<script>
export default {
    data() {
        return {
            src: 'https://example.com/video.mp4'
        }
    },
    methods: {
        onPlay() {},
        (e) {
            // e.currentTime, e.duration
        },
        () {}
    }
}
</script>

属性 Props

事件 Events

方法 Methods

通过 ref 调用：

交互说明

• 单击：显示 / 隐藏控制层（若已打开菜单则关闭菜单）
• 双击左半屏：快退 seekStep 秒
• 双击右半屏：快进 seekStep 秒
• 长按：进入 longPressRate 倍速播放，松手恢复
• 左右滑动：调节播放进度，松手生效
• 左半屏上下滑动：调节亮度
• 右半屏上下滑动：调节音量
• 进度条：点击或拖动可直接跳转进度（H5 端支持鼠标）

电脑鼠标操作（H5 / PC）

组件同时支持鼠标操作：按下左键后拖动可触发滑动类手势（进度 / 亮度 / 音量），双击快进/快退、单击切换控制层均可用；进度条可直接用鼠标点击或拖动。未按下左键时的鼠标移动不会触发任何手势。

平台支持与差异

说明：微信小程序 video 组件没有提供音量控制 API，因此音量滑动在微信小程序会降级为静音切换。

注意事项

1. App 端使用 renderjs 渲染 HTML5 video，请在 App（vue 页面） 中使用，不支持 nvue 页面。
2. 亮度调节在 App / 微信小程序调用系统屏幕亮度 API，组件销毁时会尽量恢复初始亮度；H5 等不支持的平台使用黑色遮罩模拟，仅改变视觉明暗。
3. App 端与 H5 端全屏通过 CSS 全屏实现（App 额外锁定横竖屏方向），可保证自定义控制层在全屏下依然可操作；微信小程序走 VideoContext.requestFullScreen。
4. 清晰度切换会重新加载视频资源，组件会尽量保持当前播放进度与播放状态。
5. 自动播放受各平台策略限制（如 H5 需要静音或用户交互后才可自动播放），请结合 muted 使用。
6. 倍速 / 清晰度菜单选项较多时，菜单内部可上下滑动；菜单高度自适应播放器高度，不会溢出播放器区域。