videojs-ui

打造 Video.js 播放器 UI

播放器 UI 是普通的界面工作，只是条件比较特殊：它浮在不断变化的画面上，空闲时会隐藏，同时由键盘、鼠标和触控驱动，并且会以每秒多次的频率报告变化状态。一般的界面建议仍然适用，但需根据以下规则调整。

如果要完成整个皮肤项目，videojs-skin 技能涵盖设置、工作台和发布流程。要安装或配置播放器，请使用 videojs 技能。

查找文档

阅读 node_modules/@videojs/<react|html>/docs/llms.txt 中随附的文档，或访问 https://videojs.org/docs/framework/<react|html>/llms.txt，并在页面 URL 后附加 .md。按标题查找：

需求	阅读
控件如何公开状态、属性和渲染自定义功能	UI 组件
库中未提供的控件	构建自己的 UI 组件
单个组件的部件、data-* 状态、CSS 属性和按键	其参考页面
组件现有的无障碍功能	无障碍功能
快捷键、手势和翻译后的标签	键盘快捷键、国际化

工作流程

1. 在开始设置样式前，先明确要构建什么。如果有参考或设计规范，就按其实现，不要添加其中没有展示或用户没有要求的内容。如果没有，就用几行描述预期外观，并在构建多个控件前确认。
2. 从 Video.js 组件开始，或通过其中一个组件渲染你的元素，以保留其角色、翻译后的标签、状态属性和键盘支持。仅在库缺少所需功能时才从头构建，并遵循“构建自己的 UI 组件”中的说明。
3. 构建时遵循以下规则。
4. 在安装了配套技能或用户同意添加这些技能时，使用 references/companions.md 中的技能进行润色。
5. 交付前，按照 references/review.md 进行检查。

视频上的 UI 规则

• 对照画面，而非页面背景检查对比度。 在明亮、暗淡和画面繁杂的帧上测量文本和图标的对比度。使用遮罩层、渐变、半透明表面或阴影将控件与视频区分开；单靠细线边框会消失。
• 保持数字稳定。 时间显示始终使用 font-variant-numeric: tabular-nums（Tailwind tabular-nums）；播放时会变化的速率和计数也使用该属性，让数字保持相同宽度，避免布局跳动。为长媒体的小时数和直播标签留出空间。
• 图标使用同一套，并按实际显示尺寸绘制。 使用用户自己的设计文件时，直接采用其中导出的图标。仿照他人的播放器时，重新绘制出外观相同的图标；不要复制其 SVG。除此之外，使用现有图标集，或创建一套拥有统一网格、描边、圆角和风格的新图标。绝不要混用不同图标集。添加或更改图标前，请阅读 references/icons.md。
• 在原位切换图标状态。 播放和暂停、音量级别以及进入或退出图标共用同一位置，并根据组件的 data-* 属性切换，通过交叉淡入淡出而非跳动来切换。整套图标保持统一的描边粗细和视觉尺寸。
• 确保常用控件响应迅速。 播放、静音和拖动进度条操作频繁：提供即时的按压反馈，尽量减少或避免动画。菜单和弹出框从其触发控件处展开；设置菜单应快速打开，因为用户经常使用。
• 平稳地隐藏和显示控件。 空闲时隐藏控件应采用短暂、轻微的退出动画；指针移动、触摸或键盘聚焦时，控件应立即显示。首次加载时不播放任何动画。
• 优先考虑触摸操作。 将悬停样式放在支持悬停的指针媒体查询中，因为轻触会显示控件，而悬停状态卡住会让控件看起来像是已选中。目标区域至少为 24 × 24 CSS 像素，触摸设备上应更大；滑块的可点击区域应高于可见轨道，密集的控件栏中各目标区域不得重叠。
• 动画遵循用户偏好。 通过令牌管理动画时长，并在减少动态效果的设置下将其缩短；为 transform、opacity 和 filter 添加动画，并明确指定过渡涵盖的属性。
• 按用途使用颜色。 使用语义令牌，例如强调色和控件表面色；强调色仅用于品牌。除非设计有充分依据，否则两种配色方案中的视频控件都应保持深色。
• 绝不硬编码 UI 文案。 可见文本、工具提示和无障碍名称均应来自 Video.js i18n：内置控件提供已翻译的标签，新字符串通过 Video.js 翻译（Internationalization）处理。文案使用句首字母大写，并明确说明操作结果。为较长语言版本留出空间，并针对从右向左的语言镜像布局。
• 保持工具提示和焦点样式一致。 播放器启用工具提示时，每个工具提示与对应控件的偏移量和样式都应相同，包括播放器边缘处的工具提示。每个可聚焦部分，包括按钮、滑块滑块和菜单项，都应显示相同的可见焦点环，并使用播放器皮肤的令牌设置样式。
• 默认使用系统字体。 除非用户的网站已获授权使用网页字体，否则将 --media-font-family 设为系统字体栈；如果选择系统字体而非参考设计中的网页字体，请告知用户。
• 状态不能只靠颜色表达。 同时使用图标变化、标签或形状，并确保当状态播报器未涵盖自定义状态时，通过实时区域播报该状态。