YouTube Player API Reference for iframe Embeds

API trình phát IFrame cho phép bạn nhúng trình phát video trên YouTube vào trang web của mình và điều khiển trình phát bằng JavaScript.

Khi sử dụng các hàm JavaScript của API, bạn có thể thêm video vào hàng đợi phát; phát, tạm dừng hoặc dừng các video đó; điều chỉnh âm lượng của trình phát; hoặc truy xuất thông tin về video đang phát. Bạn cũng có thể thêm trình nghe sự kiện sẽ thực thi để phản hồi một số sự kiện nhất định của người chơi, chẳng hạn như thay đổi trạng thái của người chơi.

Hướng dẫn này giải thích cách sử dụng API IFrame. Tài liệu này xác định các loại sự kiện mà API có thể gửi và giải thích cách viết trình nghe sự kiện để phản hồi các sự kiện đó. Tài liệu này cũng trình bày chi tiết các hàm JavaScript mà bạn có thể gọi để kiểm soát trình phát video cũng như các tham số trình phát mà bạn có thể sử dụng để tuỳ chỉnh thêm trình phát.

Yêu cầu

Trình duyệt của người dùng phải hỗ trợ tính năng postMessage HTML5. Hầu hết các trình duyệt hiện đại đều hỗ trợ postMessage.

Trình phát được nhúng phải có khung nhìn tối thiểu là 200px x 200px. Nếu trình phát hiển thị các nút điều khiển, thì trình phát phải đủ lớn để hiển thị đầy đủ các nút điều khiển mà không làm thu nhỏ khung nhìn xuống dưới kích thước tối thiểu. Bạn nên sử dụng trình phát 16:9 có chiều rộng tối thiểu 480 pixel và chiều cao tối thiểu 270 pixel.

Mọi trang web sử dụng API IFrame cũng phải triển khai hàm JavaScript sau:

  • onYouTubeIframeAPIReady – API sẽ gọi hàm này khi trang đã tải xong JavaScript cho API trình phát, cho phép bạn sử dụng API trên trang của mình. Do đó, hàm này có thể tạo các đối tượng người chơi mà bạn muốn hiển thị khi trang tải.

Bắt đầu

Trang HTML mẫu bên dưới sẽ tạo một trình phát được nhúng để tải video, phát video trong 6 giây rồi dừng phát. Các nhận xét được đánh số trong HTML được giải thích trong danh sách bên dưới ví dụ.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <div id="player"></div>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and YouTube player)
      //    after the API code downloads.
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('player', {
          height: '390',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          playerVars: {
            'playsinline': 1
          },
          events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
          }
        });
      }

      // 4. The API will call this function when the video player is ready.
      function onPlayerReady(event) {
        event.target.playVideo();
      }

      // 5. The API calls this function when the player's state changes.
      //    The function indicates that when playing a video (state=1),
      //    the player should play for six seconds and then stop.
      var done = false;
      function onPlayerStateChange(event) {
        if (event.data == YT.PlayerState.PLAYING && !done) {
          setTimeout(stopVideo, 6000);
          done = true;
        }
      }
      function stopVideo() {
        player.stopVideo();
      }
    </script>
  </body>
</html>

Danh sách sau đây cung cấp thêm thông tin chi tiết về mẫu trên:

  1. Thẻ <div> trong phần này xác định vị trí trên trang mà API IFrame sẽ đặt trình phát video. Hàm khởi tạo cho đối tượng trình phát (được mô tả trong phần Tải trình phát video) xác định thẻ <div> bằng id để đảm bảo rằng API đặt <iframe> ở vị trí thích hợp. Cụ thể, API IFrame sẽ thay thế thẻ <div> bằng thẻ <iframe>.

    Ngoài ra, bạn cũng có thể đặt phần tử <iframe> ngay trên trang. Phần Tải trình phát video giải thích cách thực hiện.

  2. Mã trong phần này sẽ tải mã JavaScript của API Trình phát IFrame. Ví dụ này sử dụng tính năng sửa đổi DOM để tải mã API xuống nhằm đảm bảo rằng mã được truy xuất không đồng bộ. (Thuộc tính async của thẻ <script> cũng cho phép tải xuống không đồng bộ, nhưng chưa được hỗ trợ trong tất cả trình duyệt hiện đại như đã thảo luận trong câu trả lời trên Stack Overflow này.

  3. Hàm onYouTubeIframeAPIReady sẽ thực thi ngay khi mã API của người chơi tải xuống. Phần mã này xác định một biến toàn cục, player, tham chiếu đến trình phát video mà bạn đang nhúng, sau đó hàm này sẽ tạo đối tượng trình phát video.

  4. Hàm onPlayerReady sẽ thực thi khi sự kiện onReady kích hoạt. Trong ví dụ này, hàm cho biết rằng khi trình phát video đã sẵn sàng, trình phát sẽ bắt đầu phát.

  5. API sẽ gọi hàm onPlayerStateChange khi trạng thái của người chơi thay đổi, có thể cho biết người chơi đang chơi, tạm dừng, kết thúc, v.v. Hàm này cho biết rằng khi trạng thái của trình phát là 1 (đang phát), trình phát sẽ phát trong 6 giây rồi gọi hàm stopVideo để dừng video.

Tải trình phát video

Sau khi tải mã JavaScript của API, API sẽ gọi hàm onYouTubeIframeAPIReady. Tại thời điểm này, bạn có thể tạo một đối tượng YT.Player để chèn trình phát video trên trang của mình. Phần trích dẫn HTML bên dưới cho thấy hàm onYouTubeIframeAPIReady trong ví dụ trên:

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '390',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    playerVars: {
      'playsinline': 1
    },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange
    }
  });
}

Hàm khởi tạo cho trình phát video chỉ định các tham số sau:

  1. Tham số đầu tiên chỉ định phần tử DOM hoặc id của phần tử HTML mà API sẽ chèn thẻ <iframe> chứa trình phát.

    API IFrame sẽ thay thế phần tử đã chỉ định bằng phần tử <iframe> chứa trình phát. Điều này có thể ảnh hưởng đến bố cục của trang nếu phần tử được thay thế có kiểu hiển thị khác với phần tử <iframe> đã chèn. Theo mặc định, <iframe> hiển thị dưới dạng phần tử inline-block.

  2. Tham số thứ hai là một đối tượng chỉ định các tuỳ chọn của người chơi. Đối tượng này chứa các thuộc tính sau:
    • width (số) – Chiều rộng của trình phát video. Giá trị mặc định là 640.
    • height (số) – Chiều cao của trình phát video. Giá trị mặc định là 390.
    • videoId (chuỗi) – Mã video trên YouTube giúp xác định video mà trình phát sẽ tải.
    • playerVars (đối tượng) – Các thuộc tính của đối tượng xác định tham số trình phát có thể dùng để tuỳ chỉnh trình phát.
    • events (đối tượng) – Các thuộc tính của đối tượng xác định các sự kiện mà API kích hoạt và các hàm (trình nghe sự kiện) mà API sẽ gọi khi các sự kiện đó xảy ra. Trong ví dụ này, hàm khởi tạo cho biết hàm onPlayerReady sẽ thực thi khi sự kiện onReady kích hoạt và hàm onPlayerStateChange sẽ thực thi khi sự kiện onStateChange kích hoạt.

Như đã đề cập trong phần Bắt đầu, thay vì viết một phần tử <div> trống trên trang, sau đó mã JavaScript của API trình phát sẽ thay thế bằng phần tử <iframe>, bạn có thể tự tạo thẻ