概览
本文档介绍如何在应用中嵌入 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 创建），则可以直接将播放器参数附加到网址末尾。网址格式如下：
https://www.youtube.com/embed/VIDEO_ID
以下 <iframe> 标记将会加载一个可用来播放 YouTube 视频 M7lc1UVf-VE 的 640x360 像素的播放器。由于网址中 autoplay 参数设置为 1，因此视频会在播放器加载完后自动播放。
使用 iframe Player API 嵌入播放器
<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>
请按照 iframe Player API 说明，在 iframe Player API 的 JavaScript 代码加载之后，在网页或应用中插入视频播放器。视频播放器构造函数中的第二个参数是指定播放器选项的对象。在此对象中，playerVars 属性会确定播放器参数。
以下 HTML 和 JavaScript 代码展示了一个简单示例，即将 YouTube 播放器插入 id 值为 ytplayer 的页面元素。系统会在 iframe Player API 代码加载完成后自动调用此处指定的 onYouTubePlayerAPIReady() 函数。此代码不会定义任何播放器参数，也不会定义其他事件处理脚本。
选择要播放的内容
<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>
您可以配置已嵌入的播放器，以加载视频、播放列表、用户上传的视频或针对特定查询的搜索结果。
以下列表介绍了这些选项：
加载视频
对于使用 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。
https://www.youtube.com/embed?listType=playlist&list=PLAYLIST_ID
请注意，播放列表 ID 需要以字母 PL 作为前缀，如下例所示：
https://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6
如果您使用的是 YouTube Data API (v3)，则可以从搜索结果、频道资源或活动资源中检索播放列表 ID，以编程方式构建这些网址。获得播放列表 ID 之后，请使用该值替换上述网址中的 PLAYLIST_ID 文字。
加载用户上传的视频
将 listType 播放器参数设为 user_uploads，然后将 list 播放器参数设为 YouTube 用户名，加载自己喜欢的对象所上传的视频。
https://www.youtube.com/embed?listType=user_uploads&list=USERNAME
加载指定查询的搜索结果
将 listType 播放器参数设为 search，然后将 list 播放器参数设置为您希望的查询字词，让播放器加载相应的搜索结果。
https://www.youtube.com/embed?listType=search&list=QUERY
支持的参数
下面所有的参数都是可选的。
参数
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。listlist 参数与 listType 参数搭配使用时可确定播放器中将要加载的内容。如果
listType 参数的值为 search，则 list 参数值会指定搜索查询。如果
listType 参数的值为 user_uploads，则 list 参数值会确定将要加载的已上传视频所在的 YouTube 频道。如果
listType 参数的值为 playlist，则 list 参数值会指定 YouTube 播放列表 ID。在参数值中，您需要使用字母 PL 为播放列表 ID 添加前缀，如下例所示。https://www.youtube.com/embed?
listType=playlist
&list=PLC77007E23FF423C6
注意：如果您指定
list 和 listType 参数的值，则 iframe 嵌入网址就无需指定视频 ID。listTypelistType 参数与 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 相同的值：https://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 日当天或之后有调整。
在更改前，此参数用于指示初始视频播放结束时，播放器是否应显示相关视频。
如果参数值设置为
1（默认值），则播放器会显示相关视频。如果参数值设置为
0，则播放器不会显示相关视频。在更改后，您将无法停用相关视频。相反，如果
rel 参数设置为 0，则相关视频将来自与刚播放的视频相同的频道。showinfo注意：2018 年 9 月 25 日后，此参数已被弃用，并会被忽略。
支持的值包括：
0 和 1。如果将参数值设置为
0，则在视频开始播放之前，播放器不会显示视频标题和上传者等信息。如果播放器正在加载播放列表，而且您已明确将该参数值设置为
1，那么播放列表加载时，播放器还将显示播放列表中视频的缩略图。start此参数可让播放器从视频中的指定位置开始播放视频，具体位置以距视频开头的秒数表示。此参数值是正整数。请注意，与
seekTo 函数类似，播放器会查找与指定时间最接近的关键帧。这就意味着，播放指针有时可能会停在请求时间之前几秒的位置，通常与请求时间相差不超过 2 秒。widget_referrer此参数用于标识在其中嵌入了播放器的网址。如果 YouTube 播放器嵌入到了微件中，而该微件随后嵌入到网页或应用中，则 YouTube 数据分析报告中会使用此值。在这种情况下，
origin 参数用于标识微件提供商的网域，但 YouTube 数据分析不会将微件提供商标识为实际的流量来源。相反，YouTube 数据分析会改用 widget_referrer 参数值以标识与流量来源关联的网域。修订历史记录
August 23, 2018
Note: This is a deprecation announcement for the showinfo parameter. In addition, the behavior for the rel parameter is changing. Titles, channel information, and related videos are an important part of YouTube’s core user experience, and these changes help to make the YouTube viewing experience consistent across different platforms.
The behavior for the
rel parameter is changing on or after September 25, 2018. The effect of the change is that you will not be able to disable related videos. However, you will have the option of specifying that the related videos shown in the player should be from the same channel as the video that was just played.To be more specific:
Prior to the change, if the parameter's value is set to
0, then the player does not show related videos.After the change, if the
rel parameter is set to 0, the player will show related videos that are from the same channel as the video that was just played.The
showinfo parameter, which indicates whether the player should display information like the video title and uploader before the video starts playing, is also being deprecated. Following the change, the channel avatar and video title will always display before playback begins, when playback is paused, and when playback ends. The avatar being displayed is new behavior that will be consistent across all embedded players.These changes will become effective on or after September 25, 2018. After that time, the showinfo parameter will be ignored. The behavior following the changes is consistent with the current default behavior for embedded players with the exception of the channel avatar changes mentioned above.
August 16, 2018
The cc_lang_pref parameter can be used to specify the default language that the player will use to display captions. This parameter can be used in conjunction with the cc_load_policy parameter to automatically show captions in the specified language during playback.
September 15, 2017
The controls parameter's definition has been updated to remove references to the deprecated Flash (AS3) player. The value 2 has been deprecated as it was originally designed to provide a performance improvement for embeds that loaded a Flash player.
June 12, 2017
The new widget_referrer parameter helps to enable more accurate YouTube Analytics reporting when the YouTube player is embedded in a widget, and that widget is then embedded in a web page or application.
November 1, 2016
This document has been updated to remove references to the deprecated Flash (AS3) player as well as to parameters only supported by that player. The YouTube Flash player was deprecated in January 2015.
October 20, 2016
This update contains the following changes:
The disablekb parameter definition has been corrected to note that the default value is 0, which means that keyboard controls are enabled. A value of 1 indicates that keyboard controls should be disabled.
The list of keyboard controls that the player supports has also been updated to include the following:
[f]: Toggle full-screen display
[j]: Jump back 10 seconds in the current video
[k]: Play / Pause
[l]: Jump ahead 10 seconds in the current video
[m]: Mute or unmute the video
[0-9]: Jump to a point in the video.
0 jumps to the beginning of the video, 1 jumps to the time 10% into the video, 2 jumps to the point 20% into the video, and so forth.In addition, the effect of pressing the [arrow left] or [arrow right] keys has changed. These keys now jump 5 seconds back (arrow left) or ahead (arrow right) in the current video.
August 11, 2016
This update contains the following changes:
The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog, provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.
The full set of new documents is described in the revision history for the Updated Terms. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.
December 18, 2015
European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy. We have added a notice of this requirement in our YouTube API Terms of Service.
August 19, 2015
The autohide parameter has been deprecated for the HTML5 player. In HTML5 players, the video progress bar and player controls display or hide automatically. That behavior corresponds to an autohide setting of 1.
The theme parameter has been deprecated for the HTML5 player. HTML5 players now always use the dark theme.
March 9, 2015
The document has been updated to reflect the fact that YouTube <object> embeds, the YouTube Flash Player API and the YouTube JavaScript Player API have all been deprecated as of January 27, 2015. A deprecation warning appears in several sections of this document to help point readers to the IFrame Player API as an alternative.
The definition of the autohide parameter has been updated to clarify the meaning of the parameter's values. The default behavior (autohide=2) is that if the player has a 16:9 or 4:3 aspect ratio, the player's video progress bar and player controls display or hide automatically. Otherwise, those controls are visible throughout the video.
The definition of the hl parameter has been updated to note that the parameter value could be an ISO 639-1 two-letter language code or a fully specified locale. For example, fr and fr-ca are both valid parameter values.
The definition of the enablejsapi parameter has been reworded to clarify that the parameter enables a player to be controlled via API calls. The API could be either the IFrame Player API or the JavaScript Player API.
October 14, 2014
The HTML5 player now supports the cc_load_policy, disablekb, end, fs, list, and listType parameters. The parameter descriptions have been updated accordingly.
July 18, 2014
The new hl parameter can be used to set the player's interface language. The interface language is used for tooltips in the player and also affects the default caption track. The selected caption track may also depend on the availability of caption tracks and user's individual language preferences.
The parameter's value is an ISO 639-1 two-letter language code, though other language input codes, such as IETF language tags (BCP 47) may also be handled properly.
The definition of the playsinline parameter, which only affects HTML5 players on iOS, has been modified slightly. The definition now notes that setting the parameter value to 1 causes inline playback only for UIWebViews created with the allowsInlineMediaPlayback property set to TRUE.
January 28, 2014
The playsinline parameter controls whether videos play inline or fullscreen in an HTML5 player on iOS. Setting the value to 1 causes inline playback.
The Selecting content to play section has been updated to explain how to find YouTube video IDs and playlist IDs using the YouTube Data API (v3) rather than the older API version.
The controls parameter's definition has been updated to reflect the fact that the parameter value only affects the time that the Flash player actually loads in IFrame embeds. In addition, for IFrame embeds, the parameter value also determines when the controls display in the player. If you set the parameter's value to 2, then the controls display and the Flash player loads after the user initiates the video playback.
May 10, 2013
This update contains the following changes:
YouTube no longer identifies experimental API features and services. Instead, we now provide a list of YouTube APIs that are subject to the deprecation policy.
July 20, 2012
This update contains the following changes:
The definition of the controls parameter has been updated to reflect support for a parameter value of 2 and to explain that, for AS3 players, the parameter value determines the time when the Flash player actually loads. If the controls parameter is set to 0 or 1, the Flash player loads immediately. If the parameter value is 2, the Flash player does not load until the video playback is initiated.
June 5, 2012
This update contains the following changes:
The HTML5 player now supports the color, modestbranding, and rel parameters, and the definitions for these parameters have been updated accordingly.
The definition of the showinfo parameter has been updated to explain how that if the player is loading a playlist, and you explicitly set the parameter value to 1, then, upon loading, the player will also display thumbnail images for the videos in the playlist. Note that this functionality is only supported for the AS3 player since that is the only player that can load a playlist.
May 4, 2012
This update contains the following changes:
The showinfo parameter's definition has been updated to reflect the fact that the HTML5 player supports this parameter.
May 3, 2012
This update contains the following changes:
The new end parameter specifies the time, measured in seconds from the start of the video, when the player should stop playing a video. Note that the time when playback is stopped is measured from the beginning of the video and not from the value of either the start player parameter or the startSeconds parameter, which is used in YouTube Player API functions for loading or queueing a video.
March 29, 2012
This update contains the following changes:
The new Embedding a YouTube player section explains different ways to embed a YouTube player in your application. This section covers manual IFrame embeds, IFrame embeds that use the IFrame Player API, and AS3 and AS2 object embeds. This section incorporates information from the old Example usage section, which has been removed.
The new Selecting content to play section explains how to configure the player to load a video, a playlist, search results for a specified query, or uploaded videos for a specified user.
The new list and listType parameters let you specify the content that the player should load. You can specify a playlist, a search query, or a particular user's uploaded videos.
The definitions of the fs and rel parameters have been updated to more clearly explain the default parameter values for the AS3 player.
The border, color1, egm, hd, and showsearch parameters, which are all only supported for the deprecated AS2 Player API, have been moved to a new section named deprecated parameters only used in the AS2 Player API.
The document no longer provides a way to filter the parameter list to only display parameters supported in either the AS3, AS2, or HTML5 player. Instead, each parameter definition has been updated to identify the players that support that parameter.
August 11, 2011
This update contains the following changes:
The new theme and color parameters let you customize the appearance of the embedded player's player controls. See the YouTube API blog for more information.
June 8, 2011
This update contains the following changes:
The new modestbranding parameter lets you use a YouTube player that does not show a YouTube logo. As of this release, the parameter was only supported for the AS3 embedded player and for IFrame embeds that loaded the AS3 player. As of June 5, 2012, the HTML5 player also supported this parameter.
February 14, 2011
This update contains the following changes:
The documentation has been updated to note that the AS2 Player API has been deprecated. The deprecation of the AS2 Player API was actually announced on October 14, 2009.
February 3, 2011
This update contains the following changes:
The documentation has been updated to identify parameters supported in the HTML5 (IFrame) embedded player.
The document now displays all of the parameters supported in any of YouTube's embedded players (HTML5, AS3, AS2).
The following parameters are supported in the AS2 player but have been deprecated for the newer AS3 and HTML5 players: border, color1, color2, egm, hd, and showsearch.
In addition, the loop parameter has limited support in the AS3 player and in IFrame embeds, which could load either an AS3 or HTML player. Currently, the loop parameter only works in the AS3 player when used in conjunction with the playlist parameter. To loop a single video, set the loop parameter to 1 and set the playlist parameter value to the same video ID already specified in the Player API URL:
https://www.youtube.com/v/VIDEO_ID?version=3&loop=1&playlist=VIDEO_ID
Similarly, the controls and playlist parameters are supported in the AS3 and HTML5 players but are not and will not be supported in the AS2 player.
As noted above, IFrame embeds can load either an AS3 or HTML5 player. Though some parameters are not supported in both players, an IFrame embed that loads the AS3 player will support all parameters that work with that player and ignore all other parameters. Similarly, an IFrame embed that loads the HTML5 player will support all parameters that work with that player while ignoring all other parameters.
The parameter list has been updated to include the autohide parameter, which indicates whether the player's video controls will automatically hide after a video begins playing.
The parameter list has been updated to include the controls parameter, which indicates whether the player's video controls will display at all. (Player controls do display by default.)
The parameter list has been updated to include the playlist parameter, which specifies a comma-separated list of video IDs to play.
The definition of the fs has been updated to note that the fullscreen option will not work if you load the YouTube player into another SWF.
The example at the end of the document has been updated to use the embedded AS3 player instead of the embedded AS2 player. The parameters used in the example have also been updated to only include parameters that the AS3 player supports.
In addition, the instructions for constructing the URLs that contain player parameters have been updated to reflect the URL formats used by the AS3 and AS2 embedded and chromeless players as well as by the HTML5 player.
... <看更多>
iframe高度依內容自動調整 在 [HTML] 設定iframe內鑲YouTube影片的寬度為100%，高度自動 ... 的推薦與評價
必須透過一個容器來自動調整寬和高度：. 在上層新增1個class為「container」的div；刪除iframe的width、height的設定，並新增「video」的class。 ... <看更多>