HTMLMediaElement

Baseline 廣泛可用 *

此特性已相當成熟，可在許多裝置和瀏覽器版本上使用。自 ⁨2015 年 7 月⁩以來，各瀏覽器均已提供此特性。

* 此特性的某些部分可能存在不同級別的支援。

HTMLMediaElement 介面在 HTMLElement 的基礎上增加了支援音訊和影片共同的基本媒體相關功能所需的屬性和方法。

HTMLVideoElement 和 HTMLAudioElement 元素都繼承了此介面。

例項屬性

此介面還繼承了其祖先 HTMLElement、Element、Node 和 EventTarget 的屬性。

HTMLMediaElement.audioTracks 只讀: 一個 AudioTrackList，列出了元素中包含的 AudioTrack 物件。
HTMLMediaElement.autoplay: 一個布林值，反映了 autoplay HTML 屬性，指示一旦有足夠的媒體可用，播放是否應自動開始而不中斷。

注意：在使用者不期望或不希望的情況下自動播放音訊會帶來糟糕的使用者體驗，在大多數情況下應避免，儘管也有例外。有關更多資訊，請參閱媒體和 Web 音訊 API 的自動播放指南。請記住，瀏覽器可能會忽略自動播放請求，因此您應確保您的程式碼不依賴於自動播放的正常工作。
HTMLMediaElement.buffered 只讀: 返回一個 TimeRanges 物件，該物件指示在訪問 buffered 屬性時瀏覽器已緩衝的媒體源範圍（如果有）。
HTMLMediaElement.controls: 一個布林值，反映了 controls HTML 屬性，指示是否應顯示用於控制資源的 UI 元素。
HTMLMediaElement.controlsList: 返回一個 DOMTokenList，它有助於使用者代理選擇當用戶代理顯示其自己的控制元件集時在媒體元素上顯示哪些控制元件。DOMTokenList 接受三個可能值中的一個或多個：nodownload、nofullfullscreen 和 noremoteplayback。
HTMLMediaElement.crossOrigin: 一個字串，指示此媒體元素的 CORS 設定。
HTMLMediaElement.currentSrc 只讀: 返回一個字串，其中包含所選媒體資源的絕對 URL。
HTMLMediaElement.currentTime: 一個雙精度浮點值，指示當前播放時間（秒）；如果媒體尚未開始播放且未進行查詢，則此值為媒體的初始播放時間。設定此值會將媒體查詢至新時間。時間是相對於媒體時間線指定的。
HTMLMediaElement.defaultMuted: 一個布林值，反映了 muted HTML 屬性，指示媒體元素的音訊輸出是否應預設靜音。
HTMLMediaElement.defaultPlaybackRate: 一個 double，指示媒體的預設播放速率。
HTMLMediaElement.disableRemotePlayback: 一個布林值，用於設定或返回遠端播放狀態，指示媒體元素是否允許具有遠端播放 UI。
HTMLMediaElement.duration 只讀: 一個只讀雙精度浮點值，指示媒體的總時長（秒）。如果沒有媒體資料可用，則返回值為 NaN。如果媒體長度不確定（例如直播流媒體、WebRTC 通話媒體或類似情況），則該值為 Infinity。
HTMLMediaElement.ended 只讀: 返回一個布林值，指示媒體元素是否已播放完畢。
HTMLMediaElement.error 只讀: 返回一個 MediaError 物件，表示最近的錯誤，如果未發生錯誤，則為 null。
HTMLMediaElement.loop: 一個布林值，反映了 loop HTML 屬性，指示媒體元素在到達末尾時是否應重新開始。
HTMLMediaElement.mediaKeys 只讀安全上下文: 返回一個 MediaKeys 物件，這是一組元素在播放期間用於解密媒體資料的金鑰。如果沒有金鑰可用，則可以為 null。
HTMLMediaElement.muted: 一個布林值，指示音訊是否靜音。如果音訊靜音，則為 true，否則為 false。
HTMLMediaElement.networkState 只讀: 返回一個 unsigned short（列舉），指示透過網路獲取媒體的當前狀態。
HTMLMediaElement.paused 只讀: 返回一個布林值，指示媒體元素是否已暫停。
HTMLMediaElement.playbackRate: 一個 double，指示媒體的播放速率。
HTMLMediaElement.played 只讀: 返回一個 TimeRanges 物件，其中包含瀏覽器已播放的媒體源範圍（如果有）。
HTMLMediaElement.preload: 一個字串，反映了 preload HTML 屬性，指示應預載入哪些資料（如果有）。可能的值有：none、metadata、auto。
HTMLMediaElement.preservesPitch: 一個布林值，指示是否保留音高。如果設定為 false，則音高將根據音訊速度進行調整。
HTMLMediaElement.readyState 只讀: 返回一個 unsigned short（列舉），指示媒體的就緒狀態。
HTMLMediaElement.remote 只讀: 返回與媒體元素關聯的 RemotePlayback 物件例項。
HTMLMediaElement.seekable 只讀: 返回一個 TimeRanges 物件，其中包含使用者可以查詢的時間範圍（如果有）。
HTMLMediaElement.seeking 只讀: 返回一個布林值，指示媒體是否正在查詢新位置。
HTMLMediaElement.sinkId 只讀安全上下文: 返回一個字串，表示提供輸出的音訊裝置的唯一 ID，如果正在使用使用者代理預設音訊裝置，則返回一個空字串。
HTMLMediaElement.src: 一個字串，反映了 src HTML 屬性，其中包含要使用的媒體資源的 URL。
HTMLMediaElement.srcObject: 一個物件，作為與 HTMLMediaElement 關聯的媒體的源，如果未分配，則為 null。
HTMLMediaElement.textTracks 只讀: 返回一個 TextTrackList 物件，其中包含元素中包含的 TextTrack 物件的列表。
HTMLMediaElement.videoTracks 只讀: 返回一個 VideoTrackList 物件，其中包含元素中包含的 VideoTrack 物件的列表。
HTMLMediaElement.volume: 一個 double，指示音量，從 0.0（靜音）到 1.0（最大聲）。

已廢棄的屬性

這些屬性已廢棄，即使瀏覽器仍然支援它們，也不應使用。

HTMLMediaElement.controller 已廢棄非標準: 一個 MediaController 物件，表示分配給元素的媒體控制器，如果未分配，則為 null。
HTMLMediaElement.mediaGroup 已廢棄非標準: 一個字串，反映了 mediagroup HTML 屬性，指示其所屬組的名稱。一組媒體元素共享一個共同的 MediaController。
HTMLMediaElement.mozAudioCaptured 只讀非標準已廢棄: 返回一個布林值。與音訊流捕獲相關。
HTMLMediaElement.mozFragmentEnd 非標準已廢棄: 一個 double，如果媒體元素的 currentSrc 具有片段 URI，則提供對片段結束時間的訪問，否則它等於媒體時長。

例項方法

此介面還繼承了其祖先 HTMLElement、Element、Node 和 EventTarget 的方法。

HTMLMediaElement.addTextTrack(): 向媒體元素新增新的 TextTrack 物件（例如字幕軌道）。這僅是程式設計介面，不影響 DOM。
HTMLMediaElement.captureStream(): 返回 MediaStream，捕獲媒體內容的流。
HTMLMediaElement.canPlayType(): 給定一個指定 MIME 媒體型別（可能包含 codecs 引數）的字串，canPlayType() 返回字串 probably（如果媒體應該可播放），maybe（如果沒有足夠的資訊來確定媒體是否會播放），或者一個空字串（如果媒體無法播放）。
HTMLMediaElement.fastSeek(): 以低精度快速查詢給定時間。
HTMLMediaElement.load(): 將媒體重置到開頭，並從使用 src 屬性或 <source> 元素提供的源中選擇最佳可用源。
HTMLMediaElement.pause(): 暫停媒體播放。
HTMLMediaElement.play(): 開始播放媒體。
HTMLMediaElement.seekToNextFrame() 已廢棄非標準: 查詢媒體中的下一幀。此非標準、實驗性方法使得可以以自定義速度手動驅動媒體的讀取和渲染，或者逐幀移動媒體以執行過濾或其他操作。
HTMLMediaElement.setMediaKeys() 安全上下文: 返回 Promise。設定在播放期間解密媒體時要使用的 MediaKeys 金鑰。
HTMLMediaElement.setSinkId() 安全上下文: 設定用於輸出的音訊裝置的 ID 並返回一個 Promise。這僅在應用程式被授權使用指定裝置時有效。

已廢棄的方法

這些方法已廢棄，即使瀏覽器仍然支援它們，也不應使用。

HTMLMediaElement.mozCaptureStream() 非標準: 帶有 Firefox 字首的 HTMLMediaElement.captureStream() 等效方法。有關詳細資訊，請參閱其瀏覽器相容性。
HTMLMediaElement.mozCaptureStreamUntilEnded() 非標準已廢棄: [輸入描述]
HTMLMediaElement.mozGetMetadata() 非標準已廢棄: 返回 Object，其中包含表示來自正在播放的媒體資源的元資料作為 {key: value} 對的屬性。每次呼叫此方法時都會返回資料的單獨副本。此方法必須在 loadedmetadata 事件觸發後呼叫。

事件

繼承自其父級 HTMLElement 的事件.

使用 addEventListener() 監聽這些事件，或透過將事件監聽器分配給此介面的 oneventname 屬性。

abort: 當資源未完全載入但並非由於錯誤而觸發。
canplay: 當用戶代理可以播放媒體，但估計沒有載入足夠的資料以播放媒體直到結束而無需停止進一步緩衝內容時觸發。
canplaythrough: 當用戶代理可以播放媒體，並且估計已載入足夠的資料以播放媒體直到結束而無需停止進一步緩衝內容時觸發。
durationchange: 當 duration 屬性已更新時觸發。
emptied: 當媒體變空時觸發；例如，當媒體已載入（或部分載入），並且呼叫 HTMLMediaElement.load() 方法重新載入它時。
encrypted: 當在媒體中發現指示媒體已加密的初始化資料時觸發。
ended: 當播放停止時觸發，因為媒體（<audio> 或 <video>）已結束或因為沒有更多資料可用。
error: 當資源由於錯誤而無法載入時觸發。
loadeddata: 當媒體的第一幀載入完成時觸發。
loadedmetadata: 當元資料已載入時觸發。
loadstart: 當瀏覽器開始載入資源時觸發。
pause: 當處理暫停播放請求並且活動已進入其暫停狀態時觸發，最常見的情況是呼叫媒體的 HTMLMediaElement.pause() 方法時。
play: 當 paused 屬性從 true 更改為 false 時觸發，這是由 HTMLMediaElement.play() 方法或 autoplay 屬性引起的。
playing: 當播放因資料不足而暫停或延遲後準備開始時觸發。
progress: 當瀏覽器載入資源時定期觸發。
ratechange: 當播放速率發生變化時觸發。
seeked: 當查詢操作完成時觸發。
seeking: 當查詢操作開始時觸發。
stalled: 當用戶代理嘗試獲取媒體資料，但資料意外地沒有到來時觸發。
suspend: 當媒體資料載入已暫停時觸發。
timeupdate: 當由 currentTime 屬性指示的時間已更新時觸發。
volumechange: 當音量發生變化時觸發。
waiting: 當播放因資料暫時不足而停止時觸發。
waitingforkey: 當播放首次因等待金鑰而被阻止時觸發。

規範

規範
HTML # htmlmediaelement

瀏覽器相容性

另見

參考

<video> 和 <audio> HTML 元素
HTMLVideoElement 和 HTMLAudioElement 介面，派生自 HTMLMediaElement

指南

幫助改進 MDN

瞭解如何貢獻

此頁面上次修改於 2025 年 9 月 4 日由 MDN 貢獻者。

在 GitHub 上檢視此頁面 • 報告此內容的問題