企业官网建设流程全解析

• 前端
• UI组件

本篇技术指南围绕 Metro UI CSS 框架中的 Video Player 组件展开，介绍如何通过data-role="video-player"声明式语法快速构建具备音量、进度、全屏、自定义宽高比等完整控制能力的 HTML5 视频播放器。读完本文，你将掌握该组件的全部配置参数、API 方法、事件回调、全局配置方式，并能结合 组件源码 理解其底层实现原理，直接应用到自己的页面中。

组件定位与依赖关系

Video Player 是一个基于原生 HTML5<video>元素的封装组件，提供定制化播放能力：音量调节、播放控制、全屏模式、自定义宽高比以及 Logo 叠加等。从 组件入口文件 可以看到它的启动依赖：

import "../media-player/index.js"; import "../slider/index.js"; import "../button/index.js"; import "./video-player.less"; import "./video-player.js";

结合 官方 README 的说明，该组件依赖以下模块：

• Metro UI Core：框架核心运行时，提供组件注册、插件获取等基础设施；
• Metro Slider 组件：用于渲染进度条（stream）与音量条（volume）的滑动条控件；
• Metro Activity 组件：用于加载缓冲期间的 preloader 指示器；
• Metro Button 组件：控制条上的循环、播放、停止、静音、全屏按钮。

实际使用前，请确保页面已引入 lib/metro.css 与 lib/metro.js（见 示例页面），并在 HTML 中引入<video><video><video><video>const player = Metro.getPlugin('#my-video', 'video-player'); player.play(); // 播放当前视频 player.play("new-video.mp4"); // 更换源并播放 player.setVolume(0.8); // 设置音量为 80%

事件系统

组件初始化后暴露以下回调事件（源码中均通过Metro.utils.exec触发，回调参数为video、player等，见 video-player.js）：

这些事件与底层 HTML5 媒体事件一一对应：play、pause、stop、ended、loadedmetadata、timeupdate，组件在_createEvents中统一监听并转发。onTime回调还会同步驱动进度条位置（按currentTime / duration计算百分比）与时间信息显示。

CSS 变量与样式定制

组件通过 CSS 变量暴露主题化入口，默认在:root上声明（见 video-player.less）：

示例：为指定播放器自定义背景色：

#my-video-player { --player-wrapper-background: #1a1a1a; }

可用的 CSS 类

基础类

• .video-player：组件主容器类；
• .video-wrapper：视频元素容器；
• .controls：播放控制条容器。

修饰类

• .full-screen：播放器处于全屏模式时应用（在WINDOW全屏模式下通过addClass("full-screen")添加，见 video-player.js）。

从 video-player.less 可以看出，.video-player使用 flex 纵向布局，.controls通过margin-top: auto被推向底部；.full-screen模式下.video-wrapper会被绝对定位并垂直居中。

全局配置

可通过Metro.videoPlayerSetup(options)为所有播放器设置全局默认值，该函数会把传入的配置对象合并进默认配置（见 video-player.js）：

Metro.videoPlayerSetup({ aspectRatio: Metro.aspectRatio.SD, volume: 0.8, autoplay: true });

另外，源码中还会读取globalThis.metroVideoPlayerSetup变量：若在引入metro.js之前已定义该全局对象，组件会自动应用其中的配置（见 video-player.js），这为在框架加载前注入全局配置提供了入口。

宽高比与全屏模式常量

宽高比常量

三个常量定义在 core/props.js：

• Metro.aspectRatio.HD—"hd"，16:9（默认）；
• Metro.aspectRatio.SD—"sd"，4:3；
• Metro.aspectRatio.CINEMA—"cinema"，21:9。

在_setAspectRatio中，组件根据当前播放器宽度调用Metro.utils.aspectRatioH(width, "16/9" | "4/3" | "21/9")计算并设置高度（见 video-player.js），并在窗口resize时自动重新计算以保持比例。

全屏模式常量

同样定义于 core/props.js：

• Metro.fullScreenMode.DESKTOP—"desktop"，使用浏览器原生 Fullscreen API（默认）；
• Metro.fullScreenMode.WINDOW—"window"，让播放器填满其容器（仅切换.full-screen类）。

需要说明：若浏览器不支持原生全屏（即Metro.fullScreenEnabled === false，见 core/metro.js），组件会自动回退为WINDOW模式（video-player.js）。在DESKTOP模式下，全屏切换会调用Metro.requestFullScreen(video)/Metro.exitFullScreen()，并通过Metro.inFullScreen()以 1 秒间隔轮询监听退出状态以同步按钮图标（core/metro.js）；同时注册全局keyup监听，按Esc键退出全屏（video-player.js）。

多源播放完整示例

为兼容不同浏览器，可一次提供多种编码格式。HTML 方式：

<video>Metro.getPlugin("#my-video", "video-player").play([ {src: "video.mp4", type: "video/mp4"}, {src: "video.webm", type: "video/webm"} ]);

实测示例与运行验证

仓库提供了可直接运行的 video-player.html 示例页面（引用 examples/data/ocean.mp4 作为视频源，并通过data-full-screen-mode="desktop"启用桌面全屏），同时配套的 tests/video-player.test.js 测试用例会通过自动化测试框架加载该页面进行回归验证。你可以直接打开示例页面观察组件行为，再结合本文的参数表按需调整。

小结

Video Player 组件将 Metro UI CSS 的声明式data-role语法与 HTML5 媒体 API 相结合，核心要点可归纳为：

1. 以<video>赞分享