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>
支持的参数
下面所有的参数都是可选的。
参数 | |
| 此参数用于指定是否在播放器加载时自动开始播放初始视频。支持的值为 |
| 此参数用于指定播放器将用于显示字幕的默认语言。请将参数值设置为两个字母组成的 ISO 639-1 语言代码。 如果您使用此参数且将 |
| 将参数值设置为 |
| 此参数用于指定在播放器的视频进度条中用来突出显示观看者已经看过的视频长度的颜色。有效的参数值包括 注意:将 |
| 此参数用于指明视频播放器控件是否会显示:
|
| 将参数值设置为
|
| 将参数值设置为 如需详细了解 iframe API 及其用法,请参阅 iframe API 文档(JavaScript Player API 已被弃用)。 |
| 此参数用于指定时间,以秒为单位,自视频开头开始计算,直到播放器应该停止播放视频时为止。此参数值是正整数。 请注意,时间是从视频开头而不是从 |
| 将此参数设置为 |
| 设置播放器的界面语言。此参数值是两个字母组成的 ISO 639-1 语言代码或完整表示的语言区域。例如,fr 和 fr-ca 都是有效值。系统或许也能正确处理 IETF 语言标记 (BCP 47) 之类的语言输入代码。 界面语言用于播放器中的工具提示,而且还会影响默认的字幕轨道。请注意,YouTube 可能会根据特定用户的个人语言偏好设置和提供的字幕轨道,为该用户选择其他字幕轨道语言。 |
| 将参数值设置为 |
|
注意:如果您指定 |
|
如果您指定 |
| 如果播放器是单视频播放器,则将此值设置为 支持的值为 注意:此参数在 AS3 播放器和 iframe 嵌入式播放器(可能会加载 AS3 或 HTML5 播放器)中得到的支持会受到限制。目前,仅在与
|
| 此参数可让您使用不显示 YouTube 徽标的 YouTube 播放器。将参数值设置为 |
| 此参数为 iframe API 提供额外的安全措施,而且仅支持 iframe 嵌入式播放器。如果您使用了 iframe API,这意味着您会将 |
| 此参数用于指定要播放的视频 ID 列表(以英文逗号分隔)。如果您指定一个值,则播放的第一个视频将是网址路径中指定的 |
| 此参数用于控制视频在 iOS 设备上的 HTML5 播放器中播放时,是以内嵌方式还是全屏模式播放。有效值如下:
|
| 注意:此参数在 2018 年 9 月 25 日当天或之后有调整。 在更改前,此参数用于指示初始视频播放结束时,播放器是否应显示相关视频。
在更改后,您将无法停用相关视频。相反,如果 |
| 注意:2018 年 9 月 25 日后,此参数已被弃用,并会被忽略。 支持的值包括: 如果将参数值设置为 如果播放器正在加载播放列表,而且您已明确将该参数值设置为 |
| 此参数可让播放器从视频中的指定位置开始播放视频,具体位置以距视频开头的秒数表示。此参数值是正整数。请注意,与 |
| 此参数用于标识在其中嵌入了播放器的网址。如果 YouTube 播放器嵌入到了微件中,而该微件随后嵌入到网页或应用中,则 YouTube 数据分析报告中会使用此值。在这种情况下, |