TShopping

 找回密碼
 註冊
搜索
查看: 5097|回復: 2

[教學] YouTube JavaScript 播放器 API 參考

[複製鏈接]
發表於 2012-6-17 12:02:51 | 顯示全部樓層 |閱讀模式
 
Push to Facebook Push to Plurk Push to Twitter 
概述JavaScript API 可讓用戶通過 JavaScript 控制 YouTube 嵌入式視頻播放器。可以進行調用以播放視頻、暫停視頻、定位到視頻中的特定時間、設置音量、使播放器靜音以及提供其他實用功能。
要求最終用戶需要安裝 Flash Player 8 或更高版本,才能正常觀看所有內容。鑒於此要求,我們建議您使用 SWFObject 嵌入 SWF 並檢測用戶的 Flash Player 的版本。
此外,所有包含 YouTube 播放器的 HTML 頁面都必須實現 JavaScript 函數 onYouTubePlayerReady。當播放器完全載入且 API 準備好接收調用後,API 便會調用此函數。有關詳細信息,請參見事件處理程序部分。
使用入門
注意:要測試其中任何一個調用,您都必須先在網絡服務器上運行自己的文件,因為 Flash Player 會限制本地文件與互聯網之間的調用。
要啟用 JavaScript API,您必須將網址參數 enablejsapi=1 傳遞到您想要控制的播放器的網址中。例如,您可能想要使用以下網址嵌入 SWF。
http://www.youtube.com/v/VIDEO_ID?enablejsapi=1該操作會在播放器中啟用 JavaScript API 處理程序,並且會指示播放器通過回調向包含 HTML 的網頁發出通知:播放器已載入並準備好接收 JavaScript 調用。播放器準備就緒後,系統會調用 JavaScript 函數 onYouTubePlayerReady
您也可以選擇傳入 playerapiid 參數,以便在系統調用 onYouTubePlayerReady 回調時標識播放器。作為 playerapiid 傳入的值會作為第一個參數傳回 onYouTubePlayerReady
http://www.youtube.com/v/VIDEO_ID?enablejsapi=1&playerapiid=ytplayer或者,如果使用 JavaScript 構建自己的自定義控件,請在自己的網頁中載入 Chromeless Player:
http://www.youtube.com/apiplayer?enablejsapi=1您可以通過在以上網址中添加 &version=3 參數請求 AS3 Chromeless Player:
http://www.youtube.com/apiplayer?enablejsapi=1&version=3載入 Chromeless Player SWF 後,您可以使用 cueVideoById()loadVideoById()cueVideoByUrl()loadVideoByUrl() 載入特定 YouTube 視頻。
有關如何在網頁中嵌入 YouTube 播放器 SWF 的更多詳細信息,請參見下文中的示例
操作要調用播放器 API 方法,您必須先引用希望控制的播放器對象。如果使用 SWFObject 嵌入播放器 SWF,則可以對包含播放器 SWF 的 object 或 embed 標記調用 getElementById() 完成此操作。
函數隊列函數
player.cueVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):Void載入指定視頻的縮略圖,並準備用於播放視頻的播放器。只有在調用 playVideo()seekTo() 之後,播放器才會請求 FLV。

  • 必需參數 videoId 用於指定待播視頻的 YouTube 視頻 ID。在 YouTube 數據 API 視頻供稿中,<yt:videoId> 標記用於指定 ID。
  • 可選參數 startSeconds 接受浮點值/整數值,用於指定應在調用 playVideo() 後視頻開始播放的起始時間。如果您在指定 startSeconds 值後調用 seekTo(),則播放器會從 seekTo() 調用中指定的時間開始播放。在視頻插入完畢並可供播放時,播放器會傳遞已插入視頻事件 (5)。
  • 可選參數 suggestedQuality 用於指定視頻的建議播放質量。有關播放質量的更多信息,請參見 setPlaybackQuality 函數的定義。
player.loadVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):Void載入並播放指定視頻。

  • 必需參數 videoId 用於指定待播視頻的 YouTube 視頻 ID。在 YouTube 數據 API 視頻供稿中,<yt:videoId> 標記用於指定 ID。
  • 可選參數 startSeconds 接受浮點值/整數值。如果指定該可選參數,則視頻會從距離指定時間最近的關鍵幀開始播放。
  • 可選參數 suggestedQuality 用於指定視頻的建議播放質量。有關播放質量的更多信息,請參見 setPlaybackQuality 函數的定義。
player.cueVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void載入指定視頻的縮略圖,並準備用於播放視頻的播放器。只有在調用 playVideo()seekTo() 之後,播放器才會請求 FLV。

  • mediaContentUrl 必須是完全符合要求的 YouTube 播放器網址,格式為 http://www.youtube.com/v/VIDEO_ID。在 YouTube 數據 API 視頻供稿中,如果 <media:content> 標記的 format 屬性的值為 5,則表明該標記的 url 屬性包含完全符合要求的播放器網址。
  • startSeconds 接受浮點值/整數值,並用於指定在調用 playVideo() 後視頻開始播放的起始時間。如果您在指定 startSeconds 後調用 seekTo(),播放器會從 seekTo() 調用中指定的時間開始播放。在視頻插入完畢並可供播放時,播放器會傳遞已插入視頻事件 (5)。
player.loadVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void此函數用於載入並播放指定視頻,但尚未在 ActionScript 3.0 Player API 中實施。

  • mediaContentUrl 必須是完全符合要求的 YouTube 播放器網址,格式為 http://www.youtube.com/v/VIDEO_ID。在 YouTube 數據 API 視頻供稿中,如果 <media:content> 標記的 format 屬性的值為 5,則表明該標記的 url 屬性包含完全符合要求的播放器網址。
  • startSeconds 接受浮點值/整數值,並用於指定視頻開始播放的起始時間。如果指定了 startSeconds(數值可以是浮點值),則視頻會從距離指定時間最近的關鍵幀開始播放。
載入並播放指定視頻。

  • mediaContentUrl 必須是完全符合要求的 YouTube 播放器網址,格式為 http://www.youtube.com/v/VIDEO_ID。在 YouTube 數據 API 視頻供稿中,如果 <media:content> 標記的 format 屬性的值為 5,則表明該標記的 url 屬性包含完全符合要求的播放器網址。
  • startSeconds 接受浮點值/整數值,並用於指定視頻開始播放的起始時間。如果指定了 startSeconds(數值可以是浮點值),則視頻會從距離指定時間最近的關鍵幀開始播放。

播放控制和播放器設置
播放視頻 player.playVideo():Void播放當前已插入/已載入的視頻。player.pauseVideo():Void暫停當前正在播放的視頻。player.stopVideo():Void停止播放當前視頻。此函數還可取消視頻的載入。player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void定位到視頻的指定時間(以秒為單位)。seekTo() 函數會向前查找距離 seconds 所指定時間最近的關鍵幀。也就是說,播放開始位置的定位有時會稍早於請求時間,但通常與請求時間的間隔不超過 2 秒。

allowSeekAhead 參數用於確定在 seconds 超出了當前已載入視頻數據對應的播放時間時,播放器是否向服務器發起新的請求。player.clearVideo():Void清除視頻顯示。如果您想要在調用 stopVideo() 後清除視頻殘留,那麼可使用此函數。請注意,ActionScript 3.0 Player API 中不推薦使用此函數。
更改播放器的音量 player.mute():Void使播放器靜音。player.unMute():Void取消播放器靜音。player.isMuted():Boolean如果播放器處於靜音狀態,則返回 Ture;否則返回 False。player.setVolume(volume:Number):Void設置音量。接受 0 到 100 之間的整數。player.getVolume():Number返回播放器的當前音量,以 0 到 100 之間的整數值表示。請注意,即使播放器處於靜音狀態,getVolume() 也會返回音量值。
設置播放器的大小 player.setSize(width:Number, height:Number):Void設置播放器的大小(以像素為單位)。您無需在 JavaScript 中使用此方法,原因是,如果嵌入代碼中包含的元素已修改自身的高度和寬度屬性,則播放器的大小會自動進行設置。

播放狀態
player.getVideoBytesLoaded():Number返回當前視頻已載入的字節數。player.getVideoBytesTotal():Number返回當前已載入/正在播放的視頻的大小(以字節為單位)。player.getVideoStartBytes():Number返回視頻文件的載入點前已有的字節數。示例情況:用戶向前定位到一個尚未載入的時間點,於是播放器發起播放視頻中尚未載入片段的新請求。player.getPlayerState():Number返回播放器的狀態。可用的值為未開始 (-1)、已結束 (0)、正在播放 (1)、已暫停 (2)、正在緩衝 (3)、已插入視頻 (5)。player.getCurrentTime():Number返回視頻已播放的時間長度(以秒為單位)。
播放質量
player.getPlaybackQuality():String此函數用於檢索當前視頻的實際質量。如果當前沒有視頻,則該函數會返回 undefined。可用的值為 hd720、large、medium 和 small。player.setPlaybackQuality(suggestedQuality:String):Void此函數用於設置當前視頻的建議質量。該函數可在視頻的當前位置使用另一種視頻質量重新載入該視頻。如果更改了播放質量,則此更改只會影響當前正在播放的視頻。

調用此函數並不意味著播放質量會發生實際更改。如果更改了播放質量,則此更改只會影響當前正在播放的視頻。此時,系統會觸發 onPlaybackQualityChange 事件。您的代碼應該響應該事件,而不是調用 setPlaybackQuality 函數。

suggestedQuality 參數的值可以為 small、medium、large、hd720 或 default。如果將該參數值設置為 default,YouTube 就會選擇最合適的播放質量,具體質量會視不同的用戶、視頻、系統和其他播放條件而有所不同。

如果您建議使用特定質量播放某個視頻,則只有該視頻會採用建議的質量。您選擇的播放質量應該適合視頻播放器的大小。例如,如果網頁上顯示的是 640x360 像素的視頻播放器,則 medium 級別的視頻質量的實際顯示效果要優於 large 級別的視頻質量。下面的列表針對不同的播放器大小給出了不同的播放質量級別建議:


  • 質量級別 small:播放器的分辨率低於 640x360 像素。
  • medium 質量級:播放器的最低分辨率為 640x360 像素。
  • large 質量級:播放器的最低分辨率為 854x480 像素。
  • hd720 質量級:播放器的最低分辨率為 1280x720 像素。
  • default 質量級:YouTube 選擇合適的播放質量。此設置會將質量級有效地恢復成默認狀態,並會撤消以前通過使用 cueVideoByIdloadVideoById 或 setPlaybackQuality 函數設置播放質量的全部操作。

如果您在調用 setPlaybackQuality 函數時使用了不適合視頻的質量級別 suggestedQuality,則系統會將質量設置為適合視頻的下一級別。例如,如果您請求的質量級別為 large 而該級別並不適用,則系統會將播放質量設置為 medium(如果該質量級別適用)。

另外,將 suggestedQuality 設置為一個無法識別的質量級就相當於將 suggestedQuality 設置為 default。player.getAvailableQualityLevels():Array此函數可返回適合當前視頻的一系列質量格式。您可以使用此函數確定是否存在比用戶所觀看質量更高的視頻質量,這樣播放器就可以顯示按鈕或其他元素供用戶調整質量。

該函數返回的是按質量順序由高到低排列的字符串數組。可用的數組元素值包括 hd720、large、medium 和 small。如果當前沒有任何視頻,則此函數會返回空數組。

您的客戶端不應自動選擇使用質量最高(或最低)的視頻,也不應自動選擇使用未知的格式名稱。YouTube 會擴充質量級別列表,其中包含的某些格式可能不適用於您的播放器環境。同樣,YouTube 也會刪除不利於用戶體驗的質量選項。您應確保自己的客戶端只會選擇已知的有效格式,這樣在引入新的質量級或刪除不適用於您播放器環境的質量級時,就可以確保您的客戶端效果不會受到這些因素的影響。
檢索視頻信息
player.getDuration():Number返回當前正在播放的視頻的時長(以秒為單位)。請注意,如果視頻的元數據尚未載入,則 getDuration() 會返回 0。通常,視頻一開始播放就會載入元數據。player.getVideoUrl():String返回當前已載入/正在播放的視頻的 YouTube.com 網址。player.getVideoEmbedCode():String返回當前已載入/正在播放的視頻的嵌入代碼。
添加事件偵聽器 player.addEventListener(event:String, listener:String):Void為指定的 event 添加事件偵聽器函數。下文的 Events 部分介紹了播放器可能觸發的不同事件。偵聽器是一個字符串,用於指定觸發指定事件時執行的函數。
事件onStateChange只要播放器的狀態發生更改,系統就會觸發此事件。可用的值為未開始 (-1)、已結束 (0)、正在播放 (1)、已暫停 (2)、正在緩衝 (3)、已插入視頻 (5)。在初次載入 SWF 時,該事件會傳遞未開始 (-1) 事件。在視頻插入完畢並可供播放時,該事件會傳遞已插入視頻 (5) 事件。onPlaybackQualityChange只要視頻的播放質量發生更改,系統就會觸發此事件。例如,如果您調用 setPlaybackQuality(suggestedQuality) 函數,則在播放質量發生實際更改時,系統就會觸發此事件。您的代碼應響應該事件,並且不應假定播放質量在調用 setPlaybackQuality(suggestedQuality) 函數時會自動發生更改。同樣,您的代碼也不應假定,只有對 setPlaybackQuality 或可讓您設置建議播放質量的任何其他函數進行顯式調用時,播放品質才會發生更改。

事件廣播的值代表新的播放質量。可用的值包括「small」(小)、「medium」(中)、「large」(大) 和「hd720」(高清,分辨率為 720)。onError播放器中出現錯誤時,系統就會觸發此事件。可用的錯誤代碼為 100、101 和 150。如果沒有找到請求的視頻,則系統會傳遞錯誤代碼 100。如果視頻因某種原因遭到刪除或標記為私有視頻,則會出現這種情況。如果請求的視頻無法在嵌入的播放器中播放,則系統會傳遞錯誤代碼 101。錯誤代碼 150 與 101 的作用相同;它與 101 的不同之處只在於名稱。事件處理程序顯示 Chromeless Player 的 HTML 網頁必須實現回調函數 onYouTubePlayerReady。當播放器完全載入且 API 準備好接收調用後,API 便會調用此函數。
onYouTubePlayerReady(playerid)在播放器已完全載入且 API 準備好接收調用的情況下調用。如果 playerapiid 是通過網址參數傳入播放器的,那麼,它也會傳遞到此函數中。示例使用 SWFObject 嵌入 YouTube 播放器我們建議您使用 SWFObject 嵌入可通過 JavaScript API 訪問的任何播放器。這樣,您就可以檢測到最終用戶的 Flash Player 版本(JavaScript API 必須使用 Flash Player 8 或更高的版本),並且避免在使用 Internet Explorer 查看該播放器時彈出「點擊激活此控件」(Click to activate this control) 對話框。要在 SWF 中啟用 API,您必須傳入參數 enablejsapi=1
要瞭解如何使用 script 嵌入已啟用 JavaScript API 並且 playerapiid 為 ytplayer 的 YouTube 播放器,請參見以下示例。
  1. <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>
複製代碼
因為托管播放器的域和托管 HTML 網頁的域是各不相同的,所以,必須在上述代碼中使用 allowScriptAccess 參數,才能讓播放器 SWF 在所包含的 HTML 網頁上調用函數。
我們傳入的唯一一個屬性為嵌入對象的 id,在此示例中即 myytplayer。使用此 ID 即可通過 getElementById() 引用播放器。
swfobject.embedSWF 可從 YouTube 載入播放器並將其嵌入您的網頁中。
swfobject.embedSWF(swfUrlStr, replaceElemIdStr, widthStr, heightStr, swfVersionStr, xiSwfUrlStr, flashvarsObj, parObj, attObj)

  • swfUrlStr - 這是 SWF 的網址。請注意,我們在 YouTube SWF 的常規網址中附加了 enablejsapi 參數和 playerapiid 參數,以便實現 JavaScript API 調用。
  • replaceElemIdStr - 要用嵌入內容替換的 HTML DIV ID。在上述示例中即為 ytapiplayer。
  • widthStr - 播放器寬度。
  • heightStr - 播放器高度。
  • swfVersionStr - 用戶查看內容所需的最低版本。在此情況下,需要版本 8 或更高版本。如果用戶沒有安裝版本 8 或更高版本,則會在 HTML DIV 中看到默認的文本行。
  • xiSwfUrlStr -(可選)用於指定 express install SWF 的網址。此示例中未使用。
  • flashVarsObj -(可選)以名稱:值對的形式指定您的 FlashVars。此示例中未使用。
  • parObj -(可選)嵌入對象的參數。在此示例中設置為 allowScriptAccess。
  • AttObj -(可選)嵌入對象的屬性。在此示例中,我們將 ID 設置為 myytplayer。

有關更多介紹,請參見 SWFObject 文檔
引用播放器在播放器準備就緒後,就會調用 onYouTubePlayerReady
要引用該播放器,請使用 getElementById()。獲得對像後,您就可以開始調用 API。
  1. function onYouTubePlayerReady(playerId) { ytplayer = document.getElementById("myytplayer"); }
複製代碼
進行調用現在,您可以使用播放器的引用調用函數了。比如說,如果您希望在用戶點擊某鏈接後播放相應的視頻,則應調用如下函數:
  1. function play() { if (ytplayer) { ytplayer.playVideo(); } } <a href="javascript:void(0);" onclick="play();">Play</a>
複製代碼
或是簡化形式:
  1. <a href="javascript:ytplayer.playVideo()">Play</a>
複製代碼
訂閱事件在播放器的引用中添加事件偵聽器即可訂閱事件。例如,要在播放器的狀態發生改變時得到通知,請添加針對
onStateChange 的事件偵聽器並加入回調函數。

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

  5. function onytplayerStateChange(newState) {
  6.    alert("Player's new state: " + newState);
  7. }
複製代碼
現場演示您可以使用 YouTube 播放器演示測試 JavaScript API 在嵌入式播放器或 Chromeless Player 中的功能。此外,Google 代碼園地可讓您調試和運行 JavaScript 播放器 API 代碼,從而查看您的代碼對於網絡用戶的顯示效果。

 

臉書網友討論
發表於 2013-11-14 00:43:30 | 顯示全部樓層
支持你加分  

版主招募中

發表於 2013-11-14 00:43:30 | 顯示全部樓層
回復一下  


您需要登錄後才可以回帖 登錄 | 註冊 |

本版積分規則



Archiver|手機版|小黑屋|免責聲明|TShopping

GMT+8, 2016-12-5 04:06 , Processed in 0.079341 second(s), 19 queries .

本論壇言論純屬發表者個人意見,與 TShopping綜合論壇 立場無關 如有意見侵犯了您的權益 請寫信聯絡我們。

Powered by Discuz! X3.2

© 2001-2013 Comsenz Inc.

快速回復 返回頂部 返回列表