本文档提供了关于 YouTube JavaScript Player API 的参考信息。

目录

概述

JavaScript API 可让用户通过 JavaScript 控制 YouTube 嵌入的视频播放器。调用可以用来播放、暂停、查找视频的某个特定时间、设置音量、使播放器静音，还具有其他有用的功能。

要求

最终用户必须安装有 Flash Player 8 或更高版本才能正确查看所有内容。鉴于此要求，我们建议使用 SWFObject 来嵌入 SWF 并检测用户的 Flash Player 版本。

使用入门

请注意：若要测试这些调用中的任何一个，您必须在网络服务器上运行您的文件，因为 Flash Player 限制本地文件和互联网之间的调用。

若要启用 JavaScript API，您必须在希望控制的播放器 URL 中传递 URL 参数 enablejsapi=1。例如，您可能想要使用以下 URL 来嵌入 SWF。

http://www.youtube.com/v/VIDEO_ID&enablejsapi=1

这将在播放器中启用 JavaScript API 处理机，还会通知播放器在播放器载入并准备接收 JavaScript 调用时通过回调来警告包含 HTML 的页面。播放器准备就绪后，将调用 JavaScript 功能 onYouTubePlayerReady。

您可以随意传入 playerapiid 参数，该参数将在执行回调 onYouTubePlayerReady 时标识播放器。无论传入什么值，playerapiid 均将作为第一个参数传回 onYouTubePlayerReady。

http://www.youtube.com/v/VIDEO_ID&enablejsapi=1&playerapiid=ytplayer

请参阅以下实例以获取有关如何将 YouTube 播放器 SWF 嵌入到您页面的详细信息。

操作

若要调用播放器 API 方法，您必须先获取想要控制的播放器对象参考。如果使用 SWFObject 嵌入播放器 SWF，则此操作可通过在包含播放器 SWF 的 object 或 embed 标签上调用 getElementById() 来完成。

功能

player.playVideo():Void

播放目前插入/载入的视频。

player.pauseVideo():Void

暂停目前正播放的视频。

player.stopVideo():Void

停止当前视频。此操作还会关闭 NetStream 对象并取消视频的载入。调用 stopVideo() 后，除非重新载入播放器或载入新视频（仅限 Chromeless 播放器），否则无法恢复视频。调用 stopVideo() 时，播放器会首先广播结束事件 (0)，然后广播未开始的事件(-1)。

player.clearVideo():Void

清除视频显示。如果您想在调用 stopVideo() 后清除视频残留，这会很有用。

player.getVideoBytesLoaded():Number

传回当前视频载入的字节数。

player.getVideoBytesTotal():Number

传回当前已载入的视频/播放的视频的字节大小。

player.getVideoStartBytes():Number

传回视频文件从其中开始载入的字节数。实例情况：用户搜寻到尚未载入的内容，而播放器发出新的请求，要求播放尚未载入的视频片断。

player.mute():Void

使播放器静音。

player.unMute():Void

使播放器取消静音。

player.isMuted():Boolean

如果播放器已静音，会传回 true，否则会传回 false。

player.setVolume(volume):Void

设置音量。接受 0 到 100 之间的整数。

player.getVolume(volume):Void

传回播放器当前音量，介于 0 到 100 之间的整数。请注意，getVolume() 将传回音量（即使播放器已静音）。

player.seekTo(seconds, allowSeekAhead):Void

以秒为单位搜寻到视频的指定时间。如果 seconds 超过了当前载入的视频数据，allowSeekAhead 将确定播放器是否要对服务器做出新请求。请注意，seekTo() 将尝试搜寻与指定的 seconds 最相近的键架。这意味着有的时候播放头实际可能正好搜寻到请求时间之前或之后，通常不会超过 2 秒。

player.getPlayerState():Number

传回播放器的状态。可能的值为未开始 (-1)、已结束 (0)、正在播放 (1)、已暂停 (2)、正在缓冲 (3)、已插入视频 (5)。

player.getCurrentTime():Number

以秒为单位传回当前视频的目前时间。

player.getDuration():Number

以秒为单位传回当前播放的视频长度。请注意，getDuration() 将传回 0，直到已载入视频的元数据（通常正好发生在视频开始播放之后）。

player.addEventListener(event, listener):Void

为指定的事件添加监听功能。

player.getVideoUrl():String

传回当前载入/播放的视频的 YouTube.com URL。

player.getVideoEmbedCode():String

传回当前载入/播放的视频的嵌入代码。

事件

onStateChange

播放器状态更改时会闪光。可能的值为未开始 (-1)、已结束 (0)、正在播放 (1)、已暂停 (2)、正在缓冲 (3)、已插入视频 (5)。首次载入 SWF 后，它将广播一个未开始的 (-1) 事件。插入视频并准备播放时，它会广播视频插入事件 (5)。

onError

播放器出现错误时会闪光。目前只有一个错误代码，即 100“未找到视频”。该错误发生在视频已删除（出于任何原因）或视频已由用户标记为私人的或不可嵌入的情况下。

特殊事件

实例

使用 SWFObject 嵌入 YouTube 播放器

我们建议使用 SWFObject 来嵌入将使用 JavaScript API 进行访问的所有播放器。这可让您检测最终用户的 Flash Player 版本（JavaScript API 需要 Flash Player 8 或更高版本），并可让您在使用 Internet Explorer 查看播放器时无需选中“单击以启用此控件”框。 若要在 SWF 中启用 API，您必须传入参数 enablejsapi=1。

请参阅以下内容，以获取使用脚本嵌入已启用 JavaScript API 且具有 ytplayer 的 playerapiid 的 YouTube 播放器的实例。

  <script type="text/javascript" src="swfobject.js"></script>    
  <div id="ytapiplayer">
    You need Flash player 8+ and JavaScript enabled to view this video.
  </div>

  <script type="text/javascript">

    var params = { allowScriptAccess: "always" };
    var atts = { id: "myytplayer" };
    swfobject.embedSWF("http://www.youtube.com/v/VIDEO_ID&enablejsapi=1&playerapiid=ytplayer", 
                       "ytapiplayer", "425", "356", "8", null, null, params, atts);

  </script>

需要代码中的 allowScriptAccess 参数才能允许播放器 SWF 在包含 HTML 页面上调用功能，因为播放器的托管域与 HTML 页面的托管域不同。

在 myytplayer 的情况下，我们传入的唯一属性即为嵌入对象的 id。我们将使用此 ID 通过 getElementById() 获取播放器参考。

swfobject.embedSWF 将从 YouTube 载入播放器并将其嵌入在您的页面上。

swfobject.embedSWF(swfUrlStr, replaceElemIdStr, widthStr, heightStr, swfVersionStr, xiSwfUrlStr, flashvarsObj, parObj, attObj)

• swfUrlStr - 这是 SWF 的 URL。请注意我们已将 enablejsapi 和 playerapiid 参数附加到常规 YouTube SWF URL 以启用 JavaScript API 调用。
• replaceElemIdStr - 这是要使用嵌入内容替换的 HTML DIV ID。在上面的实例中，其为 ytapiplayer。
• widthStr - 播放器的宽度。
• heightStr - 播放器的高度。
• swfVersionStr - 用户查看内容所要求的最低版本。这种情况下，需要版本 8 或更高版本。如果用户不具有版本 8 或更高版本，他们将在 HTML DIV 中看到默认的文字线。
• xiSwfUrlStr -（可选）指定您的在线安装 SWF 的 URL。不用于此实例。
• flashVarsObj -（可选）在名称:值配对中指定您的 FlashVars。不用于此实例。
• parObj -（可选）嵌入对象的参数。此情况中，我们已设置 allowScriptAccess。
• AttObj -（可选）嵌入对象的属性。此情况中，我们已将 ID 设置为 myytplayer。

请参阅 SWFObject 文档获得更详细的解释。

获取播放器参考

播放器准备就绪后，将会调用 onYouTubePlayerReady。

若要获取播放器的参考，请使用 getElementById()。您拥有对象后就可以开始调用 API。

    function onYouTubePlayerReady(playerId) {
      ytplayer = document.getElementById("myytplayer");
    }

进行调用

现在您可以使用播放器参考调用功能。例如，如果您想在用户单击链接时播放视频，将会显示如下内容：

function play() {
  if (ytplayer) {
    ytplayer.playVideo();
  }
}

<a href="javascript:void(0);" onclick="play();">Play</a>

或者简单地，

 <a href="javascript:ytplayer.playVideo()">Play</a> 

订阅事件

通过将事件监听添加到播放器参考来订阅事件。例如，在播放器状态更改时收到通知，将事件监听添加到 onStateChange，并包含一个回调功能。

function onYouTubePlayerReady(playerId) {
  ytplayer = document.getElementById("myytplayer");
  ytplayer.addEventListener("onStateChange", "onytplayerStateChange");
}

function onytplayerStateChange(newState) {
   alert("Player's new state: " + newState);
}

此处是一个显示很多功能的简单示例。查看源代码以了解其原理。

返回页首