YouTube Player 常用参数

概览

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

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

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

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

支持的参数

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

参数
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 添加前缀，如下例所示。 https://www.youtube.com/embed?     listType=playlist     &list=PLC77007E23FF423C6 注意：如果您指定 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 相同的值： 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 参数值以标识与流量来源关联的网域。