ew-video-player-pro
v0.0.4
Published
原生 HTML5 视频播放器(TypeScript 实现,支持 HLS 清晰度切换,支持进度/音量/全屏/悬停预览)
Maintainers
Readme
ew-video-player-pro
原生 HTML5 视频播放器,TypeScript 实现,支持 HLS 清晰度切换(hls.js 按需动态加载)。
特性
- 🎬 播放 / 暂停 / 进度拖拽 / 缓冲指示
- 🔍 悬停/触摸预览(PC 悬停进度条、移动端按住拖动,显示缩略帧 + 时间标签)
- 🔊 音量滑块 + 静音切换(拖动即解除静音,图标与
video真实音量状态始终同步) - 🖥️ 全屏(Fullscreen API + iOS
webkitEnterFullscreen降级);全屏下控制条 3 秒无交互自动隐藏,暂停时常显,隐藏后移动鼠标或点击画面即可重新唤出 - 🔌 自定义控制按钮(收藏 / 播放队列 / 分享等),初始化传入或运行时动态增删改
- 📱 触屏适配(点击视频切换控制条、按住进度条预览缩略帧、4 秒无操作自动隐藏控制条)
- 🤖 自动播放(有声被拦截时静音兜底)
- 🎨 主题色可切换(默认
blue) - 📦 CSS / JS 分离——调用方手动引入 CSS,无自动注入
- 💾 所有图标内联(SVG data URI + base64 PNG),零外部图片依赖
安装
npm i ew-video-player-pro
# 或
pnpm add ew-video-player-pro快速使用
CSS 和 JS 必须分开引入(JS 不会自动注入 CSS):
import "ew-video-player-pro/dist/style.css"; // ← 必须手动引入
import { createPlayer } from "ew-video-player-pro";
// 1) HTML 中只需要一个容器(播放器内部自动创建 <video>,无需自己写 video)
// <div id="demo" style="width:720px;height:405px"></div>
// 2) 初始化(也兼容传入已有 <video> 元素,此时可省略 src,回退元素自带 src)
const player = createPlayer("#demo", {
src: "/demo.mp4",
volume: 0.7,
});
// 3) 操作
player.play();
player.pause();
player.toggle();
player.destroy(); // 卸载:还原 DOM + 清理事件UMD 全局(CDN 引入)
<link rel="stylesheet" href="./node_modules/ew-video-player-pro/dist/style.css" />
<script src="./node_modules/ew-video-player-pro/dist/index.umd.js"></script>
<script>
const player = window.EwVideoPlayer.createPlayer("#demo", { src: "/demo.mp4" });
</script>Options
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
| src | string | 必填 | 视频地址(传入已有 <video> 时可不传,回退元素 src) |
| volume | number | 0.7 | 初始音量 0 ~ 1 |
| autoplay | boolean | false | 自动播放;有声被浏览器拦截时自动静音兜底 |
| theme | string | "blue" | 主题色类名,CSS 里目前只有 blue |
| className | string | "ew-video-player" | 外层容器 className |
| fitMode | "cover" \| "contain" | "cover" | 视频填充方式:铺满裁切 / 保持宽高比留边 |
| fetchAsBlob | boolean | false | fetch 成 Blob 后播放,DOM 中只暴露 blob: 地址(需同源或 CORS;大文件慎用) |
| protected | boolean | false | 保护模式:阻止右键/长按/拖拽,隐藏 src 属性,禁用下载 |
| qualities | PlayerQuality[] | - | 多清晰度列表 { label, src, default? },齿轮菜单出现"清晰度"分组;.m3u8 档位自动走 HLS(Safari 原生,其余浏览器动态加载 hls.js),切换保持进度与倍速 |
| customControls | PlayerControl[] | - | 自定义控制按钮,追加在内置按钮左侧,按数组顺序排列(见下文) |
HLS 与清晰度切换
src直接传含多档的主m3u8:解析后自动生成清晰度菜单,含"自动"档(hls.js ABR 按网速自适应)。- 或传
qualities显式列出各档地址(各自独立的m3u8,也可混普通 mp4),切换时保持currentTime、playbackRate与播放状态。 - HLS 源下
fetchAsBlob自动失效;进度条悬停预览退化为仅显示时间。 - hls.js 为按需动态加载,仅在使用 HLS 源时才会拉取对应 chunk(ESM 构建自动分包)。
自定义控制按钮
播放器留出了业务扩展位:按钮追加在内置齿轮/音量/全屏按钮的左侧,按传入顺序排列。
const player = createPlayer("#demo", {
src: "/demo.mp4",
customControls: [
{
id: "fav",
title: "收藏",
// icon 三种写法:内联 SVG(以 < 开头)/ 图片地址 / 纯文本
icon: '<svg viewBox="0 0 24 24" stroke="#fff" fill="none"><path d="M19 21l-7-5-7 5V5h14z"/></svg>',
onClick: (p) => {
// 收藏状态由业务自己维护,用 active 展示选中态
p.updateControl("fav", { active: true, title: "取消收藏" });
},
},
{ id: "queue", title: "播放队列", label: "队列", onClick: () => openQueuePanel() },
],
});PlayerControl 字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 必填,唯一标识,动态更新/移除时使用 |
| title | string | 悬浮提示与 aria-label |
| icon | string | 内联 SVG / 图片地址 / 纯文本(优先于 label) |
| label | string | 纯文字按钮文案 |
| active | boolean | 激活态(如已收藏),默认 false,显示高亮与小圆点 |
| visible | boolean | 是否显示,默认 true |
| onClick | (player) => void | 点击回调,入参为播放器实例 |
运行时动态增删改:
player.addControl({ id: "share", title: "分享", icon: SHARE_SVG, onClick: () => {} });
player.updateControl("share", { active: true, title: "已分享" });
player.updateControl("share", { visible: false });
player.removeControl("share");Player 实例方法
interface PlayerInstance {
el: HTMLDivElement; // 外层容器 DOM
video: HTMLVideoElement; // 原生 <video> 元素
play(): void;
pause(): void;
toggle(): void; // 切换播放/暂停
addControl(control: PlayerControl): void; // 追加(同 id 等价于更新)
removeControl(id: string): void; // 按 id 移除
updateControl(id: string, patch: Partial<PlayerControl>): void; // 局部更新
destroy(): void; // 卸载:pause + 清空 src + 还原 DOM + 移除事件监听
}工具函数(可单独使用)
包还导出了 6 个纯工具函数,可独立复用:
import {
ewVideoPlayerGetEle, // DOM 查询:ewVideoPlayerGetEle<T>(root, ".selector")
bindSlider, // 通用滑块(进度条 / 音量条)
formatTime, // 秒数 → "mm:ss"
pageXOf, // 从 MouseEvent / TouchEvent 取 pageX
pageLeftOf, // 元素文档左侧偏移(含滚动)
isFullscreen, // 判断是否全屏
} from "ew-video-player-pro";
// 用 bindSlider 做一个你自己的音量滑块
bindSlider(mySlider, myBar, myFill, 6, (ratio) => {
console.log("ratio:", ratio); // 0 ~ 1
});开发
pnpm install
pnpm run build:lib # 构建 dist(ES + UMD + d.ts + 复制 style.css)
pnpm run pack # npm pack 本地打 tarball构建产物:
dist/
├── index.es.mjs 21.7 kB ← ES Module(hls.js 已自动分包)
├── hls-*.mjs 859.4 kB ← hls.js 独立 chunk(仅 HLS 源按需加载)
├── index.umd.js 610.6 kB ← UMD (window.EwVideoPlayer,内含 hls.js)
├── index.d.ts / Player.d.ts / util.d.ts ← 类型声明
└── style.css 81.8 kB ← 独立 CSS(图标 SVG data URI + base64 内联)控制条显隐规则
| 场景 | 行为 | |---|---| | 非全屏 | 鼠标悬停在播放器上时控制条从底部滑出;移出即隐藏 | | 全屏 | 进入全屏先显示控制条;鼠标移动/触摸或点击画面时唤出并重新计时,3 秒无交互自动隐藏(此时鼠标指针一并隐藏) | | 全屏 + 暂停 | 控制条常显,不自动隐藏;恢复播放后重新计时 | | 设置菜单打开 | 控制条不会自动隐藏 | | 移动端 | 点击视频切换控制条;播放中 4 秒无操作自动隐藏 |
版本历史
| 版本 | 说明 |
|---|---|
| 0.0.3 | 新增自定义控制按钮扩展:options.customControls + 实例方法 addControl / updateControl / removeControl(支持 SVG / 图片 / 文字图标、active 选中态、显隐);修复全屏控制条隐藏后无法唤出(改为 document 级鼠标/触摸监听,点击画面优先唤出控制条);播放/暂停图标换成圆角 SVG(样式体积减少约 44KB);修复移动端/矮容器里设置菜单顶部被裁切、倍速列表看不到的问题(按控制条上方可用高度限高并内部滚动) |
| 0.0.2 | 全屏控制条改为 3 秒无交互自动隐藏(不再依赖 hover)、暂停时保持常显;音量控制重构(以 video 真实状态为准,拖动即解除静音,修复默认静音与点不动/回跳);音量条加宽并扩大点击热区;全屏图标换成 SVG 并加 hover 反馈 |
| 0.0.1 | 首版——从 website 项目原生 player.js 迁移,TypeScript 重写 + CSS 精简 + 6 图标 base64 内联 + util 拆分 |
License
MIT © eveningwater
