<video>: 影片嵌入元素

試一試

<video controls width="250">
  <source src="/shared-assets/videos/flower.webm" type="video/webm" />

  <source src="/shared-assets/videos/flower.mp4" type="video/mp4" />

  Download the
  <a href="/shared-assets/videos/flower.webm">WEBM</a>
  or
  <a href="/shared-assets/videos/flower.mp4">MP4</a>
  video.
</video>

上面的示例展示瞭如何使用 <video> 元素。與 <img> 元素類似，我們在 src 屬性中包含要顯示的媒體路徑；我們可以包含其他屬性來指定資訊，例如影片的寬度和高度，是否希望它自動播放和迴圈，或者顯示瀏覽器的預設影片控制元件等等。

在開標籤和閉標籤 <video></video> 之間的內容會作為不支援該元素的瀏覽器中的備用內容顯示。

屬性

與所有其他 HTML 元素一樣，此元素支援全域性屬性。

autoplay

一個布林屬性；如果指定，影片將一能播放就自動開始播放，而無需停止以完成資料載入。

注意：現代瀏覽器會阻止音訊（或帶有未靜音音軌的影片）自動播放，因為自動播放音訊的網站可能會給使用者帶來不愉快的體驗。有關如何正確使用自動播放的更多資訊，請參閱我們的自動播放指南。

要停用影片自動播放，autoplay="false" 將不起作用；如果 <video> 標籤中存在該屬性，影片將自動播放。要移除自動播放，需要完全移除該屬性。

controls

如果此屬性存在，瀏覽器將提供控制元件，允許使用者控制影片播放，包括音量、快進/快退以及暫停/恢復播放。

controlslist

當指定 controlslist 屬性時，它有助於瀏覽器選擇在瀏覽器顯示自己的控制元件集（即，指定了 controls 屬性時）時，為 video 元素顯示哪些控制元件。

允許的值為 nodownload、nofullscreen 和 noremoteplayback。

如果想停用畫中畫模式（和控制元件），請使用 disablepictureinpicture 屬性。

crossorigin

此列舉屬性指示是否使用 CORS 獲取相關的影片。支援 CORS 的資源可以在 <canvas> 元素中重複使用而不會被汙染。允許的值為

anonymous

傳送不帶憑據的跨域請求。換句話說，它傳送 Origin: HTTP 頭，但不帶 cookie、X.509 證書或執行 HTTP Basic 身份驗證。如果伺服器不向源站點提供憑據（透過不設定 Access-Control-Allow-Origin: HTTP 頭），則資源將被汙染，其使用將受到限制。

use-credentials

傳送帶憑據的跨域請求。換句話說，它傳送 Origin: HTTP 頭，帶 cookie、證書或執行 HTTP Basic 身份驗證。如果伺服器不向源站點提供憑據（透過 Access-Control-Allow-Credentials: HTTP 頭），則資源將被汙染，其使用將受到限制。

如果不存在，則在沒有 CORS 請求的情況下（即，不傳送 Origin: HTTP 頭）獲取資源，從而阻止其在 <canvas> 元素中不被汙染地使用。如果無效，則按使用列舉關鍵字 anonymous 處理。有關更多資訊，請參閱 CORS 設定屬性。

disablepictureinpicture

阻止瀏覽器在某些情況下建議畫中畫上下文選單或自動請求畫中畫。

disableremoteplayback

一個布林屬性，用於停用透過有線（HDMI、DVI 等）和無線技術（Miracast、Chromecast、DLNA、AirPlay 等）連線的裝置中的遠端播放功能。

在 Safari 中，你可以使用 x-webkit-airplay="deny" 作為備用方案。

height

影片顯示區域的高度，以 CSS 畫素為單位（僅限絕對值；無百分比）。

loop

一個布林屬性；如果指定，瀏覽器將在影片播放結束時自動重新播放。

muted

一個布林屬性，指示影片中包含的預設音訊靜音設定。如果設定，音訊將最初靜音。其預設值為 false，表示影片播放時將播放音訊。

playsinline

一個布林屬性，指示影片應“內聯”播放，即在元素的播放區域內播放。請注意，缺少此屬性並不意味著影片將始終全屏播放。

poster

影片下載時要顯示的圖片 URL。如果未指定此屬性，則在第一個幀可用之前不顯示任何內容，然後顯示第一個幀作為海報幀。

preload

此列舉屬性旨在向瀏覽器提供一個提示，說明作者認為哪種內容載入方式能在影片播放前帶來最佳的使用者體驗。它可能具有以下值之一

• none：表示影片不應預載入。
• metadata：表示僅獲取影片元資料（例如，長度）。
• auto：表示可以下載整個影片檔案，即使預計使用者不會使用它。
• 空字串：auto 值的同義詞。

每個瀏覽器的預設值都不同。規範建議將其設定為 metadata。

備註

• autoplay 屬性優先於 preload。如果指定了 autoplay，瀏覽器顯然需要開始下載影片進行播放。
• 規範並未強制瀏覽器遵循此屬性的值；它只是一個提示。

src

要嵌入的影片的 URL。這是可選的；你可以改為在影片塊內使用 <source> 元素來指定要嵌入的影片。

width

影片顯示區域的寬度，以 CSS 畫素為單位（僅限絕對值；無百分比）。

事件

audioprocess 已棄用

ScriptProcessorNode 的輸入緩衝區已準備好進行處理。

canplay

瀏覽器可以播放媒體，但估計載入的資料不足以播放到媒體結束而無需停止進一步緩衝內容。

canplaythrough

瀏覽器估計它可以播放媒體直到結束，而無需停止緩衝內容。

完成

OfflineAudioContext 的渲染已終止。

durationchange

duration 屬性已更新。

emptied

媒體已變為空；例如，如果媒體已載入（或部分載入），並且呼叫 load() 方法重新載入它，則會發送此事件。

ended

由於媒體播放結束，播放已停止。

error

獲取媒體資料時發生錯誤，或者資源的型別不是支援的媒體格式。

loadeddata

媒體的第一幀已載入完成。

loadedmetadata

元資料已載入。

loadstart

當瀏覽器開始載入資源時觸發。

pause

播放已暫停。

play

播放已開始。

playing

由於資料不足而暫停或延遲後，播放已準備好開始。

progress

瀏覽器載入資源時定期觸發。

ratechange

播放速率已更改。

seeked

快進/快退操作完成。

seeking

快進/快退操作開始。

stalled

使用者代理正在嘗試獲取媒體資料，但資料意外地沒有到達。

suspend

媒體資料載入已暫停。

timeupdate

currentTime 屬性指示的時間已更新。

volumechange

音量已更改。

waiting

由於暫時缺少資料，播放已停止。

用法說明

瀏覽器並不都支援相同的影片格式；你可以在巢狀的 <source> 元素中提供多個源，然後瀏覽器將使用它理解的第一個源。

<video controls>
  <source src="myVideo.webm" type="video/webm" />
  <source src="myVideo.mp4" type="video/mp4" />
  <p>
    Your browser doesn't support HTML video. Here is a
    <a href="myVideo.mp4" download="myVideo.mp4">link to the video</a> instead.
  </p>
</video>

當使用 <source> 元素時，瀏覽器會按順序嘗試載入每個源。如果某個源失敗（例如，由於無效 URL 或不支援的格式），則嘗試下一個源，依此類推。如果所有源都失敗，則在 <video> 元素上觸發 error 事件；error 事件不會在每個單獨的 <source> 元素上觸發。

我們提供了關於媒體檔案型別和影片支援的編解碼器的實質性且全面的指南。還提供了可與它們一起使用的音訊編解碼器指南。

其他使用注意事項

• 如果你不指定 controls 屬性，影片將不包含瀏覽器的預設控制元件；你可以使用 JavaScript 和 HTMLMediaElement API 建立自己的自定義控制元件。有關更多詳細資訊，請參閱建立跨瀏覽器影片播放器。
• 為了精確控制你的影片（和音訊）內容，HTMLMediaElements 會觸發許多不同的事件。除了提供可控性之外，這些事件還允許你監控媒體的下載和播放進度，以及播放狀態和位置。
• 你可以使用 object-position 屬性調整影片在元素幀內的定位，以及 object-fit 屬性控制影片大小如何調整以適應幀。
• 要隨影片顯示字幕/隱藏式字幕，你可以使用一些 JavaScript 以及 <track> 元素和 WebVTT 格式。有關更多資訊，請參閱為 HTML 影片新增字幕和隱藏式字幕。
• 你可以使用 <video> 元素播放音訊檔案。這很有用，例如，如果你需要播放帶有 WebVTT 文字內容的音訊，因為 <audio> 元素不允許使用 WebVTT 字幕。
• 為了在支援該元素的瀏覽器上測試備用內容，你可以將 <video> 替換為不存在的元素，例如 <notavideo>。

關於使用 HTML <video> 的一個很好的通用資訊來源是HTML 影片和音訊初學者教程。

使用 CSS 樣式

<video> 元素是一個替換元素——它的 display 值預設為 inline——但它在視口中的預設寬度和高度由嵌入的影片定義。

對於 <video> 的樣式設定沒有特殊考慮；一種常見的策略是為其提供 display 值為 block，以便更容易定位、調整大小等，然後根據需要提供樣式和佈局資訊。影片播放器樣式基礎提供了一些有用的樣式技術。

新增字幕和其他定時文字軌道

用於字幕、隱藏式字幕、章節標題等的定時文字軌道可以透過巢狀 <track> 元素以宣告方式新增。軌道在 Web Video Text Tracks File Format (WebVTT)（.vtt 檔案）中指定。

例如，下面的 HTML 包含檔案“captions.vtt”，如果使用者啟用了字幕，該檔案將用於在影片上疊加隱藏式字幕。

<video controls src="video.webm">
  <track default kind="captions" src="captions.vtt" />
</video>

定時文字軌道也可以使用 WebVTT API 透過程式設計方式新增。

檢測軌道的新增和移除

你可以使用 addtrack 和 removetrack 事件來檢測何時將軌道新增到或從 <video> 元素中移除。但是，這些事件不會直接傳送到 <video> 元素本身。相反，它們會發送到 <video> 元素的 HTMLMediaElement 中與新增到元素的軌道型別對應的軌道列表物件

HTMLMediaElement.audioTracks

一個 AudioTrackList，包含所有媒體元素的音軌。向此物件新增 addtrack 偵聽器，以在新音軌新增到元素時收到通知。

HTMLMediaElement.videoTracks

一個 VideoTrackList，包含所有媒體元素的影片軌道。向此物件新增 addtrack 偵聽器，以在影片軌道新增到元素時收到通知。

HTMLMediaElement.textTracks

一個 TextTrackList，包含所有媒體元素的文字軌道（用於字幕、隱藏式字幕等）。向此物件新增 addtrack 偵聽器，以在文字軌道新增到元素時收到通知。

例如，要檢測何時將音軌新增到或從 <video> 元素中移除，你可以使用以下程式碼

const elem = document.querySelector("video");

elem.audioTracks.onaddtrack = (event) => {
  trackEditor.addTrack(event.track);
};

elem.audioTracks.onremovetrack = (event) => {
  trackEditor.removeTrack(event.track);
};

此程式碼監視音軌何時新增到或從元素中移除，並呼叫軌道編輯器上的假定函式來註冊和從編輯器的可用軌道列表中移除軌道。

你還可以使用 addEventListener() 來監聽 addtrack 和 removetrack 事件。

伺服器對影片的支援

如果伺服器上未正確設定影片的 MIME 型別，影片可能不會顯示，或者顯示一個包含 X 的灰色框（如果啟用了 JavaScript）。

如果你使用 Apache Web 伺服器來提供 WebM 影片，你可以透過將影片檔案型別副檔名新增到 video/webm MIME 型別（最常見的 WebM 副檔名是 .webm）來解決此問題。為此，請編輯 /etc/apache 中的 mime.types 檔案，或在 httpd.conf 中使用 AddType 配置指令

AddType video/webm .webm

你的網路主機可能會為新技術提供一個簡單的 MIME 型別配置更改介面，直到全球更新自然發生。

無障礙

影片應提供準確描述其內容的字幕和文字記錄（有關如何實現這些內容的更多資訊，請參閱為 HTML 影片新增字幕和隱藏式字幕）。字幕允許聽力受損的人在影片播放時理解影片的音訊內容，而文字記錄允許需要額外時間的人以適合自己的速度和格式檢視音訊內容。

值得注意的是，雖然你可以為純音訊媒體新增字幕，但你只能在 <video> 元素中播放音訊時這樣做，因為該元素的影片區域用於呈現字幕。這是在影片元素中播放音訊的特殊場景之一。

如果使用自動字幕服務，務必檢查生成的內容，以確保它準確地代表了源影片。

除了對話，字幕和文字記錄還應識別傳達重要資訊的音樂和音效。這包括情感和語氣

14
00:03:14 --> 00:03:18
[Dramatic rock music]

15
00:03:19 --> 00:03:21
[whispering] What's that off in the distance?

16
00:03:22 --> 00:03:24
It's… it's a…

16 00:03:25 --> 00:03:32
[Loud thumping]
[Dishes clattering]

字幕不應遮擋影片的主要內容。它們可以使用align VTT 提示設定進行定位。

• Web 影片文字軌道格式 (WebVTT)
• WebAIM：字幕、文字記錄和音訊描述
• MDN 理解 WCAG，指南 1.2 解釋
• 理解成功標準 1.2.1 | W3C 理解 WCAG 2.0
• 理解成功標準 1.2.2 | W3C 理解 WCAG 2.0

示例

單一源

此示例在啟用時播放影片，為使用者提供瀏覽器的預設影片控制元件以控制播放。

HTML

<!-- Basic video example -->
<!-- 'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org -->
<!-- Poster from peach.blender.org -->
<video
  controls
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
  width="620">
  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a href="https://archive.org/details/BigBuckBunny_124">download it</a>
  and watch it with your favorite video player!
</video>

結果

在影片開始播放之前，在 poster 屬性中提供的影像會顯示在其位置。如果瀏覽器不支援影片播放，則顯示備用文字。

多個源

此示例在前一個示例的基礎上，為媒體提供了三種不同的來源；這使得無論瀏覽器支援哪種影片編解碼器，都可以觀看影片。

HTML

<!-- Using multiple sources as fallbacks for a video tag -->
<!-- 'Elephants Dream' by Orange Open Movie Project Studio, licensed under CC-3.0, hosted by archive.org -->
<!-- Poster hosted by Wikimedia -->
<video
  width="620"
  controls
  poster="https://upload.wikimedia.org/wikipedia/commons/e/e8/Elephants_Dream_s5_both.jpg">
  <source
    src="https://archive.org/download/ElephantsDream/ed_hd.avi"
    type="video/avi" />
  <source
    src="https://archive.org/download/ElephantsDream/ed_1024_512kb.mp4"
    type="video/mp4" />

  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a
    href="https://archive.org/download/ElephantsDream/ed_1024_512kb.mp4"
    download="ed_1024_512kb.mp4">
    download the MP4
  </a>
  and watch it with your favorite video player!
</video>

結果

首先嚐試 AVI。如果無法播放，則嘗試 MP4。如果不支援影片元素，則顯示備用訊息，但如果所有源都失敗，則不顯示。

某些媒體檔案型別允許你使用 codecs 引數作為檔案型別字串的一部分提供更具體的資訊。例如，video/webm; codecs="vp8, vorbis" 表示該檔案是一個 WebM 影片，使用 VP8 進行影片編碼，使用 Vorbis 進行音訊編碼。

技術摘要

規範

瀏覽器相容性

另見

• Web 媒體型別和格式指南

  • 媒體容器格式（檔案型別）
  • Web 影片編解碼器指南
  • Web 音訊編解碼器指南

• 圖片在其框架內的定位和大小調整：object-position 和 object-fit

• <audio>

• HTML 影片和音訊

• 使用 canvas 操作影片

• 為 Ogg 媒體配置伺服器