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)">/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="/embed/M7lc1UVf-VE?autoplay=1&origin="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 = "/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
网址中指定的。
/embed/VIDEO_ID
如果您使用了 YouTube Data API (v3),则可以从搜索结果、播放列表项资源、视频资源或其他资源中检索视频 ID,以编程方式构建这些网址。获取视频 ID 之后,请使用该值替换上述网址中的VIDEO_ID
文字以创建播放器网址。
加载播放列表
将listType
播放器参数设为playlist
。此外,将list
播放器参数设为您想加载的 YouTube 播放列表 ID。
<span style="color:var(--devsite-code-color)">/embed?listType=playlist&list=<strong>PLAYLIST_ID</strong></span>
请注意,播放列表 ID 需要以字母PL
作为前缀,如下例所示:
<span style="color:var(--devsite-code-color)">/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)">/embed?listType=user_uploads&list=<strong>USERNAME</strong></span>
加载指定查询的搜索结果
将listType
播放器参数设为search
,然后将list
播放器参数设置为您希望的查询字词,让播放器加载相应的搜索结果。
<span style="color:var(--devsite-code-color)">/embed?listType=search&list=<strong>QUERY</strong></span>
支持的参数
下面所有的参数都是可选的。