更新记录

1.4.1（2026-10-11）

• 修复 Web 端音量调节不生效的问题：音量/静音现已真实写入底层 video 元素
• longPressRate 默认值由 2 调整为 3，与 Vue 版保持一致
• 修复全屏切换后测量尺寸的定时器未回收的问题，组件卸载时统一清理
• 点击视频/容器后自动聚焦，桌面端键盘快捷键更易生效
• 全屏按钮新增退出态图标；菜单补充最大高度兜底，避免测量前溢出
• 为 <video> 补充 duration 绑定（配合 durationHint）

平台兼容性

uni-app x(4.66)

其他

hy-video-player-x 视频播放器

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

与 Vue2 版 hy-video-player 的主要差异：本组件直接使用 uni-app x 原生 video 组件（同层渲染，自定义 UI 可完整覆盖），脚本采用 <script setup lang="uts"> 写法，longPressRate 默认值为 2。

功能特性

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

安装

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

需使用 uni-app x 项目（HBuilderX 编译到 App-Android / App-iOS / App-HarmonyOS / Web / 微信小程序）。

基本用法

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

<script setup lang="uts">
    type TimeUpdatePayload = {
        currentTime : number,
        duration : number
    }

    const src = ref('https://example.com/video.mp4')

    const onPlay = () => {}
    const  = (e : TimeUpdatePayload) => {
        // e.currentTime, e.duration
    }
    const  = () => {}
</script>

完整可运行示例见插件目录 example/example.uvue：将其拷入 uni-app x 工程并在 pages.json 中注册后即可预览。

属性 Props

事件 Events

交互说明

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

电脑鼠标操作（Web）

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

此外，Web 桌面端还支持：鼠标滚轮调节音量（按住 Ctrl / Alt 时调节亮度）；键盘快捷键——空格播放/暂停、← / → 快退/快进、↑ / ↓ 调音量、Esc 退出全屏。键盘快捷键需先点击一次视频使其获得焦点后生效，可通过 enableWheel、enableKeyboard 关闭。

平台支持与差异

说明：uni-app x 原生 video 组件没有提供音量控制 API，因此音量滑动在各平台统一降级为静音开关（滑到 0 静音、非 0 恢复）；Web 平台不支持系统亮度，使用黑色遮罩模拟明暗。

注意事项

1. 组件直接使用原生 video 组件并开启同层渲染，控制层 / 手势层覆盖在视频之上，请在页面中为播放器预留足够高度。
2. 亮度调节在 App / 微信小程序调用系统屏幕亮度 API，组件销毁时会尽量恢复初始亮度；Web 使用黑色遮罩模拟，仅改变视觉明暗。
3. App 端与 Web 端全屏通过 CSS 全屏实现（组件根节点固定定位铺满视口），可保证自定义控制层在全屏下依然可操作；微信小程序走原生 VideoContext.requestFullScreen / exitFullScreen。
4. 清晰度切换会重新加载视频资源，组件会尽量保持当前播放进度与播放状态。
5. 自动播放受各平台策略限制（如 Web 需要静音或用户交互后才可自动播放），请结合 muted 使用。
6. 倍速 / 清晰度菜单选项较多时，菜单内部可上下滑动；菜单最大高度受限，不会溢出播放器区域。