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

[l] 键：在当前视频中向前跳10 秒; [m] 键：将视频静音或取消静音; [0-9] 键：跳转到视频中的某一位置。

YouTube IFramePlayerAPI English BahasaIndonesia Deutsch Español Français Italiano Polski Português–Brasil Türkçe Русский 中文–简体 日本語 한국어 登录 参考 示例 支持 YouTube IFramePlayerAPI 参考 示例 支持 IFrameAPI 播放器参数 MobileAPIs AndroidAPI iOS助手库 首页 产品 YouTube IFramePlayerAPI YouTube嵌入式播放器及播放器参数 概览 本文档介绍如何在应用中嵌入YouTube播放器，并定义了YouTube嵌入式播放器可以使用的参数。

通过将参数附加到iframe网址末尾，您可以自定义应用中的播放体验。

例如，您可以使用autoplay参数自动播放多个视频，也可以使用loop参数重复播放一个视频。

您还可以使用enablejsapi参数，允许通过iframePlayerAPI控制播放器。

目前，本页面定义了任意YouTube嵌入式播放器支持的全部参数。

每个参数定义均会确定支持相应参数的播放器。

注意：嵌入式播放器必须具有一个尺寸至少为200x200像素的视口。

如果播放器显示控件，那么它必须足够大，可以在无需将视口缩小到最小尺寸以下的情况下完整显示控件。

我们建议16:9播放器的宽至少为480像素、高至少为270像素。

嵌入YouTube播放器 您可以使用以下任意一种方法在应用中嵌入YouTube播放器并指定播放器参数。

请注意，以下说明将介绍如何嵌入会加载单个视频的播放器。

接下来的部分将说明如何配置您的播放器，以便加载其他类型的内容（例如播放列表和搜索结果）。

使用 使用iframePlayerAPI嵌入播放器 请按照iframePlayerAPI说明，在iframePlayerAPI的JavaScript代码加载之后，在网页或应用中插入视频播放器。

视频播放器构造函数中的第二个参数是指定播放器选项的对象。

在此对象中，playerVars属性会确定播放器参数。

以下HTML和JavaScript代码展示了一个简单示例，即将YouTube播放器插入id值为ytplayer的页面元素。

系统会在iframePlayerAPI代码加载完成后自动调用此处指定的onYouTubePlayerAPIReady()函数。

此代码不会定义任何播放器参数，也不会定义其他事件处理脚本。

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

以下列表介绍了这些选项： 加载视频 对于使用iframe嵌入的播放器，您要加载的视频的YouTube视频ID是在iframe的src网址中指定的。

https://www.youtube.com/embed/VIDEO_ID 如果您使用了YouTubeDataAPI(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 如果您使用的是YouTubeDataAPI(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 此参数用于指定播放器将用于显示字幕的默认语言。

请将参数值设置为两个字母组成的ISO639-1语言代码。

如果您使用此参数且将cc_load_policy参数设为1，则在播放器加载时，播放器将会以指定的语言显示字幕。

如果您还未设置cc_load_policy参数，则默认情况下字幕将不会显示，但如果用户选择打开字幕，则字幕将会以指定的语言显示。

cc_load_policy 将参数值设置为1会使系统在默认情况下显示字幕，即使在用户此前关闭了字幕的情况下也是如此。

默认行为基于用户偏好设置。

color 此参数用于指定在播放器的视频进度条中用来突出显示观看者已经看过的视频长度的颜色。

有效的参数值包括red和white，而且在默认情况下，播放器将在视频进度条中使用红色。

如需详细了解颜色选项，请参阅YouTubeAPI博客。

注意：将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或JavaScriptPlayerAPI调用来控制播放器。

默认值为0，表示无法使用这些API控制播放器。

如需详细了解iframeAPI及其用法，请参阅iframeAPI文档（JavaScriptPlayerAPI已被弃用）。

end 此参数用于指定时间，以秒为单位，自视频开头开始计算，直到播放器应该停止播放视频时为止。

此参数值是正整数。

请注意，时间是从视频开头而不是从start播放器参数值或startSeconds参数值开始计算的；此时间在YouTubePlayerAPI函数中用于加载视频或将视频加入队列。

fs 将此参数设置为0可以阻止全屏按钮显示在播放器中。

默认值为1，该值会使全屏按钮显示。

hl 设置播放器的界面语言。

此参数值是两个字母组成的ISO639-1语言代码或完整表示的语言区域。

例如，fr和fr-ca都是有效值。

系统或许也能正确处理IETF语言标记(BCP47)之类的语言输入代码。

界面语言用于播放器中的工具提示，而且还会影响默认的字幕轨道。

请注意，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参数值设置为与PlayerAPI网址中已指定的视频ID相同的值： https://www.youtube.com/v/VIDEO_ID?    version=3    &loop=1    &playlist=VIDEO_ID modestbranding 此参数可让您使用不显示YouTube徽标的YouTube播放器。

将参数值设置为1可以阻止YouTube徽标显示在控制栏中。

请注意，当用户的鼠标指针悬停在播放器上方时，一个小YouTube文字标签仍将显示在暂停的视频的右上角。

origin 此参数为iframeAPI提供额外的安全措施，而且仅支持iframe嵌入式播放器。

如果您使用了iframeAPI，这意味着您会将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参数值以标识与流量来源关联的网域。

修订历史记录 August23,2018 Note:Thisisadeprecationannouncementfortheshowinfoparameter.Inaddition,thebehaviorfortherelparameterischanging.Titles,channelinformation,andrelatedvideosareanimportantpartofYouTube’scoreuserexperience,andthesechangeshelptomaketheYouTubeviewingexperienceconsistentacrossdifferentplatforms. ThebehaviorfortherelparameterischangingonorafterSeptember25,2018.Theeffectofthechangeisthatyouwillnotbeabletodisablerelatedvideos.However,youwillhavetheoptionofspecifyingthattherelatedvideosshownintheplayershouldbefromthesamechannelasthevideothatwasjustplayed. Tobemorespecific: Priortothechange,iftheparameter'svalueissetto0,thentheplayerdoesnotshowrelatedvideos. Afterthechange,iftherelparameterissetto0,theplayerwillshowrelatedvideosthatarefromthesamechannelasthevideothatwasjustplayed. Theshowinfoparameter,whichindicateswhethertheplayershoulddisplayinformationlikethevideotitleanduploaderbeforethevideostartsplaying,isalsobeingdeprecated.Followingthechange,thechannelavatarandvideotitlewillalwaysdisplaybeforeplaybackbegins,whenplaybackispaused,andwhenplaybackends.Theavatarbeingdisplayedisnewbehaviorthatwillbeconsistentacrossallembeddedplayers. ThesechangeswillbecomeeffectiveonorafterSeptember25,2018.Afterthattime,theshowinfoparameterwillbeignored.Thebehaviorfollowingthechangesisconsistentwiththecurrentdefaultbehaviorforembeddedplayerswiththeexceptionofthechannelavatarchangesmentionedabove. August16,2018 Thecc_lang_prefparametercanbeusedtospecifythedefaultlanguagethattheplayerwillusetodisplaycaptions.Thisparametercanbeusedinconjunctionwiththecc_load_policyparametertoautomaticallyshowcaptionsinthespecifiedlanguageduringplayback. September15,2017 Thecontrolsparameter'sdefinitionhasbeenupdatedtoremovereferencestothedeprecatedFlash(AS3)player.Thevalue2hasbeendeprecatedasitwasoriginallydesignedtoprovideaperformanceimprovementforembedsthatloadedaFlashplayer. June12,2017 Thenewwidget_referrerparameterhelpstoenablemoreaccurateYouTubeAnalyticsreportingwhentheYouTubeplayerisembeddedinawidget,andthatwidgetisthenembeddedinawebpageorapplication. November1,2016 ThisdocumenthasbeenupdatedtoremovereferencestothedeprecatedFlash(AS3)playeraswellastoparametersonlysupportedbythatplayer.TheYouTubeFlashplayerwasdeprecatedinJanuary2015. October20,2016 Thisupdatecontainsthefollowingchanges: Thedisablekbparameterdefinitionhasbeencorrectedtonotethatthedefaultvalueis0,whichmeansthatkeyboardcontrolsareenabled.Avalueof1indicatesthatkeyboardcontrolsshouldbedisabled. Thelistofkeyboardcontrolsthattheplayersupportshasalsobeenupdatedtoincludethefollowing: [f]:Togglefull-screendisplay [j]:Jumpback10secondsinthecurrentvideo [k]:Play/Pause [l]:Jumpahead10secondsinthecurrentvideo [m]:Muteorunmutethevideo [0-9]:Jumptoapointinthevideo.0jumpstothebeginningofthevideo,1jumpstothetime10%intothevideo,2jumpstothepoint20%intothevideo,andsoforth. Inaddition,theeffectofpressingthe[arrowleft]or[arrowright]keyshaschanged.Thesekeysnowjump5secondsback(arrowleft)orahead(arrowright)inthecurrentvideo. August11,2016 Thisupdatecontainsthefollowingchanges: ThenewlypublishedYouTubeAPIServicesTermsofService("theUpdatedTerms"),discussedindetailontheYouTubeEngineeringandDevelopersBlog,providesarichsetofupdatestothecurrentTermsofService.InadditiontotheUpdatedTerms,whichwillgointoeffectasofFebruary10,2017,thisupdateincludesseveralsupportingdocumentstohelpexplainthepoliciesthatdevelopersmustfollow. ThefullsetofnewdocumentsisdescribedintherevisionhistoryfortheUpdatedTerms.Inaddition,futurechangestotheUpdatedTermsortothosesupportingdocumentswillalsobeexplainedinthatrevisionhistory.YoucansubscribetoanRSSfeedlistingchangesinthatrevisionhistoryfromalinkinthatdocument. December18,2015 EuropeanUnion(EU)lawsrequirethatcertaindisclosuresmustbegiventoandconsentsobtainedfromendusersintheEU.Therefore,forendusersintheEuropeanUnion,youmustcomplywiththeEUUserConsentPolicy.WehaveaddedanoticeofthisrequirementinourYouTubeAPITermsofService. August19,2015 TheautohideparameterhasbeendeprecatedfortheHTML5player.InHTML5players,thevideoprogressbarandplayercontrolsdisplayorhideautomatically.Thatbehaviorcorrespondstoanautohidesettingof1. ThethemeparameterhasbeendeprecatedfortheHTML5player.HTML5playersnowalwaysusethedarktheme. March9,2015 ThedocumenthasbeenupdatedtoreflectthefactthatYouTube