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 上檢視此頁面 • 報告此內容的錯誤