HTMLMediaElement: play() 方法

Baseline 已广泛支持

此特性已相当成熟，可在许多设备和浏览器版本上使用。自 ⁨2015 年 7 月⁩以来，各浏览器均已提供此特性。

HTMLMediaElement 的 play() 方法尝试开始媒体播放。它返回一个 Promise，当播放成功开始时，该 Promise 会被解析。

由于任何原因（例如权限问题）导致无法开始播放，Promise 会被拒绝。

语法

play()

返回值

当播放开始时，会解析一个 Promise；如果由于任何原因无法开始播放，则会拒绝该 Promise。

注意： 2019 年之前发布的浏览器可能不会从 play() 返回值。

异常

Promise 的 **rejection handler** 会被调用，并传入一个 DOMException 对象作为其唯一的输入参数（而不是抛出传统的异常）。可能出现的错误包括：

NotAllowedError DOMException: 如果用户代理（浏览器）或操作系统不允许在当前上下文或情况下播放媒体，则会提供此错误。浏览器可能要求用户通过点击“播放”按钮来显式开始播放媒体，例如，这是由于 Permissions Policy。
NotSupportedError DOMException: 如果媒体源（可能指定为 MediaStream、MediaSource、Blob 或 File 等）不代表受支持的媒体格式，则会提供此错误。

根据浏览器实现细节、媒体播放器实现等，可能会报告其他异常。

用法说明

虽然“自动播放”一词通常指的是页面加载后立即开始播放媒体的内容，但 Web 浏览器的自动播放策略也适用于任何脚本启动的媒体播放，包括对 play() 的调用。

如果用户代理配置为不允许自动播放或脚本启动的媒体播放，则调用 play() 会导致返回的 Promise 立即被拒绝，并带有 NotAllowedError。网站应准备好处理这种情况。例如，网站不应呈现假定媒体已自动开始播放的用户界面，而应根据返回的 Promise 是被fulfilled 还是 rejected 来更新其 UI。有关更多信息，请参阅下面的示例。

注意： play() 方法可能会导致用户被要求授予播放媒体的权限，从而在返回的 Promise 被解析之前可能出现延迟。请确保您的代码不期望立即响应。

有关自动播放和自动播放阻止的更深入信息，请参阅我们的文章媒体和 Web 音频 API 的自动播放指南。

示例

确认播放和处理状态

此示例演示了如何确认播放已开始以及如何优雅地处理被阻止的自动播放。

当执行此示例时，它首先收集对 <video> 元素以及用于切换播放状态的 <button> 的引用。然后，它为切换按钮上的 click 事件设置事件处理程序，并通过调用 async playVideo() 函数来尝试自动开始播放。

一个名为 toggleButton() 的辅助函数允许我们定义当传递一个布尔值来表示播放状态时（例如，toggleButton(true)）代码中应该发生什么。如果播放成功，按钮文本及其 aria-label 会更改为“Pause”。如果播放失败，按钮和 aria-label 会显示“Play”。这可确保 playButton 与播放状态匹配，方法是监听 play() 返回的 Promise 的解析或拒绝。

html

<div class="video-box">
  <video
    id="video"
    width="480"
    loop
    src="/shared-assets/videos/flower.mp4"></video>
  <button type="button" id="play-button" aria-label="Play"></button>
</div>

let videoElem = document.getElementById("video");
let playButton = document.getElementById("play-button");

playButton.addEventListener("click", handlePlayButton);
playVideo();

function toggleButton(playing) {
  if (playing) {
    playButton.textContent = "Pause";
    playButton.setAttribute("aria-label", "Pause");
  } else {
    playButton.textContent = "Play";
    playButton.setAttribute("aria-label", "Play");
  }
}

async function playVideo() {
  try {
    await videoElem.play();
    toggleButton(true);
  } catch (err) {
    toggleButton(false);
  }
}

function handlePlayButton() {
  if (videoElem.paused) {
    playVideo();
  } else {
    videoElem.pause();
    toggleButton(false);
  }
}

.video-box {
  position: relative;
}

#video {
  border: 2px solid black;
}

#play-button {
  position: absolute;
  top: 10px;
  left: 10px;
  padding: 8px 12px;
  background-color: black;
  color: white;
  border: none;
  cursor: pointer;
}

规范

规范
HTML # dom-media-play-dev

浏览器兼容性

另见

帮助改进 MDN

了解如何贡献

此页面最后由 MDN 贡献者于 2025 年 9 月 18 日修改。

在 GitHub 上查看此页面 • 报告此内容的错误