如何在 React Web 项目中用 JavaScript 播放和暂停视频？

2026-11-04数据阿明

在 React 中，可以用 useRef 获取原生 <video> 元素的引用，再调用 play() 和 pause() 控制播放和暂停。VS Code 是代码编辑器，视频控制逻辑运行在浏览器中。

为什么要使用 useRef？

play() 和 pause() 是浏览器视频元素提供的方法。React 的 useRef 可以保存元素的引用，让按钮的点击事件访问它。

调用 play() 会返回一个 Promise。播放请求可能因浏览器播放策略或媒体资源问题而失败，因此需要处理异常。pause() 可以直接调用，无需 await。

完整示例

这个组件包含视频、播放和暂停按钮，以及播放失败时的提示：

import { useRef, useState } from 'react';

export default function VideoPlayer() {
  const videoRef = useRef(null);
  const [error, setError] = useState('');

  async function handlePlay() {
    const video = videoRef.current;
    if (!video) return;

    setError('');

    try {
      await video.play();
    } catch (err) {
      setError('视频未能开始播放，请检查视频地址和浏览器控制台。');
      console.error('Video playback failed:', err);
    }
  }

  function handlePause() {
    videoRef.current?.pause();
  }

  return (
    <div>
      <video
        ref={videoRef}
        src="/sample.mp4"
        controls
        width={640}
        style={{ maxWidth: '100%' }}
      />

      <div>
        <button type="button" onClick={handlePlay}>
          播放
        </button>
        <button type="button" onClick={handlePause}>
          暂停
        </button>
      </div>

      {error && <p role="alert">{error}</p>}
    </div>
  );
}

将 /sample.mp4 替换为项目中可以访问的视频 URL。这个路径指向网站根路径下的资源，本地文件的存放位置取决于项目的构建工具和静态资源配置。

ref={videoRef} 让 React 在元素挂载后将对应的 DOM 元素赋给 videoRef.current。点击按钮时，事件处理函数就能通过这个引用调用视频方法。调用前检查引用是否存在，可以避免在元素不可用时调用方法。

只需要基本控制时，可以使用 controls

如果只需要让用户手动播放、暂停和拖动进度条，直接使用浏览器自带的控制栏即可：

export default function VideoPlayer() {
  return <video src="/sample.mp4" controls />;
}

需要自定义按钮时，可以使用前面的 useRef 方案。示例同时保留了 controls 和自定义按钮，也可以根据界面需求去掉 controls。

播放失败或按钮没有效果时检查什么？

视频地址是否可访问：检查浏览器 Network 面板中的视频请求，确认没有 404 等错误。文件系统路径不能直接用作网站资源 URL。
媒体是否受浏览器支持：文件扩展名不能保证视频可播放，浏览器还需要支持对应的容器和编码格式。
调用是否来自用户操作：直接在按钮点击事件中调用 play() 是常见做法。如果改为页面加载后自动播放，可能受到浏览器自动播放策略的限制。
事件是否绑定正确：使用 onClick={handlePlay}，不要写成 `onClick={handlePlay()}“；后者会在渲染时执行函数。

暂停后会保留当前播放位置，再次调用 play() 会从该位置继续播放。如需回到开头，可以在暂停后重置播放位置：

const video = videoRef.current;

if (video) {
  video.pause();
  video.currentTime = 0;
}