本文已参与「新人创作礼」活动，一起开启掘金创作之路。

YouTube 嵌入式播放器及播放器参数

概览

本文档介绍如何在应用中嵌入 YouTube 播放器，并定义了 YouTube 嵌入式播放器可以使用的参数。

通过将参数附加到 iframe 网址末尾，您可以自定义应用中的播放体验。例如，您可以使用 autoplay 参数自动播放多个视频，也可以使用 loop 参数重复播放一个视频。您还可以使用 enablejsapi 参数，允许通过 iframe Player API 控制播放器。

目前，本页面定义了任意 YouTube 嵌入式播放器支持的全部参数。每个参数定义均会确定支持相应参数的播放器。

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

嵌入 YouTube 播放器

您可以使用以下任意一种方法在应用中嵌入 YouTube 播放器并指定播放器参数。请注意，以下说明将介绍如何嵌入会加载单个视频的播放器。接下来的部分将说明如何配置您的播放器，以便加载其他类型的内容（例如播放列表和搜索结果）。

使用 `<iframe>` 标记嵌入播放器

在您的应用中定义一个 <iframe> 标记，其中 src 网址用于指定播放器将要加载的内容以及您想设置的其他任何播放器参数。<iframe> 标记的 height 和 width 参数指定了播放器的尺寸。

如果您自行创建 <iframe> 元素（而不是使用 iframe Player API 创建），则可以直接将播放器参数附加到网址末尾。网址格式如下：

<span style="color:var(--devsite-code-color)">https://www.youtube.com/embed/<strong>VIDEO_ID</strong></span>

以下 <iframe> 标记将会加载一个可用来播放 YouTube 视频 M7lc1UVf-VE 的 640x360 像素的播放器。由于网址中 autoplay 参数设置为 1，因此视频会在播放器加载完后自动播放。

<span style="color:var(--devsite-code-color)"><iframe id="ytplayer" type="text/html" width="640" height="360"
  src="https://www.youtube.com/embed/M7lc1UVf-VE?autoplay=1&origin=http://example.com"
  frameborder="0"></iframe>
</span>

使用 iframe Player API 嵌入播放器

请按照 iframe Player API 说明，在 iframe Player API 的 JavaScript 代码加载之后，在网页或应用中插入视频播放器。视频播放器构造函数中的第二个参数是指定播放器选项的对象。在此对象中，playerVars 属性会确定播放器参数。

以下 HTML 和 JavaScript 代码展示了一个简单示例，即将 YouTube 播放器插入 id 值为 ytplayer 的页面元素。系统会在 iframe Player API 代码加载完成后自动调用此处指定的 onYouTubePlayerAPIReady() 函数。此代码不会定义任何播放器参数，也不会定义其他事件处理脚本。

<span style="color:var(--devsite-code-color)"><div id="ytplayer"></div>

<script>
  // Load the IFrame Player API code asynchronously.
  var tag = document.createElement('script');
  tag.src = "https://www.youtube.com/player_api";
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  // Replace the 'ytplayer' element with an <iframe> and
  // YouTube player after the API code downloads.
  var player;
  function onYouTubePlayerAPIReady() {
    player = new YT.Player('ytplayer', {
      height: '360',
      width: '640',
      videoId: 'M7lc1UVf-VE'
    });
  }
</script>
</span>

选择要播放的内容

您可以配置已嵌入的播放器，以加载视频、播放列表、用户上传的视频或针对特定查询的搜索结果。

以下列表介绍了这些选项：

加载视频

对于使用 iframe 嵌入的播放器，您要加载的视频的 YouTube 视频 ID 是在 iframe 的 src 网址中指定的。
```
https://www.youtube.com/embed/VIDEO_ID
```
如果您使用了 YouTube Data API (v3)，则可以从搜索结果、播放列表项资源、视频资源或其他资源中检索视频 ID，以编程方式构建这些网址。获取视频 ID 之后，请使用该值替换上述网址中的 VIDEO_ID 文字以创建播放器网址。
加载播放列表

将 listType 播放器参数设为 playlist。此外，将 list 播放器参数设为您想加载的 YouTube 播放列表 ID。
```
<span style="color:var(--devsite-code-color)">https://www.youtube.com/embed?listType=playlist&list=<strong>PLAYLIST_ID</strong></span>
```
请注意，播放列表 ID 需要以字母 PL 作为前缀，如下例所示：
```
<span style="color:var(--devsite-code-color)">https://www.youtube.com/embed?listType=playlist&list=<strong>PLC77007E23FF423C6</strong></span>
```
如果您使用的是 YouTube Data API (v3)，则可以从搜索结果、频道资源或活动资源中检索播放列表 ID，以编程方式构建这些网址。获得播放列表 ID 之后，请使用该值替换上述网址中的 PLAYLIST_ID 文字。
加载用户上传的视频

将 listType 播放器参数设为 user_uploads，然后将 list 播放器参数设为 YouTube 用户名，加载自己喜欢的对象所上传的视频。
```
<span style="color:var(--devsite-code-color)">https://www.youtube.com/embed?listType=user_uploads&list=<strong>USERNAME</strong></span>
```
加载指定查询的搜索结果

将 listType 播放器参数设为 search，然后将 list 播放器参数设置为您希望的查询字词，让播放器加载相应的搜索结果。
```
<span style="color:var(--devsite-code-color)">https://www.youtube.com/embed?listType=search&list=<strong>QUERY</strong></span>
```

支持的参数

下面所有的参数都是可选的。

参数
### `autoplay`	此参数用于指定是否在播放器加载时自动开始播放初始视频。支持的值为 `0` 或 `1`。默认值为 `0`。
### `cc_lang_pref`	此参数用于指定播放器将用于显示字幕的默认语言。请将参数值设置为两个字母组成的 ISO 639-1 语言代码。如果您使用此参数且将 `cc_load_policy` 参数设为 `1`，则在播放器加载时，播放器将会以指定的语言显示字幕。如果您还未设置 `cc_load_policy` 参数，则默认情况下字幕将不会显示，但如果用户选择打开字幕，则字幕将会以指定的语言显示。
### `cc_load_policy`	将参数值设置为 `1` 会使系统在默认情况下显示字幕，即使在用户此前关闭了字幕的情况下也是如此。默认行为基于用户偏好设置。
### `color`	此参数用于指定在播放器的视频进度条中用来突出显示观看者已经看过的视频长度的颜色。有效的参数值包括 `red` 和 `white`，而且在默认情况下，播放器将在视频进度条中使用红色。如需详细了解颜色选项，请参阅 YouTube API 博客。注意：将 `color` 参数设置为 `white` 会停用 `modestbranding` 选项。
### `controls`	此参数用于指明视频播放器控件是否会显示：- `controls=0` - 播放器控件不会在播放器中显示。

controls=1（默认值）- 播放器控件会在播放器中显示。 | | ### disablekb | 将参数值设置为 1 会导致播放器无法响应键盘控制键。默认值为 0，表示支持键盘控制键。目前支持的键盘控制键如下：- 空格键或 [k] 键：播放/暂停
向左箭头键：在当前视频中向后跳 5 秒
向右箭头键：在当前视频中向前跳 5 秒
向上箭头键：调高音量
向下箭头键：调低音量
[f] 键：切换全屏显示
[j] 键：在当前视频中向后跳 10 秒
[l] 键：在当前视频中向前跳 10 秒
[m] 键：将视频静音或取消静音
[0-9] 键：跳转到视频中的某一位置。0 键用于跳转到视频的开头、1 键用于跳转到视频的 10% 这一位置、2 键用于跳转到视频的 20% 这一位置，依此类推。 | | ### enablejsapi | 将参数值设置为 1 则可允许通过 iframe 或 JavaScript Player API 调用来控制播放器。默认值为 0，表示无法使用这些 API 控制播放器。如需详细了解 iframe API 及其用法，请参阅 iframe API 文档（JavaScript Player API 已被弃用）。 | | ### end | 此参数用于指定时间，以秒为单位，自视频开头开始计算，直到播放器应该停止播放视频时为止。此参数值是正整数。请注意，时间是从视频开头而不是从 start 播放器参数值或 startSeconds 参数值开始计算的；此时间在 YouTube Player API 函数中用于加载视频或将视频加入队列。 | | ### fs | 将此参数设置为 0 可以阻止全屏按钮显示在播放器中。默认值为 1，该值会使全屏按钮显示。 | | ### hl | 设置播放器的界面语言。此参数值是两个字母组成的 ISO 639-1 语言代码或完整表示的语言区域。例如，fr 和 fr-ca 都是有效值。系统或许也能正确处理 IETF 语言标记 (BCP 47) 之类的语言输入代码。界面语言用于播放器中的工具提示，而且还会影响默认的字幕轨道。请注意，YouTube 可能会根据特定用户的个人语言偏好设置和提供的字幕轨道，为该用户选择其他字幕轨道语言。 | | ### iv_load_policy | 将参数值设置为 1 会在默认情况下显示视频注释，而将其设置为 3 则默认不显示。默认值为 1。 | | ### list | list 参数与 listType 参数搭配使用时可确定播放器中将要加载的内容。- 如果 listType 参数的值为 search，则 list 参数值会指定搜索查询。
如果 listType 参数的值为 user_uploads，则 list 参数值会确定将要加载的已上传视频所在的 YouTube 频道。
如果 listType 参数的值为 playlist，则 list 参数值会指定 YouTube 播放列表 ID。在参数值中，您需要使用字母 PL 为播放列表 ID 添加前缀，如下例所示。
```
<span style="color:var(--devsite-code-color)">https://www.youtube.com/embed?     listType=playlist     &list=PLC77007E23FF423C6</span>
```
注意：如果您指定 list 和 listType 参数的值，则 iframe 嵌入网址就无需指定视频 ID。 | | ### listType | listType 参数与 list 参数搭配使用时可确定播放器中将要加载的内容。有效的参数值包括 playlist、search 和 user_uploads。如果您指定 list 和 listType 参数的值，则 iframe 嵌入网址就无需指定视频 ID。 | | ### loop | 如果播放器是单视频播放器，则将此值设置为 1 会使播放器反复播放初始视频。如果播放器是播放列表播放器（或自定义播放器），则会播放整个播放列表中的视频，然后再从第一个视频开始播放。支持的值为 0 和 1，默认值为 0。注意：此参数在 AS3 播放器和 iframe 嵌入式播放器（可能会加载 AS3 或 HTML5 播放器）中得到的支持会受到限制。目前，仅在与 playlist 参数结合使用时，loop 参数才能在 AS3 播放器中起作用。要循环播放单个视频，请将 loop 参数值设置为 1，并将 playlist 参数值设置为与 Player API 网址中已指定的视频 ID 相同的值： ``` www.youtube.com/v/VIDEO_ID? version=3 &loop=1 &playlist=VIDEO_ID

| ### `modestbranding`  | 此参数可让您使用不显示 YouTube 徽标的 YouTube 播放器。将参数值设置为 `1` 可以阻止 YouTube 徽标显示在控制栏中。请注意，当用户的鼠标指针悬停在播放器上方时，一个小 `YouTube` 文字标签仍将显示在暂停的视频的右上角。                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ### `origin`          | 此参数为 iframe API 提供额外的安全措施，而且仅支持 iframe 嵌入式播放器。如果您使用了 iframe API，这意味着您会将 `enablejsapi` 参数值设置为 `1`，那么您应始终将网域指定为 `origin` 参数值。                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ### `playlist`        | 此参数用于指定要播放的视频 ID 列表（以英文逗号分隔）。如果您指定一个值，则播放的第一个视频将是网址路径中指定的 `VIDEO_ID` 对应的视频，而在 `playlist` 参数中指定的视频将在随后播放。                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ### `playsinline`     | 此参数用于控制视频在 iOS 设备上的 HTML5 播放器中播放时，是以内嵌方式还是全屏模式播放。有效值如下：-   `0`：如果使用该值，视频将以全屏模式播放。目前默认使用此值，但以后可能会变。
-   `1`：如果使用该值，则在 `allowsInlineMediaPlayback` 属性值设置为 `TRUE` 的情况下创建的 `UIWebViews` 会以内嵌方式播放。                                                                                                                                                                                                                                                                                                                                                        |
| ### `rel`             | **注意**：此参数在 2018 年 9 月 25 日当天或之后[有调整](https://developers.google.com/youtube/player_parameters#release_notes_08_23_2018 "有调整")。  在更改前，此参数用于指示初始视频播放结束时，播放器是否应显示相关视频。-   如果参数值设置为 `1`（默认值），则播放器会显示相关视频。
-   如果参数值设置为 `0`，则播放器不会显示相关视频。在更改后，您将无法停用相关视频。相反，如果 `rel` 参数设置为 `0`，则相关视频将来自与刚播放的视频相同的频道。                                                                                                                                                                                                                                                      |
| ### `showinfo`        | **注意**：2018 年 9 月 25 日后，此参数已被[弃用](https://developers.google.com/youtube/player_parameters#release_notes_08_23_2018 "弃用")，并会被忽略。  支持的值包括：`0` 和 `1`。  如果将参数值设置为 `0`，则在视频开始播放之前，播放器不会显示视频标题和上传者等信息。  如果播放器正在加载播放列表，而且您已明确将该参数值设置为 `1`，那么播放列表加载时，播放器还将显示播放列表中视频的缩略图。                                                                                                                                                                                                                                                                                     |
| ### `start`           | 此参数可让播放器从视频中的指定位置开始播放视频，具体位置以距视频开头的秒数表示。此参数值是正整数。请注意，与 `seekTo` 函数类似，播放器会查找与指定时间最接近的关键帧。这就意味着，播放指针有时可能会停在请求时间之前几秒的位置，通常与请求时间相差不超过 2 秒。                                                                                                                                                                                                                                                                                                                                                                                                               |
| ### `widget_referrer` | 此参数用于标识在其中嵌入了播放器的网址。如果 YouTube 播放器嵌入到了微件中，而该微件随后嵌入到网页或应用中，则 YouTube 数据分析报告中会使用此值。在这种情况下，`origin` 参数用于标识微件提供商的网域，但 YouTube 数据分析不会将微件提供商标识为实际的流量来源。相反，YouTube 数据分析会改用 `widget_referrer` 参数值以标识与流量来源关联的网域。                                                                                                                                                                                                                                                                                                                                              |

YouTube iframe嵌入式播放器及播放器参数 自动播放，循环播放，播放列表，不显示 YouTube 徽标

YouTube 嵌入式播放器及播放器参数

概览

嵌入 YouTube 播放器

使用 <iframe> 标记嵌入播放器

使用 iframe Player API 嵌入播放器

选择要播放的内容

支持的参数

YouTube iframe嵌入式播放器及播放器参数自动播放，循环播放，播放列表，不显示 YouTube 徽标

使用 `<iframe>` 标记嵌入播放器