Bento

Bento YouTube

嵌入 YouTube 影片。

使用 bento-youtube 作為網路元件或 React 函數元件

↓ 網路元件 ↓ React / Preact

網路元件

您必須包含每個 Bento 元件所需的 CSS 函式庫，才能保證適當地載入，並且在加入自訂樣式之前進行此動作。或者使用內嵌可取得的輕量級預升級樣式。請參閱 版面配置與樣式。

透過 npm 匯入

npm install @bentoproject/youtube
import {defineElement as defineBentoYoutube} from '@bentoproject/youtube';
defineBentoYoutube();

透過 <script> 包含

<script type="module" src="https://cdn.ampproject.org/bento.mjs" crossorigin="anonymous"></script>
<script nomodule src="https://cdn.ampproject.org/bento.js" crossorigin="anonymous"></script>
<script type="module" src="https://cdn.ampproject.org/v0/bento-youtube-1.0.mjs" crossorigin="anonymous"></script>
<script nomodule src="https://cdn.ampproject.org/v0/bento-youtube-1.0.js" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdn.ampproject.org/v0/bento-youtube-1.0.css" crossorigin="anonymous">

範例

<head>

<script
      type="module"
      async
      src="https://cdn.ampproject.org/bento.mjs"
    ></script>
    <script nomodule src="https://cdn.ampproject.org/bento.js"></script>
    <script
      type="module"
      async
      src="https://cdn.ampproject.org/v0/bento-youtube-1.0.mjs"
    ></script>
    <script
      nomodule
      async
      src="https://cdn.ampproject.org/v0/bento-youtube-1.0.js"
    ></script>
    <link
      rel="stylesheet"
      type="text/css"
      href="https://cdn.ampproject.org/v0/bento-youtube-1.0.css"
    />
    <style>
      bento-youtube {
        width: 320px;
        height: 180px;
      }
    </style>
</head>

<body>

<bento-youtube data-videoid="dQw4w9WgXcQ"></bento-youtube>
</body>

版面配置與樣式

每個 Bento 元件都有小型 CSS 函式庫，您必須包含該元件才能保證適當地載入且不會出現 內容轉移 的情形。由於基於順序的專屬性，您必須手動確保在所有自訂樣式之前都已包含樣式表。

<link
  rel="stylesheet"
  type="text/css"
  href="https://cdn.ampproject.org/v0/bento-youtube-1.0.css"
/>

或者，您也可以讓網路上有輕量級的預升級樣式。

<style>
  bento-youtube {
    display: block;
    overflow: hidden;
    position: relative;
  }
</style>

容器類別

bento-youtube 元件有一個已定義的版面配置大小類別。要確保元件正確顯示，務必透過想要的 CSS 版面配置（例如以 height、width、aspect-ratio 或其他此類屬性定義的配置）將大小套用至元件及其直屬子（簡報）中

bento-youtube {
  height: 100px;
  width: 100%;
}

屬性

autoplay

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

  • 影片會在自動播放開始前自動靜音
  • 當影片捲動於畫面之外時，影片會暫停
  • 當影片捲動至畫面內時，影片會恢復播放
  • 當使用者輕觸影片時，影片會恢復播放
  • 如果使用者已與影片互動（例如將影片靜音或取消靜音、暫停或開始播放等），且影片捲入或捲出畫面時，影片的狀態會維持使用者離開時的狀態。例如，如果使用者暫停該影片，然後將該影片捲動出畫面再返回至影片，影片仍會維持暫停狀態。

loop

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

data-videoid

可以在每個 YouTube 影片頁面 URL 中找到的 YouTube 影片 ID。

例如，在此 URL 中：https://www.youtube.com/watch?v=Z1q71gFeRqM，Z1q71gFeRqM 即為影片 ID。

data-live-channelid

提供穩定直播網址的 Youtube 頻道 ID。例如，在此 URL 中：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 編碼。金鑰會以駝峰式大小寫表達。

請參閱 YouTube 嵌入式播放器參數，以取得 YouTube 的更多參數選項。

credentials（選用）

定義一個 credentials 選項，如 Fetch API（omit 或 include）中所指定。

如果您想要以 隱私增強模式使用 YouTube 播放器，請傳遞 omit 的值。

YouTube 通常會在載入播放器時設定其 Cookie。在隱私增強模式中，Cookie 會在使用者按一下播放器時設定。

title（選用）

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

互動性和 API 使用

可以在您的文件內包含下列的腳本標籤，以存取 bento-youtube 元件 API

await customElements.whenDefined('bento-youtube');
const api = await video.getApi();

<head>

<script
      type="module"
      async
      src="https://cdn.ampproject.org/bento.mjs"
    ></script>
    <script nomodule src="https://cdn.ampproject.org/bento.js"></script>
    <script
      type="module"
      async
      src="https://cdn.ampproject.org/v0/bento-youtube-1.0.mjs"
    ></script>
    <script
      nomodule
      async
      src="https://cdn.ampproject.org/v0/bento-youtube-1.0.js"
    ></script>
    <link
      rel="stylesheet"
      type="text/css"
      href="https://cdn.ampproject.org/v0/bento-youtube-1.0.css"
    />
    <style>
      bento-youtube {
        width: 320px;
        height: 180px;
      }
    </style>
</head>

<body>

<bento-youtube id="my-video" data-videoid="dQw4w9WgXcQ">
    </bento-youtube>
    <p>
      <button id="play">Play</button>
      <button id="pause">Pause</button>
      <button id="mute">Mute</button>
      <button id="unmute">Unmute</button>
    </p>
    <script>
      (async () => {
        await customElements.whenDefined('amp-youtube');

        const video = document.querySelector('#my-video');
        const api = await video.getApi();

        document.querySelector('#play').onclick = () => {
          api.play();
        };
        document.querySelector('#pause').onclick = () => {
          api.pause();
        };
        document.querySelector('#mute').onclick = () => {
          api.mute();
        };
        document.querySelector('#unmute').onclick = () => {
          api.unmute();
        };
      })();
    </script>
</body>

動作

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

play()

播放影片。

api.play();
pause()

暫停影片。

api.pause();
mute()

靜音影片。

api.mute();
unmute()

取消靜音影片。

api.unmute();
requestFullscreen()

在可能的情況下，將影片擴充為全螢幕。

api.requestFullscreen();

屬性

它還會公開以下唯讀屬性

currentTime（數字）

目前的播放時間（以秒為單位）。

console.log(api.currentTime);
duration（數字）

影片的長度，以秒為單位（例如，不是直播）。

console.log(api.duration);
autoplay（布林值）

影片是否自動播放。

console.log(api.autoplay);
controls（布林值）

影片是否顯示控制項。

console.log(api.controls);
loop（布林值）

影片是否循環播放。

console.log(api.loop);

Preact/React 元件

透過 npm 匯入

npm install @bentoproject/youtube
import React from 'react';
import {BentoYoutube} from '@bentoproject/youtube/react';
import '@bentoproject/youtube/styles.css';

function App() {
  return <BentoYoutube videoid="dQw4w9WgXcQ" />;
}

版面配置與樣式

容器類別

BentoYoutube 元件有一個已定義的版面大小類型。為了確保元件正確地渲染，請務必透過所需的 CSS 版面（例如使用 height、width、aspect-ratio 或其他此類屬性所定義的版面）將大小套用於元件及其直接子代（投影片）。這些設定可以直接套用

<BentoYoutube
  style={{width: 320, height: 180}}
  videoid="dQw4w9WgXcQ"
/>

或透過 className

<BentoYoutube
  className="custom-styles"
  videoid="dQw4w9WgXcQ"
/>
.custom-styles {
  height: 320px;
  width: 180px;
}

您可以使用 aspect-ratio 來調整大小

.custom-styles {
  aspect-ratio: 16/9;
}

道具

autoplay

如果這個道具為真，而瀏覽器支援自動播放

  • 影片會在自動播放開始前自動靜音
  • 當影片捲動於畫面之外時，影片會暫停
  • 當影片捲動至畫面內時，影片會恢復播放
  • 當使用者輕觸影片時，影片會恢復播放
  • 如果使用者已與影片互動（例如將影片靜音或取消靜音、暫停或開始播放等），且影片捲入或捲出畫面時，影片的狀態會維持使用者離開時的狀態。例如，如果使用者暫停該影片，然後將該影片捲動出畫面再返回至影片，影片仍會維持暫停狀態。

loop

如果這個道具為真，視訊或播放清單會從開始處在結束後再次播放。

videoid

可以在每個 YouTube 影片頁面 URL 中找到的 YouTube 影片 ID。

例如，在此 URL 中：https://www.youtube.com/watch?v=Z1q71gFeRqM，Z1q71gFeRqM 即為影片 ID。

liveChannelid

提供穩定的直播串流 URL 的 YouTube 頻道 ID。例如，在這個 URL：https://www.youtube.com/embed/live_stream?channel=UCB8Kb4pxYzsDsHxzBfnid4Q 中，UCB8Kb4pxYzsDsHxzBfnid4Q 是頻道 ID。您可以提供 liveChannelid 道具而不是 videoid 道具，以替直播串流（而非視訊）嵌入穩定的 URL。頻道無預設的佔位符。您可以針對視訊提供佔位符，如上方範例 2 所示。

params

此物件中的所有欄位（例外為 autoplay 和 loop）會作為查詢參數新增至 YouTube iframe src。這可以用於傳遞自訂值給 YouTube 外掛程式，例如是否顯示控制項。

金鑰和值將經過 URI 編碼。金鑰必須使用駝峰式大小寫。

請參閱 YouTube 嵌入式播放器參數，以取得 YouTube 的更多參數選項。

credentials（選用）

定義一個 credentials 選項，如 Fetch API（omit 或 include）中所指定。

如果您想要以 隱私增強模式使用 YouTube 播放器，請傳遞 omit 的值。

YouTube 通常會在載入播放器時設定其 Cookie。在隱私增強模式中，Cookie 會在使用者按一下播放器時設定。

title（選用）

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

互動性和 API 使用

可透過傳遞 ref 來存取 BentoYoutube 元件 API

import React, {createRef} from 'react';

function App() {
  const ref = createRef();
  return (
    <BentoYoutube ref={ref} />
  );
}

動作

BentoYoutube API 讓您執行下列動作

play()

播放影片。

ref.current.play();
pause()

暫停影片。

ref.current.pause();
mute()

靜音影片。

ref.current.mute();
unmute()

取消靜音影片。

ref.current.unmute();
requestFullscreen()

在可能的情況下，將影片擴充為全螢幕。

ref.current.requestFullscreen();

屬性

它還會公開以下唯讀屬性

currentTime（數字）

目前的播放時間（以秒為單位）。

console.log(ref.current.currentTime);
duration（數字）

影片的長度，以秒為單位（例如，不是直播）。

console.log(ref.current.duration);
autoplay（布林值）

影片是否自動播放。

console.log(ref.current.autoplay);
controls（布林值）

影片是否顯示控制項。

console.log(ref.current.controls);
loop（布林值）

影片是否循環播放。

console.log(ref.current.loop);
我們在這個網站上提供 Cookie，以分析流量並最佳化您的體驗。
更多詳細資訊