amp-youtube

實驗性

Bento

說明

顯示 YouTube 影片。

必要指令碼

AMP Bento (獨立)

<script async custom-element="amp-youtube" src="https://cdn.ampproject.org/v0/amp-youtube-1.0.js"></script>

<script async custom-element="amp-youtube" src="https://cdn.ampproject.org/v0/amp-youtube-1.0.js"></script>
<link rel="stylesheet" href="https://cdn.ampproject.org/v0/amp-youtube-1.0.css">

支援版面配置

fill fixed fixed-height flex-item nodisplay responsive

範例

產品頁面 amp-addthis amp-youtube 在 AMP 中整合影片總覽使用 amp-carousel 製作影片輪播

用法

顯示 YouTube 影片。

使用回應式版面配置時，範例中的寬度和高度應能為 16:9 長寬比的影片產生正確的版面配置

<amp-youtube
  data-videoid="mGENRKrdoGY"
  layout="responsive"
  width="480"
  height="270"
></amp-youtube>

<amp-youtube
  id="myLiveChannel"
  data-live-channelid="UCB8Kb4pxYzsDsHxzBfnid4Q"
  width="358"
  height="204"
  layout="responsive"
>
  <amp-img
    src="https://i.ytimg.com/vi/Wm1fWz-7nLQ/hqdefault_live.jpg"
    placeholder
    layout="fill"
  />
</amp-youtube>

在有效的 AMP 文件之外獨立使用

Bento AMP 可讓您在非 AMP 頁面中使用 AMP 元件，而無需完全採用有效的 AMP。您可以採用這些元件，並將其置入不支援 AMP 的架構和 CMS 的實作項目中。如要瞭解詳情，請參閱我們的指南在非 AMP 頁面中使用 AMP 元件。

<head>
  <script async src="https://cdn.ampproject.org/v0.js"></script>
  <link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-youtube-1.0.css">
  <script async custom-element="amp-youtube" src="https://cdn.ampproject.org/v0/amp-youtube-1.0.js"></script>
</head>
<body>
  <amp-youtube
    style="aspect-ratio: 16/9"
    id="my-youtube-video"
    data-videoid="mGENRKrdoGY"
  ></amp-youtube>
  <script>
    (async () => {
      const video = document.querySelector('#my-youtube-video');
      await customElements.whenDefined('amp-youtube');
      const videoHandle = await video.getApi();

      // programatically call playback actions
      videoHandle.play();
      videoHandle.pause();
      videoHandle.requestFullscreen();
      videoHandle.mute();
      videoHandle.unmute();

      // get video state
      console.log({
        autoplay: videoHandle.autoplay,
        controls: videoHandle.controls,
        duration: videoHandle.duration,
        currentTime: videoHandle.currentTime,
        loop: videoHandle.loop,
      })
    })();
  </script>
</body>

互動性和 API 用法

Bento 透過其 API 具有高度互動性。在 Bento 獨立使用中，元素的 API 會取代 AMP 動作和事件以及 amp-bind。

amp-youtube 元件 API 可透過在文件中加入以下指令碼標記來存取

await customElements.whenDefined('amp-youtube');
const videoHandle = await video.getApi();

動作

amp-youtube API 可讓您執行下列動作

`play()`

播放影片。

videoHandle.play();

`pause()`

暫停影片。

videoHandle.pause();

`mute()`

將影片設為靜音。

videoHandle.mute();

`unmute()`

取消影片靜音。

videoHandle.unmute();

`requestFullscreen()`

盡可能將影片展開為全螢幕。

videoHandle.requestFullscreen();

屬性

它也會公開下列唯讀屬性

`currentTime` (`number`)

目前的播放時間 (以秒為單位)。

console.log(videoHandle.currentTime);

`duration` (`number`)

影片的長度 (以秒為單位)，在已知的情況下 (例如，不是直播)。

console.log(videoHandle.duration);

`autoplay` (`boolean`)

影片是否自動播放。

console.log(videoHandle.autoplay);

`controls` (`boolean`)

影片是否顯示控制項。

console.log(videoHandle.controls);

`loop` (`boolean`)

影片是否循環播放。

console.log(videoHandle.loop);

從 0.1 版移轉

實驗性 1.0 版的 amp-youtube 不會自動將 data-param-controls 轉換為 controls。而是直接將 controls 作為屬性。

屬性

autoplay

如果此屬性存在，且瀏覽器支援自動播放

影片會在開始自動播放前自動設為靜音
當影片捲動到檢視畫面外時，影片會暫停
當影片捲動到檢視畫面內時，影片會繼續播放
當使用者輕觸影片時，影片會取消靜音
如果使用者曾與影片互動 (例如，設為靜音/取消靜音、暫停/繼續等)，且影片捲動到檢視畫面內或外，影片的狀態仍會維持使用者離開時的狀態。例如，如果使用者暫停影片，然後將影片捲動到檢視畫面外，然後返回影片，則影片仍會處於暫停狀態。

loop

如果此屬性存在，影片或播放清單會在結束後再次播放 (從頭開始)。

data-videoid

在每個 YouTube 影片頁面網址中找到的 YouTube 影片 ID。

例如，在此網址中：https://www.youtube.com/watch?v=Z1q71gFeRqM，Z1q71gFeRqM 是影片 ID。

data-live-channelid

提供穩定直播網址的 YouTube 頻道 ID。例如，在此網址中：https://www.youtube.com/embed/live_stream?channel=UCB8Kb4pxYzsDsHxzBfnid4Q，UCB8Kb4pxYzsDsHxzBfnid4Q 是頻道 ID。您可以提供 data-live-channelid 而非 data-videoid 屬性，以嵌入直播的穩定網址，而非影片。頻道沒有預設預留位置。您可以為影片提供預留位置，如上方的範例 2 所示。

data-param-*

所有 data-param-* 屬性 (data-param-autoplay 和 data-param-loop 除外) 都會新增為 YouTube iframe src 的查詢參數。這可用於將自訂值傳遞至 YouTube 外掛程式，例如是否顯示控制項。

索引鍵和值將會進行 URI 編碼。索引鍵將會使用駝峰式命名法

controls

如需 YouTube 的更多參數選項，請參閱YouTube 嵌入式播放器參數。

請使用 autoplay 屬性而非 data-param-autoplay，並使用 loop 屬性而非 data-param-loop，因為自動播放和循環行為都是由 AMP 而非 YouTube 播放器在內部處理。

credentials (選填)

定義 credentials 選項，如 Fetch API 所指定。

支援的值：omit、include
預設值：include

如果您想要在隱私權加強模式中使用 YouTube 播放器，請傳遞 omit 值。

通常，YouTube 會在播放器載入時設定 Cookie。在隱私權加強模式中，Cookie 會在使用者點擊播放器後設定。

title (選填)

為元件定義 title 屬性，以傳播至底層的 <iframe> 元素。預設值為 "YouTube 影片"。

通用屬性

此元素包含擴充至 AMP 元件的通用屬性。

需要更多協助嗎？

您已閱讀本文件十幾次，但它仍然沒有真正涵蓋您的所有問題？也許其他人也有同感：在 Stack Overflow 上與他們聯繫。

前往 Stack Overflow

發現錯誤或缺少功能嗎？

AMP 專案強烈鼓勵您的參與和貢獻！我們希望您能成為我們開放原始碼社群的長期參與者，但我們也歡迎您針對您特別熱衷的問題提供一次性的貢獻。

前往 GitHub

amp-youtube 1.0 0.1

說明