SPEC.md

自定义视频播放器 需求规格说明书

一、项目概述

基于原生 HTML5 video 标签 + TS + CSS 封装通用网页视频播放器，完全替换原生控制器，实现图标化控制、自适应收纳、自定义按钮、XGPlayer 风格居中悬浮图标交互，仅适配常规 MP4 视频。

二、基础固定控制器（默认常驻、不收纳）

1. 播放/暂停按钮（SVG 切换）
2. 可拖拽进度条（已播放进度、缓冲进度、拖拽圆点）
3. 时间展示（当前时间 / 总时间，自动适配时分秒）
4. 音量控制（音量图标+水平滑块、静音切换）

三、选配控制器（默认开启、宽度不足自动收纳）

1. 画中画按钮
2. 视频下载按钮
3. 样式全屏（容器全屏，非系统全屏）
4. 系统原生全屏

四、核心特殊需求

1. 控制器自适应收纳

• 实时监听播放器容器宽度
• 宽度充足：所有按钮横向展示
• 宽度不足：自动将选配按钮、自定义按钮从右至左收纳
• 右侧常驻「三点更多」图标按钮，点击弹出收纳菜单
• 移动端自动收缩为极简模式

2. 自定义按钮能力

• 支持外部传入自定义按钮配置
• 渲染优先级：内置基础按钮 > 内置选配按钮 > 自定义按钮
• 空间不足时，自定义按钮优先被收纳
• 支持自定义图标、点击事件、悬浮提示、永久收纳配置

3. XGPlayer 居中悬浮透明图标交互

1. 首次加载未播放：居中展示透明轮廓播放图标，点击播放且图标永久消失
2. 播放中点击视频空白处：浮现透明轮廓暂停图标，渐变淡出消失
3. 暂停中点击视频空白处：浮现透明轮廓播放图标，渐变淡出消失
4. 图标为空心轮廓、低透明度、居中悬浮，不遮挡控制器

4. 控制栏显隐优化（新增）

1. 视频播放中，鼠标离开播放器：自动隐藏
2. 视频播放中，鼠标不动3秒：自动隐藏
3. 视频暂停中：不自动隐藏
4. 正在拖拽进度条/音量：不自动隐藏
5. 更多菜单显示中：不自动隐藏

5. MORE按钮动态显示（新增）

1. 仅当容器宽度不足以显示所有按钮时才显示MORE按钮
2. 拉伸屏幕后，所有按钮展开时自动隐藏MORE按钮
3. 更多菜单在所有按钮展开后自动关闭

6. 全屏按钮图标切换（新增）

1. 样式全屏按钮：进入全屏显示退出图标（CSS_EXIT_FULLSCREEN），退出全屏显示进入图标（CSS_FULLSCREEN）
2. 原生全屏按钮：进入全屏显示退出图标（EXIT_FULLSCREEN），退出全屏显示进入图标（FULLSCREEN）
3. 通过 ButtonItem 的 activeIcon 属性实现状态切换

五、UI 硬性规范

1. 所有控制元素纯 SVG 图标，无任何文字
2. 控制器静止 3 秒自动隐藏，鼠标移动重新显示
3. 下拉菜单点击外部/点击按钮后自动关闭
4. 所有功能做浏览器兼容降级（不支持则隐藏/置灰）

六、技术能力清单

1. 完整播放控制：播放、暂停、快进、进度拖拽
2. 音量调节、静音切换
3. 双全屏模式：样式全屏、系统全屏
4. 画中画切换
5. 视频下载（支持自定义文件名）
6. 键盘快捷键支持
7. 完整实例生命周期 + 销毁方法（无内存泄漏）
8. 事件订阅系统（on/once/off）

七、非功能需求（不做）

1. 不支持流媒体、加密视频、倍速、字幕、弹幕
2. 不依赖任何第三方播放器、图标库
3. 不兼容 IE 以外的老旧浏览器