YouTube Player API Reference for iframe Embeds

通过 IFrame Player API，您可以在自己的网站上嵌入 YouTube 视频播放器并使用 JavaScript 控制播放器。与 Flash 和 JavaScript Player API 不同的是，这两者都要求在您的网页上嵌入一个 Flash 对象，而 IFrame API 会将内容发布到网页上的<iframe>标记中。这种方法比之前提供的 API 更加灵活，因为它允许 YouTube 针对不支持 Flash 的移动设备提供 HTML5 播放器（而非 Flash 播放器）。

使用 API 的 JavaScript 函数，您可以：将视频列入播放队列；播放、暂停或停止这些视频；调整播放器音量；或者检索正在播放的视频的相关信息。您还可以添加会响应特定的播放器事件（例如播放器状态变化或视频播放质量变化）而运行的事件监听器。

本指南将介绍如何使用 IFrame API，列举 API 可以发送的不同类型的事件，并介绍如何撰写事件监听器来响应这些事件。此外，本指南还将详细说明您可以在控制视频播放器时调用的各种 JavaScript 函数，以及可用于进一步自定义播放器的播放器参数。

要求

最终用户使用的必须是支持 HTML5 postMessage 功能的浏览器。除了 Internet Explorer 7 以外，大部分的新型浏览器都支持 postMessage。

嵌入式播放器必须具有一个尺寸至少为200x200像素的视口。如果播放器显示控件，>那么它必须足够大，可以在无需将视口缩小到最小尺寸以下的情况下完整显示控件。我们建议16:9播放器的宽至少为480像素、高至少为270像素。

使用 IFrame API 的所有网页都还必须实施以下 JavaScript 函数：

onYouTubeIframeAPIReady – 在网页下载完播放器API的JavaScript（随后您便可以在网页上使用 API）时，API 就会调用此函数。因此，此函数可创建您希望在网页加载时显示的播放器对象。

开始使用

下面的示例HTML网页可以创建一个执行以下操作的嵌入式播放器：加载视频，播放 6 秒钟，然后停止播放。示例下面的列表对 HTML 中带编号的注释进行了说明。

<!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: '360',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          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>

以下列表更加详细地介绍了上述示例：

此部分中的 <div> 标记用于标识 IFrame API 将在网页上的什么位置插入视频播放器。播放器对象的构造函数（参见加载视频播放器部分中的说明）用于按 id 标识 <div> 标记，确保API在正确位置放置 <iframe>。具体而言，IFrame API 将以 <iframe> 标记替换 <div> 标记。

或者，您也可以直接在网页上插入 <iframe> 元素。有关具体步骤，请参阅加载视频播放器部分中的说明。
此部分中的代码用于加载 IFrame Player API JavaScript 代码。此示例利用 DOM 修改来下载 API 代码，确保系统以异步方式检索代码。<script> 标记的 async 属性（也能帮助实现异步下载）尚未在所有新型浏览器中获得支持，具体请参阅此堆栈溢出解答中的讨论。
onYouTubeIframeAPIReady 函数会在播放器 API 代码下载后马上运行。此部分代码会定义全局变量 player（指您要嵌入的视频播放器），而函数则据此构造视频播放器对象。
onPlayerReady 在 onReady 事件触发时运行。在本示例中，该函数指示当视频播放器就绪时就应开始播放。
API会在播放器状态改变时调用 onPlayerStateChange 函数，指示播放器正在播放、已暂停、已完成等等。该函数指定当播放器状态为1（正在播放）时，播放器应播放 6 秒钟，然后调用 stopVideo 函数停止播放视频。

加载视频播放器

在 API 的 JavaScript 代码加载后 API 就会调用 onYouTubeIframeAPIReady 函数，此时您可以构造YT.Player对象以在网页上插入视频播放器。下面的 HTML 片段显示了以上示例中的 onYouTubeIframeAPIReady 函数：

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

视频播放器的构造函数指定了以下参数：

第一个参数指定 DOM 元素或 HTML 元素id（API 将在其中插入包含播放器的 <iframe> 标记）。

IFrame API 将以包含播放器的 <iframe> 元素替换指定的元素。如果所替换的元素在显示样式上与插入的 <iframe> 元素有所不同，这可能会影响网页的版式。默认情况下，<iframe> 会显示为 inline-block 元素。
第二个参数是用于指定播放器选项的对象。该对象包含以下属性：
- width（数字）– 视频播放器的宽度。默认值为 640。
- height（数字）– 视频播放器的高度。默认值为360。
- videoId（字符串）– 用于标识播放器将加载的视频的YouTube视频ID。
- playerVars（对象）– 该对象的属性用于标识可用于自定义播放器的播放器参数。
- events（对象）– 该对象的属性用于标识 API 会触发的事件以及 API 将在这些事件发生时调用的函数（事件监听器）。在示例中，构造函数指示 onPlayerReady 函数在 onReady 事件触发时运行，而 onPlayerStateChange 函数在 onStateChange 事件触发时运行。

如开始使用部分中所述，您可以自行创建 <iframe> 标记，而不必在网页上撰写空的 <div> 元素（然后由播放器 API 的 JavaScript 代码以 <iframe> 元素替换之）。

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

如果您要撰写 <iframe> 标记，在构造 YT.Player 对象时，您不需要指定 width 和 height 的值（将作为 <iframe> 标记的属性指定），也不需要指定 videoId 和播放器参数（将在 src 网址中指定）。作为额外的安全措施，您还应在网址中添加origin参数，以参数值的形式指定网址架构（http:// 或 https://）和托管网页的完整域名。origin 为可选参数，添加此参数可避免第三方恶意注入 JavaScript 到您的网页中，劫持您的 YouTube 播放器。

示例部分列举了关于如何构造视频播放器对象的更多示例。

操作

要调用播放器 API 方法，您必须先引用要控制的播放器对象，方法是按照本文档的开始使用与加载视频播放器部分中的说明创建 YT.Player 对象。

函数

队列函数

队列函数可让您加载和播放视频、播放列表或其他视频列表。如果您使用下面讲述的对象语法调用这些函数，那么您也可以将搜索结果列表或已上传视频的用户列表加入播放队列或加载这些内容。

该 API 支持两种不同的队列函数调用语法。

参数语法要求函数参数以规定的顺序列出。
对象语法可让您传递一个对象作为单个参数，还可以让您为设置的函数参数定义对象属性。此外，该 API 还可以支持参数语法所不支持的其他功能。

例如，loadVideoById 函数可以通过以下任一方式调用。请注意，对象语法支持 endSeconds 属性，而参数语法则不支持。

参数语法

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

对象语法

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

视频队列函数

cueVideoById

参数语法

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

对象语法

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

此函数用于加载指定视频的缩略图，并准备用于播放视频的播放器。只有调用 playVideo() 或 seekTo() 之后，播放器才会请求 FLV。

必需参数 videoId 用于指定要播放的视频的 YouTube 视频 ID。在 YouTube Data API 视频 Feed 中，<yt:videoid> 代码用于指定 ID。
可选参数 startSeconds 接受浮点值/整数值，用于指定在调用 playVideo()后视频开始播放的时间。如果您在指定 startSeconds 值后调用 seekTo()，则播放器会根据 seekTo() 调用中指定的时间开始播放。在视频插入完毕而且可供播放时，播放器会广播 video cued 事件(5)。
可选参数 endSeconds 仅受对象语法支持，而且接受浮点值/整数值，用于指定调用 playVideo() 后视频停止播放的时间。如果您在指定 endSeconds 值后调用 seekTo()，则该 endSeconds 值就会失效。
可选参数 suggestedQuality 用于指定视频的建议播放质量。有关播放质量的更多信息，请参见setPlaybackQuality函数的定义。

loadVideoById

Argument syntax

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

Object syntax

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

此函数用于加载并播放指定的视频。

必需参数 videoId 用于指定待播视频的 YouTube 视频 ID。在 YouTube Data API 视频 Feed 中，<yt:videoid> 代码用于指定 ID。
可选参数 startSeconds 接受浮点值/整数值。如果指定该可选参数，则视频会从距离指定时间最近的关键帧开始播放。
可选参数 endSeconds 接受浮点值/整数值。如果指定该可选参数，则视频会在指定的时间停止播放。
可选参数 suggestedQuality 用于指定视频的建议播放质量。有关播放质量的更多信息，请参见 setPlaybackQuality 函数的定义。

cueVideoByUrl

Argument syntax

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

Object syntax

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

此函数用于加载指定视频的缩略图，并准备播放视频的播放器。仅在调用 playVideo() 或 seekTo() 之后，播放器才会请求 FLV。

必需参数 mediaContentUrl 用于指定完全符合要求的 YouTube 播放器网址，格式为 http://www.youtube.com/v/VIDEO_ID?version=3。在 YouTube Data API 视频 Feed 中，如果 <media:content> 代码的 format 属性值为 5，则表明该代码的 url 属性包含完全符合要求的播放器网址。
可选参数 startSeconds 接受浮点值/整数值，用于指定调用 playVideo() 后视频开始播放的时间。如果您在指定 startSeconds 后调用 seekTo()，则播放器会根据 seekTo() 调用中指定的时间开始播放。在视频插入完毕而且可供播放时，播放器会广播 video cued 事件(5)。
可选参数 endSeconds 仅受对象语法支持，而且接受浮点值/整数值，用于指定调用 playVideo() 后视频停止播放的时间。如果您在指定 endSeconds 值后调用 seekTo()，则该 endSeconds 值就会失效。
可选参数 suggestedQuality 用于指定视频的建议播放质量。有关播放质量的更多信息，请参见 setPlaybackQuality 函数的定义。

loadVideoByUrl

Argument syntax

player.loadVideoByUrl(mediaContentUrl:String,
                      startSeconds:Number,
                      suggestedQuality:String):Void

Object syntax

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

此函数用于加载并播放指定的视频。

必需参数 mediaContentUrl 用于指定完全符合要求的 YouTube 播放器网址，格式为 http://www.youtube.com/v/VIDEO_ID?version=3。在 YouTube Data API 视频 Feed 中，如果 <media:content> 代码的 format 属性值为 5，则表明该代码的 url 属性包含完全符合要求的播放器网址。
可选参数 startSeconds 接受浮点值/整数值，用于指定视频开始播放的时间。如果指定 startSeconds（数值可以是浮点值），则视频会从距离指定时间最近的关键帧开始播放。
可选参数 endSeconds 仅受对象语法支持，而且接受浮点值/整数值，用于指定视频停止播放的时间。
可选参数 suggestedQuality 用于指定视频的建议播放质量。有关播放质量的更多信息，请参见 setPlaybackQuality 函数的定义。

列表队列函数

cuePlaylist 和 loadPlaylist 函数允许您加载和播放播放列表或视频列表。如果您使用对象语法调用这些函数，那么您还可以将搜索结果列表或已上传视频的用户列表加入播放队列（或加载这些内容）。

由于函数的具体工作方式取决于它们的调用方法（参数语法还是对象语法），因此我们在下文提供了这两种调用方法的说明。

cuePlaylist

Argument syntax
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number,
                   suggestedQuality:String):Void
```
将指定的播放列表加入播放队列。在播放列表插入完毕而且可供播放时，播放器会广播 video cued事件(5)。
- 必需参数 playlist 用于指定 YouTube 视频 ID 数组。在 YouTube Data API Feed 中，<yt:videoid> 代码用于指定视频 ID。
- 可选参数 index 用于指定播放列表中首先播放的视频的索引。该参数使用从零开始的索引，且默认参数值为 0，因此，默认行为是加载和播放播放列表中的第一个视频。
- 可选参数 startSeconds 接受浮点值/整数值，用于指定调用 playVideo() 函数后播放列表中第一个视频开始播放的时间。如果您在指定 startSeconds 值后调用 seekTo()，则播放器会根据 seekTo() 调用中指定的时间开始播放。如果您在插入播放列表后调用 playVideoAt() 函数，则播放器会从指定视频的开头开始播放。
- 可选参数 suggestedQuality 用于指定视频的建议播放质量。有关播放质量的更多信息，请参见 setPlaybackQuality 函数的定义。
对象语法
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number,
                    suggestedQuality:String}):Void
```
将指定的视频列表加入播放队列。列表可以是播放列表、搜索结果 Feed 或用户的已上传视频 Feed。在列表插入完毕而且可供播放时，播放器会广播 video cued 事件(5)。
- 可选属性 listType 用于指定您检索的结果 Feed 的类型。有效值有 playlist、search 和 user_uploads。默认值为 playlist。
- 必需属性 list 包含一个键值，用于标识 YouTube 应返回的特定视频列表。
  - 如果 listType 属性值为 playlist，则 list 属性会指定播放列表 ID 或视频 ID 数组。在 YouTube Data API Feed 中，<yt:playlistid> 代码用于指定播放列表 ID，<yt:videoid> 代码用于指定视频 ID。
  - 如果 listType 属性值为 search，则 list 属性会指定搜索查询。
  - 如果 listType 属性值为 user_uploads，则 list 属性会标识将要返回的视频的上传者。
- 可选属性 index 用于指定列表中首先播放的视频的索引。该参数使用从零开始的索引，且默认参数值为0，因此，默认行为是加载和播放列表中的第一个视频。
- 可选属性 startSeconds 接受浮点值/整数值，用于指定调用 playVideo() 函数后列表中第一个视频开始播放的时间。如果您在指定 startSeconds 值后调用 seekTo()，则播放器会从 seekTo() 调用中指定的时间开始播放。如果您在插入列表后调用 playVideoAt() 函数，则播放器会从指定视频的开头开始播放。
- 可选属性 suggestedQuality 用于指定列表中视频的建议播放质量。有关播放质量的更多信息，请参见 setPlaybackQuality 函数的定义。

loadPlaylist

Argument syntax
```
player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number,
                    suggestedQuality:String):Void
```
此函数用于加载指定的播放列表并播放。
- 必需参数 playlist 用于指定 YouTube 视频 ID 数组。在 YouTube Data API Feed 中，<yt:videoid> 代码用于指定视频 ID。
- 可选参数 index 用于指定播放列表中首先播放的视频的索引。该参数使用从零开始的索引，且默认参数值为0，因此，默认行为是加载和播放播放列表中的第一个视频。
- 可选参数 startSeconds 接受浮点值/整数值，用于指定播放列表中第一个视频开始播放的时间。
- 可选参数 suggestedQuality 用于指定视频的建议播放质量。有关播放质量的更多信息，请参见 setPlaybackQuality 函数的定义。
Object syntax
```
player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number,
                     suggestedQuality:String}):Void
```
此函数用于加载指定的列表并播放。列表可以是播放列表、搜索结果 Feed 或用户的已上传视频 Feed。
- 可选属性 listType 用于指定您检索的结果 Feed 的类型。有效值有 playlist、search 和 user_uploads。默认值为 playlist。
- 必需属性 list 包含一个键值，用于标识 YouTube 应返回的特定视频列表。
  - 如果 listType 属性值为 playlist，则 list 属性会指定播放列表 ID 或视频 ID 数组。在 YouTube Data API Feed 中，<yt:playlistid> 代码用于指定播放列表 ID，<yt:videoid> 代码用于指定视频 ID。
  - 如果 listType 属性值为 search，则 list 属性会指定搜索查询。
  - 如果 listType 属性值为 user_uploads，则 list 属性会标识将要返回的视频的上传者。
- 可选属性 index 用于指定列表中首先播放的视频的索引。该参数使用从零开始的索引，且默认参数值为0，因此，默认行为是加载和播放列表中的第一个视频。
- 可选属性 startSeconds 接受浮点值/整数值，用于指定列表中第一个视频开始播放的时间。
- 可选属性 suggestedQuality 用于指定列表中视频的建议播放质量。有关播放质量的更多信息，请参见 setPlaybackQuality 函数的定义。

播放控制和播放器设置

播放视频

player.playVideo():Void: 播放当前已插入/已加载的视频。此函数执行后，播放器的最终状态将是 playing (1)。

注意：只有通过播放器中的原生播放按钮启动播放，本次播放才会计入视频的官方观看次数。

player.pauseVideo():Void: 暂停当前正在播放的视频。除非调用此函数时，播放器的状态为 ended (0)（在这种情况下，播放器的状态不会改变），否则此函数执行后，播放器的最终状态将是 paused (2)。

player.stopVideo():Void: 停止和取消加载当前视频。您应将此函数保留以用于极少数情况（例如，您知道用户不会观看播放器中的其他视频）。如果您的目的是要暂停视频，那么您应该只调用 pauseVideo 函数。如果您想改变播放器播放的视频，那么您可以调用某个队列函数，而无需先调用 stopVideo。

重要提示：与 pauseVideo 函数（此函数会使播放器处于 paused (2) 状态）不同，stopVideo 函数会使播放器处于任意非播放状态，包括 ended (0)、paused (2)、video cued (5) 或 unstarted (-1)。

player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void

定位到视频的指定时间。如果调用该函数时播放器已暂停，则播放器会保持暂停状态。如果调用该函数时播放器处于其他状态（playing、video cued等），则播放器会播放视频。

参数seconds用于标识播放器快进的单位时间。

除非播放器已经下载了用户正在定位到的视频部分，否则播放器会快进到距离指定时间最近的关键帧。在这种情况下，播放器会快进到距离 Flash 播放器 NetStream 对象的 seek() 方法指示的时间前后最近的关键帧（有关详情，请参阅 Adobe 的文档）。
allowSeekAhead 参数用于确定在 seconds 参数指定的时间超出了当前已缓冲的视频数据对应的播放时间时，播放器是否向服务器发送新的请求。

当用户沿视频进度条拖动鼠标时，我们建议您将此参数设置为 false，当用户松开鼠标时，将其设置为 true。此方法可让用户滚动到视频的不同时间点，而无需在滚动过视频中未缓冲的时间点时请求新的视频流。当用户松开鼠标按钮后，播放器会快进到视频中的相应时间点，并在必要时请求新的视频流。

player.clearVideo():Void: 清除视频显示。如果您想在调用 stopVideo() 后清除视频残留，那么此函数非常有用。请注意，ActionScript 3.0 Player API 已弃用此函数。

播放播放列表中的视频

player.nextVideo():Void

此函数用于加载并播放播放列表中的下一个视频。

如果在观看播放列表中的最后一个视频且将播放列表设置为连续播放 (loop) 时调用 player.nextVideo()，则播放器将会加载并播放列表中的第一个视频。
如果在观看播放列表中的最后一个视频且未将播放列表设置为连续播放时调用 player.nextVideo()，则播放将会结束。

player.previousVideo():Void

此函数用于加载并播放播放列表中的上一个的视频。

如果在观看播放列表中的第一个视频且将播放列表设置为连续播放 (loop) 时调用 player.previousVideo()，则播放器将会加载并播放列表中的最后一个视频。
如果在观看播放列表中的第一个视频且未将播放列表设置为连续播放时调用 player.previousVideo()，则播放器将会从开头开始重新播放第一个播放列表。

player.playVideoAt(index:Number):Void

此函数用于加载并播放播放列表中的指定视频。

必需参数 index 用于指定播放列表中待播放视频的索引。该参数使用从零开始的索引，因此值为0时标识列表中的第一个视频。如果您已随机播放播放列表，则此函数将会播放随机播放列表中指定位置的视频。

更改播放器的音量

player.mute():Void: 使播放器静音。

player.unMute():Void: 取消播放器静音。

player.isMuted():Boolean: 如果播放器处于静音状态，则返回true；否则返回false。

player.setVolume(volume:Number):Void: 设置音量。接受 0 到 100 之间的整数。

player.getVolume():Number: 返回播放器的当前音量，以 0 到 100 之间的整数值表示。请注意，即使播放器处于静音状态，getVolume() 也会返回音量值。

设置播放器的大小

player.setSize(width:Number, height:Number):Object: 设置包含播放器的<iframe>的大小（以像素为单位）。

设置播放速率

player.getPlaybackRate():Number: 此函数用于检索当前正在播放的视频的播放速率。默认播放速率为1，这表明视频以正常速度播放。播放速率的值可以为 0.25、0.5、1、1.5 和 2。

player.setPlaybackRate(suggestedRate:Number):Void: 此函数用于设置当前视频的建议播放速率。如果播放速率改变，那么此函数将仅改变已插入或正在播放的视频的速率。如果您设置了插入视频的播放速率，则在调用 playVideo 函数或用户直接通过播放器控件启动播放后，该速率仍然有效。此外，调用函数插入或加载视频或播放列表（cueVideoById、loadVideoById 等）会将播放速率重置为 1。

调用此函数并不意味着播放速率一定会发生实际变化。但是，如果播放速率确实变化了，那么就会触发 onPlaybackRateChange 事件，而您的代码应该响应该事件，而不是调用 setPlaybackRate 函数。

getAvailablePlaybackRates 方法将返回当前正在播放的视频可能的播放速率。但是，如果您将 suggestedRate 参数设置为不支持的整数值或浮点值，则播放器将朝 1 的方向舍入到与支持的值最接近的值。

player.getAvailablePlaybackRates():Array: 此函数用于返回适合当前视频的播放速率集。默认值为1，该值表明视频正以正常速度播放。

此函数用于返回播放速度从最慢到最快排列的数值数组。即使播放器不支持变速播放，该数组也始终应至少包含一个值 (1)。

设置播放列表的播放行为

player.setLoop(loopPlaylists:Boolean):Void

此函数用于指明视频播放器应连续播放播放列表，还是应在播放列表中的最后一个视频结束之后停止播放。默认行为是播放列表不循环播放。

即使您加载或插入其他播放列表，该设置也会保留，这就意味着，如果您加载一个播放列表，调用值为 true 的 setLoop 函数，然后加载第二个播放列表，那么第二个播放列表也将循环播放。

必需参数 loopPlaylists 用于标识循环播放行为。

如果参数值为 true，则视频播放器会连续播放播放列表。播放播放列表中的最后一个视频之后，视频播放器将回到播放列表开头，重新播放。
如果参数值为 false，则在视频播放器播放完播放列表中的最后一个视频之后，播放就会结束。

player.setShuffle(shufflePlaylist:Boolean):Void

此函数用于指出播放列表中的视频是否应随机播放，以便使这些视频以不同于播放列表创建者指定的顺序播放。如果您在播放列表开始播放之后再将其设置为随机播放，则该列表将会重新排序，而正在播放的视频会继续播放。下一个要播放的视频会基于重新排序后的列表进行选择。

如果您加载或插入其他播放列表，则该设置不会保留，这就意味着，如果您加载一个播放列表，调用 setShuffle 函数，然后加载第二个播放列表，那么第二个播放列表不会随机播放。

必需参数 shufflePlaylist 用于指示 YouTube 是否应随机播放播放列表。

如果参数值为 true，则 YouTube 会随机调整播放列表顺序。如果您指示此函数随机播放某个已设置为随机播放的播放列表，则 YouTube 将会再次调整随机播放顺序。
如果参数值为 false，则 YouTube 会将播放列表更改回原来的顺序。

播放状态

player.getVideoLoadedFraction():Float: 返回 0 和 1 之间的数值，用于指定缓冲时播放器显示的视频百分比。与现已弃用的 getVideoBytesLoaded 和 getVideoBytesTotal 方法相比，该方法可以返回更可靠的数值。

player.getPlayerState():Number

返回播放器的状态。可用的值为：

-1 – 未开始
0 – 已结束
1 – 正在播放
2 – 已暂停
3 – 正在缓冲
5 – 已插入视频

player.getCurrentTime():Number: 返回视频已播放的时长（以秒为单位）。

player.getVideoStartBytes():Number: 已于2012年10月31日弃用。返回视频文件的加载点前已有的字节数（此方法现在返回的值始终为 0）。示例情况：用户向前定位到一个尚未加载的时间点，于是播放器发起播放视频中尚未加载的片段的新请求。

player.getVideoBytesLoaded():Number: 已于2012年7月18日弃用。请改为使用getVideoLoadedFraction方法确定已缓冲的视频百分比。

此方法用于返回 0 到 1000 之间的值，该值会估算已加载的视频量。您可以用 getVideoBytesLoaded 值除以 getVideoBytesTotal 值计算出视频的已加载部分。

player.getVideoBytesTotal():Number: 已于 2012 年 7 月 18 日弃用。请改为使用 getVideoLoadedFraction 方法确定已缓冲的视频百分比。

返回当前已加载/正在播放的视频的大小或视频大小的近似值（以字节为单位）。

此方法始终会返回值 1000。您可以用 getVideoBytesLoaded 值除以 getVideoBytesTotal 值计算出视频的已加载部分。

播放质量

player.getPlaybackQuality():String: 此函数用于检索当前视频的实际质量。可能的返回值包括highres、hd1080、hd720、large、medium 和 small。如果当前没有视频，则该函数会返回 undefined。

player.setPlaybackQuality(suggestedQuality:String):Void

此函数用于设置当前视频的建议质量。该函数可使视频在当前位置以另一种视频质量重新加载。如果更改了播放质量，则此更改只会影响当前正在播放的视频。调用此函数并不意味着播放质量一定会发生实际变化。但是，如果播放质量确实变化了，那么就会触发onPlaybackQualityChange事件，而您的代码应该响应该事件，而不是调用 setPlaybackQuality 函数。

suggestedQuality 参数的值可以为small、medium、large、hd720、hd1080、highres 或 default。我们建议您将参数值设置为 default，这会指示 YouTube 选择最适合的播放质量，具体质量会因不同用户、视频、系统和其他播放条件而异。

如果您建议使用特定质量播放某个视频，则只有该视频会采用建议的质量。您选择的播放质量应该适合视频播放器的大小。例如，如果网页上显示的是 1280x720 像素的视频播放器，则hd720级别的视频质量的实际显示效果要优于 hd1080 级别的视频质量。我们建议调用 getAvailableQualityLevels() 函数来确定哪些质量级别适用于某个视频。

下面的列表列出了不同标准的播放器大小适合的播放质量级别。我们建议您将视频播放器的高度设置为以下某个值，并将播放器大小调整为使用 16:9 的宽高比。如上所述，即使您选择标准播放器大小，我们也建议您将 suggestedQuality 参数的值设置为 default，以使 YouTube 可以选择最合适的播放质量。

small 质量级：播放器高度为 240 像素，且播放器尺寸至少为 320x240 像素才能符合 4:3 的宽高比。
medium 质量级：播放器高度为360像素，且播放器尺寸为 640x360 像素（符合16:9的宽高比）或 480x360 像素（符合 4:3 的宽高比）。
large 质量级：播放器高度为480像素，且播放器尺寸为 853x480 像素（符合 16:9 的宽高比）或 640x480 像素（符合 4:3 的宽高比）。
hd720 质量级：播放器高度为 720 像素，且播放器尺寸为 1280x720 像素（符合 16:9 的宽高比）或 960x720像素（符合 4:3 的宽高比）。
hd1080 质量级：播放器高度为 1080 像素，且播放器尺寸为 1920x1080 像素（符合 16:9 的宽高比）或 1440x1080 像素（符合 4:3 的宽高比）。
highres 质量级：播放器高度大于1080像素，这意味着播放器的宽高比大于 1920x1080 像素。
default 质量级：YouTube 会选择合适的播放质量。此设置会将质量级别有效地恢复到默认状态，并会撤消以前通过使用 cueVideoById、loadVideoById 或 setPlaybackQuality 函数设置播放质量的全部操作。

如果您在调用 setPlaybackQuality 函数时使用了不适合视频的质量级别 suggestedQuality，则系统会将质量设置为适合视频的下一个最低级别。例如，如果您请求的质量级别为 large，但该级别并不适用，则系统会将播放质量设置为 medium（前提是该质量级别适用）。

此外，将 suggestedQuality 设置为一个无法识别的质量级别就相当于将 suggestedQuality 设置为 default。

player.getAvailableQualityLevels():Array: 此函数可返回适合当前视频的一系列质量格式。您可以使用此函数确定是否存在比用户所观看质量更高的视频质量，这样播放器就可以显示按钮或其他元素供用户调整质量。

该函数返回的是按质量顺序由高到低排列的字符串数组。可用的数组元素值包括highres、hd1080、hd720、large、medium 和 small。如果当前没有任何视频，则此函数会返回空数组。

您的客户端不应自动选择使用质量最高（或最低）的视频，也不应自动选择使用未知的格式名称。YouTube 会扩充质量级别列表，其中包含的某些格式可能不适用于您的播放器环境。同样，YouTube 也会删除影响用户体验的质量选项。您应确保自己的客户端只会选择已知的有效格式，这样在引入新的质量级别或删除不适用于您播放器环境的质量级别时，就可以确保您的客户端效果不会受到这些因素的影响。

检索视频信息

player.getDuration():Number: 返回当前正在播放的视频的时长（以秒为单位）。请注意，如果视频的元数据尚未加载，则 getDuration() 会返回 0，这通常会在视频刚开始播放后发生。

如果当前播放的视频是直播活动，则 getDuration() 函数将会返回自视频开始直播起已播放的时间。具体而言，这是视频在未重置或中断的情况下直播的时长。此外，此持续时间通常长于实际的活动时间，因为直播可能会在活动开始时间之前开始。

player.getVideoUrl():String: 返回当前已加载/正在播放的视频的 YouTube.com 网址。

player.getVideoEmbedCode():String: 返回当前已加载/正在播放的视频的嵌入代码。

检索播放列表信息

player.getPlaylist():Array: 此函数用于按当前顺序返回播放列表中视频ID的数组。默认情况下，此函数将以播放列表所有者指定的顺序返回视频 ID。但是，如果您已调用了 setShuffle 函数将播放列表顺序设置为随机播放，则 getPlaylist() 函数的返回值将反映随机播放顺序。

player.getPlaylistIndex():Number

此函数用于返回当前正在播放的播放列表中视频的索引。

如果您尚未随机播放播放列表，则返回值将会标识播放列表创建者放置视频的位置。返回值使用从零开始的索引，因此值为0时标识播放列表中的第一个视频。
如果您已随机播放播放列表，则返回值将会确定随机播放的播放列表中视频的顺序。

添加或移除事件监听器

player.addEventListener(event:String, listener:String):Void: 为指定的 event 添加监听器函数。下文的事件部分介绍了播放器可能会触发的不同事件。监听器是一个字符串，用于指定触发指定事件时执行的函数。

player.removeEventListener(event:String, listener:String):Void: 为指定的event移除监听器函数。listener 是一个字符串，用于指定触发指定事件时不再执行的函数。

访问和修改 DOM 节点

player.getIframe():Object: 此方法用于返回嵌入式 <iframe> 的 DOM 节点。

player.destroy():Void: 移除包含播放器的 <iframe>。

事件

API会触发事件来向您的应用通知嵌入式播放器发生的变化。如上一部分所述，您可以在构造YT.Player对象时添加事件监听器来订阅事件，也可以使用addEventListener函数。

API会将事件对象作为单独的参数传递给每个函数。事件对象具有以下属性：

事件的target用于标识与事件相对应的视频播放器。
事件的data用于指定与事件相关的值。请注意，onReady事件不会指定data属性。

以下列表定义了API触发的事件：

onReady

此事件在每次播放器完成加载并准备好开始接收API调用时触发。如果您希望在播放器准备就绪时马上自动执行某些操作（例如播放视频或显示视频信息），您的应用就应该实施此函数。

下面的示例包含用于处理此事件的函数样本。API传递给函数的事件对象拥有用于标识播放器的target属性。该函数会检索当前所加载视频的嵌入代码，开始播放视频，并在拥有embed-code的id值的页面元素中显示嵌入代码。

function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}

onStateChange

此事件在每次播放器的状态改变时触发。 API传递给事件监听器函数的事件对象的data属性会指定一个与新播放器状态相对应的整数。可能的值包括：

-1（未开始）
0（已结束）
1（正在播放）
2（已暂停）
3（正在缓冲）
5（视频已插入）

播放器首次加载视频时会广播unstarted (-1)事件。在视频插入完毕且可供播放时，播放器会广播video cued (5)事件。在代码中，您可以指定整数值或使用下列某个命名空间变量：

YT.PlayerState.ENDED
YT.PlayerState.PLAYING
YT.PlayerState.PAUSED
YT.PlayerState.BUFFERING
YT.PlayerState.CUED

onPlaybackQualityChange

此事件在每次视频播放质量改变时触发。例如，如果您调用setPlaybackQuality(suggestedQuality)函数，此事件就会在播放质量实际发生改变时触发。您的应用应对事件进行响应，且不应假设播放质量会自动在系统调用setPlaybackQuality(suggestedQuality)函数时改变。同样，您的代码也不应假设只有在明确调用setPlaybackQuality或任何其他允许您设置建议的播放质量后才会改变。

API传递给事件监听器函数的事件对象的data属性值是一个标识新播放质量的字符串。可能的值包括：

small
medium
large
hd720
hd1080
highres

onPlaybackRateChange: 此事件在每次视频播放速率改变时触发。例如，如果您调用setPlaybackRate(suggestedRate)函数，此事件就会在播放速率实际发生改变时触发。您的应用应对事件进行响应，且不应假设播放速率会自动在系统调用setPlaybackRate(suggestedRate)函数时改变。同样，您的代码也不应假设只有在明确调用setPlaybackRate后视频播放速率才会改变。

API传递给事件监听器函数的事件对象的data属性值会是一个标识新播放速率的数字。 getAvailablePlaybackRates方法会针对当前已插入或正在播放的视频返回一个有效播放速率的列表。

onError

此事件在播放器出错时触发。 API将向事件监听器函数传递一个event对象。该对象的data属性将指定一个标识所发生的错误类型的整数。可能的值包括：

2 – 请求包含无效的参数值。例如，如果您指定的视频ID不足11个字符，或者如果视频ID包含无效字符（例如感叹号或星号），就会发生此错误。
5 – 请求的内容无法在HTML5播放器中播放，或者发生了与HTML5播放器有关的其他错误。
100 – 找不到所请求的视频。当视频已被移除（无论是何种原因）或者被标记为私有状态时，就会发生此错误。
101 – 所请求的视频的所有者不允许在嵌入式播放器中播放此视频。
150 – 此错误与101相同，实际就是变相的101错误！

onApiChange

此事件触发时就表示播放器已利用提供的API方法加载（或已取消加载）模块。您的应用可监听此事件，然后轮询播放器以确定为最近加载的模块指定的选项。然后，您的应用可以检索或更新这些选项的现有设置。

以下命令可检索一系列您可为其设置播放器选项的模块名称：

player.getOptions();

目前，您只能为cc模块设置选项，此模块负责处理播放器中的字幕。在收到onApiChange事件时，您的应用可使用以下命令来确定能为cc模块设置哪些选项：

player.getOptions('cc');

通过利用此命令轮询播放器，您可以确认自己想要访问的选项是否真的可以访问。以下命令可检索并更新模块选项：

检索选项：
player.getOption(module, option);

设置选项：
player.setOption(module, option, value);

以下表格列出了API支持的选项：

模块	选项	说明
cc	fontSize	此选项可调整播放器中显示的字幕的字号大小。有效的值为`-1`、`0`、`1`、`2`和`3`。默认大小为`0`，最小为`-1`。如果将此选项设为小于`-1`的整数，系统会以最小字号来显示字幕；如果将此选项设为大于`3`的整数，系统将以最大字号来显示字幕。
cc	reload	此选项会为正在播放的视频重新加载字幕数据。如果检索此选项的值，值将显示为`null`。将值设为`true`即可重新加载字幕数据。

移动设备注意事项

自动播放和按脚本播放

在某些移动浏览器（如Chrome和Safari）中，HTML5 <video>元素只允许由用户互动（如点按播放器）发起的播放。以下内容摘录自Apple文档：

“警告：为避免在用户未请求的情况下通过移动网络进行下载并向用户扣费，禁止在iOS上的Safari浏览器中自动播放嵌入式媒体 — 播放必须始终由用户发起。”

由于此限制，autoplay、playVideo()及loadVideoById()等函数与参数将无法在某些移动环境中工作。

示例

创建YT.Player对象

示例1：大音量播放

此示例将创建1280 x 720像素的视频播放器。然后，onReady事件的事件监听器将调用setVolume函数来将音量调整到最高设置。

function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    width: 1280,
    height: 720,
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

function onPlayerReady(event) {
  event.target.setVolume(100);
  event.target.playVideo();
}

示例2：此示例会设置专门的播放器参数，以在视频加载时自动播放视频并隐藏视频播放器的控件。它还会针对API广播的所有事件添加事件监听器。

function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    videoId: 'M7lc1UVf-VE',
    playerVars: { 'autoplay': 1, 'controls': 0 },
    events: {
      'onReady': onPlayerReady,
      'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}