Video.js 怎么实现多清晰度切换菜单

一、理解多清晰度切换的两种底层场景

在开始写代码之前，必须先明确视频源的交付形式。许多人在开发清晰度菜单时遇到各种卡顿或报错，根本原因在于混淆了“独立多源文件切换”与“流式自适应轨道切换”这两类截然不同的底层协议机制：

• 场景 A：独立多源文件（MP4 / WebM）。 服务器端存放了同一视频的不同转码规格文件（如 video_1080p.mp4、video_720p.mp4、video_480p.mp4）。切换清晰度意味着让底层 <video> 元素卸载当前 URL 并重新加载另一个 URL。
• 场景 B：自适应流媒体（HLS / DASH）。 前端只接入一个主索引清单文件（Master Playlist，如 master.m3u8），清单内部声明了不同分辨率与码率的子流。播放器解复用器原生支持分片无缝衔接，切换清晰度只是修改解码管道拉取的分片轨道，不需要卸载播放器源。

二、容易混淆的说法：换清晰度只要换 video 的 src 就行吗？

在前端初学者中，有两种关于清晰度切换的说法流传很广，但它们都存在明显缺陷：

三、方案一：基于 Video.js 组件机制开发多 MP4 清晰度菜单

针对多 MP4 文件场景，最优雅且规范的做法是利用 Video.js 提供的 UI 扩展能力，继承官方的 MenuButton 和 MenuItem 基类。这样可以自动继承键盘无障碍访问、焦点管理以及与控制栏一致的样式布局。

步骤 1：扩展 MenuItem 实现具体的清晰度选项

MenuItem 代表下拉菜单里的单个选项条目。我们需要在点击时触发源切换，并在组件初始化时处理高亮逻辑：

const MenuItem = videojs.getComponent('MenuItem');

class ResolutionMenuItem extends MenuItem {
  constructor(player, options) {
    // 注入 label 与选中状态选项
    super(player, {
      label: options.label,
      selectable: true,
      selected: options.selected || false
    });
    this.src = options.src;
    this.type = options.type || 'video/mp4';
    this.label = options.label;
  }

  handleClick(event) {
    super.handleClick(event);
    // 通知父级按钮或直接触发播放器的自定义事件
    this.player().trigger('resolutionchange', {
      label: this.label,
      src: this.src,
      type: this.type
    });
  }
}

videojs.registerComponent('ResolutionMenuItem', ResolutionMenuItem);

步骤 2：扩展 MenuButton 实现下拉菜单按钮

MenuButton 是控制栏上的图标/文本按钮。当鼠标悬浮或点击时，它会自动展开一个 Menu 容器，里面盛放刚才定义的 ResolutionMenuItem 实例：

const MenuButton = videojs.getComponent('MenuButton');

class ResolutionMenuButton extends MenuButton {
  constructor(player, options) {
    super(player, options);
    // 记录源配置列表与默认分辨率
    this.sources = options.sources || [];
    this.currentLabel = options.defaultLabel || (this.sources[0] && this.sources[0].label) || '清晰度';
    this.updateButtonText();
  }

  createEl() {
    const el = super.createEl();
    // 添加自定义样式类名方便定制外观
    el.classList.add('vjs-resolution-button');
    return el;
  }

  // 构造菜单选项列表
  createItems() {
    const items = [];
    const player = this.player();
    
    this.sources.forEach(item => {
      const menuItem = new ResolutionMenuItem(player, {
        label: item.label,
        src: item.src,
        type: item.type,
        selected: item.label === this.currentLabel
      });
      items.push(menuItem);
    });
    return items;
  }

  // 更新按钮上显示的当前分辨率文字
  updateButtonText(label) {
    if (label) {
      this.currentLabel = label;
    }
    // Video.js MenuButton 内部的 label 元素
    const labelEl = this.el().querySelector('.vjs-menu-button-text') || this.el();
    // 也可以将文字直接写入按钮内容
    this.controlText(this.currentLabel);
  }
}

videojs.registerComponent('ResolutionMenuButton', ResolutionMenuButton);

四、多 MP4 平滑切换的关键状态保留

当用户在菜单中点击不同分辨率时，必须执行平滑切换逻辑。整个过程的关键在于：在换源前保存快照，换源后单次监听 loadedmetadata 事件进行追帧恢复。

下面是标准的平滑切源控制器代码：

function setupSmoothSwitch(player, sources, defaultIndex = 0) {
  let activeSource = sources[defaultIndex];

  // 监听自定义清晰度切换事件
  player.on('resolutionchange', (event, data) => {
    if (data.src === activeSource.src) {
      return; // 点击相同清晰度不重复处理
    }

    // 1. 抓取当前播放器状态快照
    const savedTime = player.currentTime();
    const isPaused = player.paused();

    // 2. 更新活跃源与按钮显示
    activeSource = data;
    const button = player.controlBar.getChild('ResolutionMenuButton');
    if (button) {
      button.updateButtonText(data.label);
      // 更新菜单项的勾选状态
      button.items.forEach(item => {
        item.selected(item.label === data.label);
      });
    }

    // 3. 换源并注册单次 loadedmetadata 监听
    player.src({ src: data.src, type: data.type });

    // 务必使用 player.one() 而非 player.on()，避免多次换源造成监听器泄漏
    player.one('loadedmetadata', () => {
      // 恢复播放进度
      player.currentTime(savedTime);
      
      // 恢复播放或暂停状态
      if (!isPaused) {
        const playPromise = player.play();
        if (playPromise !== undefined) {
          playPromise.catch(err => {
            console.warn('自动恢复播放被浏览器策略阻止：', err);
          });
        }
      }
    });
  });
}

五、方案二：基于 HLS / DASH 的自适应轨道切换

如果业务使用的是 HLS（.m3u8）或 DASH（.mpd），实现多清晰度切换更加高效。因为这些流媒体协议在底层由解复用器分片解析，浏览器只维持一条解码通道。Video.js 官方提供了 videojs-contrib-quality-levels 插件用于管理这些画质轨道。

1. 引入依赖与开启 qualityLevels

<!-- 引入 videojs-contrib-quality-levels 插件 -->
<script src="https://cdn.jsdelivr.net/npm/videojs-contrib-quality-levels@4.1.0/dist/videojs-contrib-quality-levels.min.js"></script>
<!-- 引入成熟的 HLS 清晰度选择器插件（可选） -->
<script src="https://cdn.jsdelivr.net/npm/videojs-hls-quality-selector@2.0.0/dist/videojs-hls-quality-selector.min.js"></script>

2. 原生 QualityLevels API 的工作机制

如果你希望自主掌控 HLS 轨道的切换菜单，可以直接操作 player.qualityLevels() 集合：

// 初始化播放器
const player = videojs('my-video');

// 获取质量等级列表（由 HLS Master Playlist 动态填充）
const qualityLevels = player.qualityLevels();

// 当解析出轨道列表时触发
qualityLevels.on('addqualitylevel', (event) => {
  const level = event.qualityLevel;
  console.log(`发现画质等级: ${level.height}p, 码率: ${level.bitrate} bps`);
});

// 锁定为指定清晰度（例如仅启用 720p 轨道）
function lockToHeight(targetHeight) {
  for (let i = 0; i < qualityLevels.length; i++) {
    const level = qualityLevels[i];
    // 将匹配目标高度的轨道置为 enabled，其余禁用
    level.enabled = (level.height === targetHeight);
  }
}

// 恢复为 Auto（自动自适应模式：允许所有轨道参与算法竞选）
function setAutoQuality() {
  for (let i = 0; i < qualityLevels.length; i++) {
    qualityLevels[i].enabled = true;
  }
}

六、完整可运行示例（纯前端原生组件模式）

下面是一个包含播放器初始化、自定义分辨率组件挂载以及平滑切换状态维护的完整 HTML 示例：

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Video.js 多清晰度演示</title>
  <link href="https://vjs.zencdn.net/8.10.0/video-js.css" rel="stylesheet" />
  <style>
    /* 定制清晰度按钮与弹出菜单样式 */
    .vjs-resolution-button .vjs-menu-content {
      width: 90px;
      left: -20px;
    }
    .vjs-resolution-button .vjs-menu-item.vjs-selected {
      background-color: #8A9478 !important;
      color: #FFFFFF !important;
      font-weight: bold;
    }
  </style>
</head>
<body>
  <video id="example_player" class="video-js vjs-default-skin vjs-big-play-centered" controls preload="auto" width="640" height="360" playsinline></video>

  <script src="https://vjs.zencdn.net/8.10.0/video.min.js"></script>
  <script>
    // 1. 准备多清晰度 MP4 源清单
    const videoSources = [
      { label: '1080P', src: 'https://vjs.zencdn.net/v/oceans.mp4?res=1080', type: 'video/mp4' },
      { label: '720P',  src: 'https://vjs.zencdn.net/v/oceans.mp4?res=720',  type: 'video/mp4' },
      { label: '480P',  src: 'https://vjs.zencdn.net/v/oceans.mp4?res=480',  type: 'video/mp4' }
    ];

    // 2. 注册组件（复用前文定义的 ResolutionMenuButton 与 ResolutionMenuItem）
    // ...

    // 3. 初始化播放器并将按钮注入 controlBar
    const player = videojs('example_player', {
      sources: [videoSources[1]], // 默认 720P
      controlBar: {
        children: [
          'playToggle',
          'volumePanel',
          'currentTimeDisplay',
          'timeDivider',
          'durationDisplay',
          'progressControl',
          'liveDisplay',
          'remainingTimeDisplay',
          'customControlSpacer',
          'playbackRateMenuButton',
          'chaptersButton',
          'descriptionsButton',
          'subsCapsButton',
          'audioTrackButton',
          'fullscreenToggle'
        ]
      }
    }, function() {
      // 动态将清晰度按钮插入在全屏按钮之前
      const fullScreenIndex = this.controlBar.children().indexOf(this.controlBar.getChild('fullscreenToggle'));
      this.controlBar.addChild('ResolutionMenuButton', {
        sources: videoSources,
        defaultLabel: '720P'
      }, fullScreenIndex);

      // 绑定平滑切源
      setupSmoothSwitch(this, videoSources, 1);
    });
  </script>
</body>
</html>

七、方案选型与避坑总结

为了让清晰度菜单在各类复杂终端上稳定运行，需要综合考虑转码架构、网络开销与浏览器特性：