从零打造：如何封装一个优雅的自定义视频播放器？-CSDN博客

💡 前言

你是否厌倦了浏览器默认的“丑”播放条？

“我想做一个像 Bilibili 或 YouTube 那样精致的播放器。”
“我想在进度条上显示预览图，或者自定义倍速菜单。”
“为什么我写的 play() 没反应？状态怎么同步？”

封装播放器的核心难点不在于 UI，而在于如何将原生 Video DOM 的事件与框架的状态（State）完美同步。

今天，我们将抛开框架差异，提炼出一套通用的播放器架构设计模式，并给出 Vue 和 React 的关键代码实现。

1. 核心架构：分离关注点 🏗️

无论使用 Vue 还是 React，一个优秀的播放器组件都应遵循 “数据驱动 UI” 的原则。我们需要将播放器拆分为两个部分：

逻辑层 (Logic/Hook)：负责与原生 <video> 元素交互，监听事件，维护状态（播放/暂停、进度、音量等）。
视图层 (UI/Component)：只负责渲染界面（按钮、进度条、遮罩），并根据状态展示不同的样式。

🔄 数据流向图

2. 核心状态与方法定义 📋

在写代码之前，先明确我们需要管理哪些状态（State）和暴露哪些方法（Methods）。

📊 核心状态 (State)

状态名	类型	说明
`isPlaying`	Boolean	是否正在播放
`currentTime`	Number	当前播放时间（秒）
`duration`	Number	视频总时长（秒）
`volume`	Number	音量 (0-1)
`isMuted`	Boolean	是否静音
`buffered`	Number	已缓冲进度 (0-1)
`isLoading`	Boolean	是否正在缓冲/加载

🛠️ 核心方法 (API)

方法名	说明
`play()`	播放
`pause()`	暂停
`seek(time)`	跳转到指定时间
`setVolume(val)`	设置音量
`toggleMute()`	切换静音
`setPlaybackRate(rate)`	设置倍速

3. 关键技术点实现 💻

关键点一：如何获取视频时长和进度？

原生 <video> 标签通过事件通知状态变化。我们需要监听以下关键事件：

loadedmetadata: 元数据加载完成，此时可以获取 video.duration。
timeupdate: 播放位置改变，高频触发，用于更新进度条。注意性能优化。
progress: 缓冲进度更新，用于显示灰色缓冲条。
waiting / canplay: 用于显示/隐藏 Loading 动画。

关键点二：进度条的拖拽与防抖

timeupdate 每秒触发约 4-250 次。如果每次更新都触发 React/Vue 的重渲染，性能会爆炸。

React: 使用 requestAnimationFrame 或 lodash 的 throttle 来限制状态更新频率。
Vue: 可以使用 .lazy 修饰符或在 watch 中进行节流处理。

关键点三：格式化时间

需要将秒数转换为 MM:SS 或 HH:MM:SS 格式。

function formatTime(seconds) {
  if (!seconds || isNaN(seconds)) return "00:00";
  const h = Math.floor(seconds / 3600);
  const m = Math.floor((seconds % 3600) / 60);
  const s = Math.floor(seconds % 60);

  const pad = (num) => num.toString().padStart(2, "0");

  if (h > 0) {
    return `${pad(h)}:${pad(m)}:${pad(s)}`;
  }
  return `${pad(m)}:${pad(s)}`;
}

4. 框架实战示例 🚀

方案 A：React Hooks 实现 (`useVideoPlayer`)

利用 Custom Hook 隔离逻辑，使组件更纯净。

import { useState, useRef, useEffect, useCallback } from "react";

// 1. 自定义 Hook：封装逻辑
export function useVideoPlayer(src) {
  const videoRef = useRef(null);
  const [state, setState] = useState({
    isPlaying: false,
    currentTime: 0,
    duration: 0,
    volume: 1,
    isMuted: false,
  });

  // 播放/暂停
  const togglePlay = useCallback(() => {
    const video = videoRef.current;
    if (!video) return;
    if (video.paused) {
      video.play();
    } else {
      video.pause();
    }
  }, []);

  // 跳转
  const seek = useCallback((time) => {
    if (videoRef.current) {
      videoRef.current.currentTime = time;
    }
  }, []);

  // 监听原生事件，同步状态
  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;

    const handleTimeUpdate = () => {
      setState((prev) => ({ ...prev, currentTime: video.currentTime }));
    };

    const handleLoadedMetadata = () => {
      setState((prev) => ({ ...prev, duration: video.duration }));
    };

    const handlePlay = () => setState((prev) => ({ ...prev, isPlaying: true }));
    const handlePause = () =>
      setState((prev) => ({ ...prev, isPlaying: false }));

    video.addEventListener("timeupdate", handleTimeUpdate);
    video.addEventListener("loadedmetadata", handleLoadedMetadata);
    video.addEventListener("play", handlePlay);
    video.addEventListener("pause", handlePause);

    return () => {
      video.removeEventListener("timeupdate", handleTimeUpdate);
      video.removeEventListener("loadedmetadata", handleLoadedMetadata);
      video.removeEventListener("play", handlePlay);
      video.removeEventListener("pause", handlePause);
    };
  }, [src]);

  return { videoRef, state, togglePlay, seek };
}

// 2. UI 组件
export default function VideoPlayer({ src }) {
  const { videoRef, state, togglePlay, seek } = useVideoPlayer(src);

  return (
    <div className="player-container">
      <video
        ref={videoRef}
        src={src}
        onClick={togglePlay}
        className="video-element"
      />

      {/* 自定义控制栏 */}
      <div className="controls">
        <button onClick={togglePlay}>{state.isPlaying ? "⏸" : "▶"}</button>

        <input
          type="range"
          min="0"
          max={state.duration || 100}
          value={state.currentTime}
          onChange={(e) => seek(Number(e.target.value))}
        />

        <span>
          {formatTime(state.currentTime)} / {formatTime(state.duration)}
        </span>
      </div>
    </div>
  );
}

方案 B：Vue 3 Composition API 实现 (`useVideoPlayer`)

Vue 的响应式系统让状态同步变得更加直观。

<template>
  <div class="player-container">
    <video
      ref="videoRef"
      :src="src"
      @click="togglePlay"
      @timeupdate="onTimeUpdate"
      @loadedmetadata="onLoadedMetadata"
      @play="isPlaying = true"
      @pause="isPlaying = false"
      class="video-element"
    />

    <!-- 自定义控制栏 -->
    <div class="controls">
      <button @click="togglePlay">
        {{ isPlaying ? "⏸" : "▶" }}
      </button>

      <input type="range" :max="duration" :value="currentTime" @input="seek" />

      <span>{{ formatTime(currentTime) }} / {{ formatTime(duration) }}</span>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from "vue";

const props = defineProps(["src"]);

const videoRef = ref(null);
const isPlaying = ref(false);
const currentTime = ref(0);
const duration = ref(0);

const togglePlay = () => {
  const video = videoRef.value;
  if (video.paused) {
    video.play();
  } else {
    video.pause();
  }
};

const onTimeUpdate = () => {
  // Vue 响应式更新，注意频繁更新可能带来的性能开销
  // 生产环境建议加 throttle
  currentTime.value = videoRef.value.currentTime;
};

const onLoadedMetadata = () => {
  duration.value = videoRef.value.duration;
};

const seek = (event) => {
  videoRef.value.currentTime = event.target.value;
};

// 工具函数
const formatTime = (seconds) => {
  if (!seconds) return "00:00";
  const m = Math.floor(seconds / 60);
  const s = Math.floor(seconds % 60);
  return `${m.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}`;
};
</script>

5. 进阶功能：如何让播放器更专业？🌟

点击区域区分：
- 点击视频中心：播放/暂停。
- 双击视频：全屏切换。
- 左侧双击：快退 10s；右侧双击：快进 10s。
键盘快捷键支持：
- 空格键：播放/暂停。
- 左右箭头：快进/快退 5s。
- 上下箭头：调节音量。
- F键：全屏。
弹幕集成：
- 在视频上层覆盖一个绝对定位的 canvas 或 div 层，根据 currentTime 渲染弹幕。
HLS/FLV 支持：
- 如果播放直播流，需在 videoRef 初始化后，集成 hls.js 或 flv.js，将流挂载到 video 元素上。

6. 常见坑与优化建议 ⚠️

内存泄漏：
- 在组件卸载（unmounted / useEffect cleanup）时，务必移除所有事件监听器，并调用 video.pause() 和 video.src = '' 释放资源。
自动播放策略：
- 记得处理 play() 返回的 Promise，捕获 NotAllowedError，并在失败时显示播放按钮。
全屏兼容性：
- 不同浏览器的全屏 API 前缀不同（requestFullscreen, webkitRequestFullscreen 等）。建议使用成熟的库如 screenfull.js 来处理兼容性。
移动端手势：
- 移动端需要处理 touchstart / touchmove 来实现滑动调节音量和亮度，这与 PC 端的鼠标事件不同。

7. 总结记忆口诀 🧠

原生 Video 做内核，自定义 UI 盖上层。
状态同步靠事件，TimeUpdate 刷进度。
React Hook 抽逻辑，Vue Ref 绑 DOM 树。
节流防抖不能少，性能优化是关键。
全屏快捷键配好，用户体验翻倍升。
卸载清理内存漏，优雅封装显功底。

希望这篇文档能帮你理清自定义播放器的封装思路！如果觉得有用，欢迎点赞收藏～ 🌟