npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

ew-video-player-pro

v0.0.4

Published

原生 HTML5 视频播放器(TypeScript 实现,支持 HLS 清晰度切换,支持进度/音量/全屏/悬停预览)

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