YouTube Player API Reference for iframe Embeds

Interfejs IFrame Player API umożliwia osadzenie odtwarzacza filmów YouTube w witrynie i sterowanie jego działaniem za pomocą języka JavaScript.

Za pomocą funkcji tego interfejsu API pisanych w języku JavaScript możesz kolejkować filmy do odtwarzania, odtwarzać te filmy oraz wstrzymywać i zatrzymywać ich odtwarzanie, dostosowywać poziom głośności odtwarzacza lub pobierać informacje o odtwarzanym filmie. Możesz też dodać odbiorniki zdarzeń, które będą wykonywane w odpowiedzi na określone zdarzenia odtwarzacza, np. zmianę stanu odtwarzacza.

Z tego przewodnika dowiesz się, jak korzystać z interfejsu IFrame API. W tym artykule opisano różne typy zdarzeń, które może wysyłać interfejs API, oraz wyjaśniono, jak pisać odbiorniki zdarzeń, aby na nie odpowiadać. Podręcznik zawiera też szczegółowy opis różnych funkcji języka JavaScript, które możesz wywoływać, by sterować odtwarzaczem filmów, a także parametrów odtwarzacza, które umożliwiają jego dostosowywanie.

Wymagania

Przeglądarka użytkownika musi obsługiwać funkcję HTML5 postMessage. Większość nowoczesnych przeglądarek obsługuje postMessage.

Odtwarzacz umieszczony na stronie musi mieć okno wyświetlania o rozmiarze co najmniej 200 x 200 pikseli. Jeżeli w odtwarzaczu mają być widoczne elementy sterujące, musi on być na tyle duży, aby elementy te były całkowicie widoczne bez zmniejszania okna wyświetlania poniżej rozmiaru minimalnego. W przypadku odtwarzaczy 16:9 zalecamy rozmiar co najmniej 480 pikseli szerokości i 270 pikseli wysokości.

Każda strona, na której jest używany interfejs IFrame API, musi także implementować następującą funkcję JavaScript:

  • onYouTubeIframeAPIReady – interfejs API wywoła tę funkcję, gdy skończy się pobieranie kodu JavaScript dla interfejsu API odtwarzacza, co umożliwi Ci korzystanie z interfejsu API na stronie. Dzięki temu funkcja ta może tworzyć obiekty odtwarzacza, które mają się pojawiać po wczytaniu strony.

Pierwsze kroki

Na przedstawionej poniżej przykładowej stronie HTML umieszczany jest odtwarzacz, który wczytuje film, odtwarza go przez sześć sekund, a następnie zatrzymuje odtwarzanie. Komentarze opatrzone numerami w kodzie HTML są objaśnione na liście znajdującej się pod tym przykładem.

<!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>

Poniższa lista zawiera szczegółowe informacje dotyczące przykładu przedstawionego powyżej:

  1. Tag <div> w tej sekcji wskazuje lokalizację na stronie, w której interfejs IFrame API umieści odtwarzacz wideo. Konstruktor obiektu playera, który jest opisany w sekcji Ładowanie odtwarzacza wideo, identyfikuje tag <div> za pomocą jego id, aby zapewnić, że interfejs API umieści tag <iframe> we właściwym miejscu. W szczególności interfejs IFrame API zastąpi tag <div> tagiem <iframe>.

    Możesz też umieścić element <iframe> bezpośrednio na stronie. W sekcji Wczytywanie odtwarzacza wideo znajdziesz instrukcje.

  2. Kod znajdujący się w tej sekcji wczytuje kod JavaScript interfejsu IFrame Player API. W tym przykładzie do pobrania kodu API jest używana zmodyfikowana specyfikacja DOM, co zapewnia możliwość asynchronicznego pobierania kodu Atrybut async tagu <script>, który umożliwia też pobieranie asynchroniczne, nie jest jeszcze obsługiwany we wszystkich nowoczesnych przeglądarkach, jak wyjaśniono w tej odpowiedzi na Stack Overflow.

  3. Funkcja onYouTubeIframeAPIReady zostanie wykonana, gdy tylko zostanie pobrany kod interfejsu API odtwarzacza. Ten fragment kodu definiuje zmienną globalną player, która odnosi się do odtwarzacza wideo, który umieszczasz, a funkcja tworzy obiekt odtwarzacza wideo.

  4. Funkcja onPlayerReady zostanie wykonana, gdy wystąpi zdarzenie onReady. W tym przykładzie funkcja ta wskazuje, że kiedy odtwarzacz filmów jest gotowy, powinien rozpocząć odtwarzanie.

  5. Gdy stan odtwarzacza ulegnie zmianie, interfejs API wywoła funkcję onPlayerStateChange, co może oznaczać, że odtwarzacz jest w stanie odtwarzania, wstrzymania, zakończenia itp. Funkcja wskazuje, że gdy stan odtwarzacza to 1 (odtwarzanie), odtwarzanie powinno trwać 6 sekund, a potem wywołać funkcję stopVideo, aby zatrzymać film.

Wczytywanie odtwarzacza filmów

Po wczytaniu kodu JavaScript interfejsu API zostanie wywołana funkcja onYouTubeIframeAPIReady, po czym możesz utworzyć obiekt YT.Player, aby wstawić na stronie odtwarzacz wideo. Fragment kodu HTML poniżej zawiera funkcję onYouTubeIframeAPIReady z powyższego przykładu:

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

Konstruktor odtwarzacza filmów określa następujące parametry:

  1. Pierwszy parametr określa element DOM lub id elementu HTML, w którym interfejs API wstawi tag <iframe> zawierający odtwarzacz.

    Interfejs IFrame API zastąpi określony element elementem <iframe> zawierającym odtwarzacz. Może to wpłynąć na układ strony, jeśli zastępowany element ma inny styl wyświetlania niż wstawiony element <iframe>. Domyślnie element <iframe> jest wyświetlany jako element inline-block.

  2. Drugim parametrem jest obiekt określający opcje odtwarzacza. Obiekt zawiera te właściwości:
    • width (liczba) – szerokość odtwarzacza. (wartością domyślną jest 640);
    • height (liczba) – wysokość odtwarzacza. (wartością domyślną jest 390);
    • videoId (ciąg znaków) – identyfikator filmu w YouTube, który identyfikuje film, który odtwarzacz ma wczytać.
    • playerVars (obiekt) – właściwości obiektu identyfikują parametry odtwarzacza, których można używać do dostosowywania odtwarzacza.
    • events (obiekt) – właściwości obiektu wskazują zdarzenia wywoływane przez interfejs API oraz funkcje (słuchacze zdarzeń), które interfejs API wywoła, gdy wystąpią te zdarzenia. W tym przykładzie konstruktor wskazuje, że funkcja onPlayerReady zostanie wykonana po wywołaniu zdarzenia onReady, a funkcja onPlayerStateChange – po wywołaniu zdarzenia onStateChange.

Jak wspomnieliśmy w sekcji Pierwsze kroki, zamiast umieszczać na stronie pusty element <div>, który kod JavaScript interfejsu API odtwarzacza zastąpi elementem <iframe>, możesz utworzyć tag <iframe> samodzielnie. Pierwszy przykład w sekcji Przykłady pokazuje, jak to zrobić.

<iframe id="player" type="text/html" width="640" height="390"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com"
  frameborder="0"></iframe>

Pamiętaj, że jeśli napiszesz tag <iframe>, podczas tworzenia obiektu YT.Player nie musisz podawać wartości parametrów width i height, które są podawane jako atrybuty tagu <iframe>, ani parametrów videoId i player, które są podawane w adresie URL src. Jako dodatkowy środek bezpieczeństwa dodaj do adresu URL parametr origin, podając jako jego wartość schemat adresu URL (http:// lub https://) i pełną domenę strony hosta. origin jest opcjonalny, ale jego uwzględnienie chroni przed wstrzyknięciem na Twoją stronę złośliwego kodu JavaScript pochodzącego od osób trzecich i przejęciem kontroli nad odtwarzaczem YouTube.

Inne przykłady tworzenia obiektów odtwarzacza wideo znajdziesz w sekcji Przykłady.

Operacje

Aby wywoływać metody interfejsu API odtwarzacza, musisz najpierw uzyskać odniesienie do obiektu odtwarzacza, który chcesz kontrolować. Odniesienie uzyskuje się przez utworzenie obiektu YT.Player, jak opisano w sekcjach Wprowadzenie i Ładowanie odtwarzacza filmów tego dokumentu.

Funkcje

Funkcje kolejkujące

Funkcje kolejkujące umożliwiają wczytanie i odtworzenie filmu, playlisty lub innej listy filmów. Jeśli do wywoływania tych funkcji używasz opisanej poniżej składni obiektu, możesz też umieścić w kolejce lub załadować listę przesłanych przez użytkownika filmów.

Interfejs API obsługuje dwie różne składnie wywoływania funkcji kolejkujących.

  • Składnia argumentów wymaga, by wymienić argumenty funkcji w określonej kolejności.

  • Składnia obiektu umożliwia przekazanie pojedynczego parametru w postaci obiektu o zdefiniowanych właściwościach odpowiadających argumentom funkcji, które chcesz ustawić. Oprócz tego interfejs API może obsłużyć dodatkowe funkcje, których nie obsługuje składnia argumentów.

Na przykład funkcję loadVideoById można wywołać na jeden z tych sposobów. Pamiętaj, że składnia obiektu obsługuje właściwość endSeconds, której nie obsługuje składnia argumentów.

  • Składnia argumentów

    loadVideoById("bHQqvYy5KYo", 5, "large")

  • Składnia obiektu

    loadVideoById({'videoId': 'bHQqvYy5KYo',
               'startSeconds': 5,
               'endSeconds': 60});

Funkcje kolejkujące do obsługi filmów

cueVideoById

  • Składnia argumentów

    player.cueVideoById(videoId:String,
                    startSeconds:Number):Void

  • Składnia obiektu

    player.cueVideoById({videoId:String,
                     startSeconds:Number,
                     endSeconds:Number}):Void

Ta funkcja wczytuje miniaturę określonego filmu i przygotowuje odtwarzacz do jego odtworzenia. Odtwarzacz nie wysyła żądania pliku FLV, dopóki nie zostanie wywołana funkcja playVideo() lub seekTo().

  • Wymagany parametr videoId określa identyfikator filmu w YouTube, który ma zostać odtworzony. W interfejsie YouTube Data API identyfikator określa właściwość video zasobu id.
  • Opcjonalny parametr startSeconds może przyjmować wartości zmiennoprzecinkowe lub całkowite i określa czas, od którego film ma się zacząć odtwarzać po wywołaniu funkcji playVideo(). Jeśli określisz wartość startSeconds, a następnie wywołasz funkcję seekTo(), odtwarzacz odtwarza od czasu określonego w wywołaniu funkcji seekTo(). Gdy film jest gotowy do odtworzenia, odtwarzacz wyśle do urządzenia sygnał o video cued zdarzeniu (5).
  • Opcjonalny parametr endSeconds, który jest obsługiwany tylko w składni obiektowej, przyjmuje wartość zmiennoprzecinkową lub całkowitą i określa czas, w którym film ma przestać się odtwarzać po wywołaniu funkcji playVideo(). Jeśli określisz wartość endSeconds, a potem wywołasz funkcję seekTo(), wartość endSeconds przestanie obowiązywać.

loadVideoById

  • Składnia argumentów

    player.loadVideoById(videoId:String,
                     startSeconds:Number):Void

  • Składnia obiektu

    player.loadVideoById({videoId:String,
                      startSeconds:Number,
                      endSeconds:Number}):Void

Ta funkcja wczytuje i odtwarza określony film.

  • Wymagany parametr videoId określa identyfikator filmu w YouTube, który ma zostać odtworzony. W interfejsie YouTube Data API identyfikator określa właściwość video zasobu id.
  • Opcjonalny parametr startSeconds może przyjmować wartości zmiennoprzecinkowe lub całkowite. Jeśli jest określony, odtwarzanie filmu rozpoczyna się od klatki kluczowej znajdującej się najbliżej podanego czasu.
  • Opcjonalny parametr endSeconds może przyjmować wartości zmiennoprzecinkowe lub całkowite. Jeśli jest określony, odtwarzanie filmu zatrzymuje się w podanym czasie.

cueVideoByUrl

  • Składnia argumentów

    player.cueVideoByUrl(mediaContentUrl:String,
                     startSeconds:Number):Void

  • Składnia obiektu

    player.cueVideoByUrl({mediaContentUrl:String,
                      startSeconds:Number,
                      endSeconds:Number}):Void

Ta funkcja wczytuje miniaturę określonego filmu i przygotowuje odtwarzacz do jego odtworzenia. Odtwarzacz nie wysyła żądania pliku FLV, dopóki nie zostanie wywołana funkcja playVideo() lub seekTo().

  • Wymagany parametr mediaContentUrl określa pełny adres URL odtwarzacza YouTube w formacie http://www.youtube.com/v/VIDEO_ID?version=3.
  • Opcjonalny parametr startSeconds może przyjmować wartości zmiennoprzecinkowe lub całkowite i określa czas, od którego film ma się zacząć odtwarzać po wywołaniu funkcji playVideo(). Jeśli określisz startSeconds, a następnie wywołasz seekTo(), odtwarzanie rozpocznie się od czasu określonego w wywołaniu seekTo(). Gdy film jest gotowy do odtworzenia, odtwarzacz wyśle sygnał video cued (5).
  • Opcjonalny parametr endSeconds, który jest obsługiwany tylko w składni obiektu, przyjmuje wartość zmiennoprzecinkową lub całkowitą i określa czas, w którym film ma przestać się odtwarzać po wywołaniu funkcji playVideo(). Jeśli określisz wartość endSeconds, a potem wywołasz funkcję