API โปรแกรมเล่น iframe ช่วยให้คุณสามารถฝังโปรแกรมเล่นวิดีโอ YouTube ในเว็บไซต์ของคุณและควบคุมโปรแกรมเล่นโดยใช้ JavaScript
เมื่อใช้ฟังก์ชัน JavaScript ของ API คุณสามารถจัดคิววิดีโอสำหรับเล่น เล่น หยุดชั่วคราว หรือหยุดวิดีโอเหล่านั้น ปรับระดับเสียงของโปรแกรมเล่น หรือเรียกดูข้อมูลเกี่ยวกับวิดีโอที่กำลังเล่นได้ นอกจากนี้ คุณสามารถเพิ่ม Listener เหตุการณ์ที่จะทำงานเพื่อตอบสนองต่อเหตุการณ์ของโปรแกรมเล่นบางอย่าง เช่น การเปลี่ยนสถานะโปรแกรมเล่น
คู่มือนี้จะอธิบายถึงวิธีใช้ IFrame API ซึ่งระบุเหตุการณ์ประเภทต่างๆ ที่ API ส่งได้ และอธิบายวิธีเขียน Listener เหตุการณ์เพื่อตอบสนองต่อเหตุการณ์เหล่านั้น นอกจากนี้ยังมีรายละเอียดของฟังก์ชัน JavaScript ต่างๆ ที่คุณเรียกใช้เพื่อควบคุมโปรแกรมเล่นวิดีโอ รวมถึงพารามิเตอร์ของโปรแกรมเล่นที่ใช้เพื่อปรับแต่งโปรแกรมเล่นเพิ่มเติมได้
ข้อกำหนด
เบราว์เซอร์ของผู้ใช้ต้องรองรับฟีเจอร์ postMessage
ของ HTML5 เบราว์เซอร์รุ่นใหม่ส่วนใหญ่จะรองรับ postMessage
โปรแกรมเล่นที่ฝังต้องมีวิวพอร์ตขนาดอย่างน้อย 200 x 200 พิกเซล หากโปรแกรมเล่นแสดงตัวควบคุม ตัวควบคุมนั้นต้องมีขนาดใหญ่พอที่จะแสดงตัวควบคุมได้อย่างสมบูรณ์โดยไม่ต้องย่อวิวพอร์ตให้เล็กลงต่ำกว่าขนาดขั้นต่ำ เราขอแนะนำให้โปรแกรมเล่น 16:9 กว้างอย่างน้อย 480 พิกเซลและสูง 270 พิกเซล
หน้าเว็บที่ใช้ IFrame API ต้องใช้ฟังก์ชัน JavaScript ต่อไปนี้ด้วย:
-
onYouTubeIframeAPIReady
– API จะเรียกใช้ฟังก์ชันนี้เมื่อดาวน์โหลด JavaScript สำหรับ API โปรแกรมเล่นเสร็จแล้ว ซึ่งจะช่วยให้คุณใช้ API ในหน้าเว็บได้ ดังนั้น ฟังก์ชันนี้อาจสร้างออบเจ็กต์โปรแกรมเล่นที่คุณต้องการแสดงเมื่อโหลดหน้าเว็บ
เริ่มต้นใช้งาน
หน้า HTML ตัวอย่างด้านล่างสร้างโปรแกรมเล่นแบบฝังที่จะโหลดวิดีโอ เล่นเป็นเวลา 6 วินาที แล้วหยุดเล่น ความคิดเห็นที่เรียงลำดับเลขใน HTML จะอธิบายในรายการด้านล่างตัวอย่าง
<!DOCTYPE html> <html> <body> <!-- 1. The <iframe> (and video player) will replace this <div> tag. --> <div id="player"></div> <script> // 2. This code loads the IFrame Player API code asynchronously. var tag = document.createElement('script'); tag.src = "https://www.youtube.com/iframe_api"; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); // 3. This function creates an <iframe> (and YouTube player) // after the API code downloads. var player; function onYouTubeIframeAPIReady() { player = new YT.Player('player', { height: '390', width: '640', videoId: 'M7lc1UVf-VE', playerVars: { 'playsinline': 1 }, events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); } // 4. The API will call this function when the video player is ready. function onPlayerReady(event) { event.target.playVideo(); } // 5. The API calls this function when the player's state changes. // The function indicates that when playing a video (state=1), // the player should play for six seconds and then stop. var done = false; function onPlayerStateChange(event) { if (event.data == YT.PlayerState.PLAYING && !done) { setTimeout(stopVideo, 6000); done = true; } } function stopVideo() { player.stopVideo(); } </script> </body> </html>
รายการต่อไปนี้ให้รายละเอียดเพิ่มเติมเกี่ยวกับตัวอย่างข้างต้น
-
แท็ก
<div>
ในส่วนนี้ระบุตำแหน่งบนหน้าเว็บที่ IFrame API จะวางโปรแกรมเล่นวิดีโอ เครื่องมือสร้างสำหรับออบเจ็กต์โปรแกรมเล่น ซึ่งอธิบายไว้ในส่วนการโหลดวิดีโอเพลเยอร์ จะระบุแท็ก<div>
ตามid
เพื่อให้มั่นใจว่า API จะวาง<iframe>
ในตำแหน่งที่เหมาะสม กล่าวโดยละเอียดคือ IFrame API จะแทนที่แท็ก<div>
ด้วยแท็ก<iframe>
หรือคุณจะวางองค์ประกอบ
<iframe>
ไว้ในหน้าโดยตรงก็ได้ ส่วนการโหลดวิดีโอเพลเยอร์จะอธิบายวิธีการดำเนินการ -
โค้ดในส่วนนี้จะโหลดโค้ด JavaScript ของ IFrame Player API ตัวอย่างนี้ใช้การแก้ไข DOM เพื่อดาวน์โหลดโค้ด API เพื่อให้แน่ใจว่ามีการเรียกโค้ดแบบไม่พร้อมกัน (ระบบยังไม่รองรับแอตทริบิวต์
async
ของแท็ก<script>
ซึ่งเปิดใช้การดาวน์โหลดแบบอะซิงโครนัสด้วยเช่นกัน ในเบราว์เซอร์สมัยใหม่ทั้งหมดที่กล่าวถึงในคําตอบของ Stack Overflow -
ฟังก์ชัน
onYouTubeIframeAPIReady
จะทำงานทันทีที่ดาวน์โหลดโค้ด API โปรแกรมเล่น โค้ดส่วนนี้จะระบุตัวแปรร่วม ซึ่งก็คือplayer
ซึ่งหมายถึงโปรแกรมเล่นวิดีโอที่คุณกำลังฝัง จากนั้นฟังก์ชันนี้จะสร้างออบเจ็กต์โปรแกรมเล่นวิดีโอ -
ฟังก์ชัน
onPlayerReady
จะทำงานเมื่อเหตุการณ์onReady
เริ่มทำงาน ในตัวอย่างนี้ ฟังก์ชันระบุว่าเมื่อวิดีโอเพลเยอร์พร้อมแล้ว วิดีโอควรเริ่มเล่น -
API จะเรียกฟังก์ชัน
onPlayerStateChange
เมื่อสถานะของโปรแกรมเล่นเปลี่ยนแปลง ซึ่งอาจบ่งชี้ว่าโปรแกรมเล่นกำลังเล่น หยุดชั่วคราว เล่นจบ และอื่นๆ ฟังก์ชันดังกล่าวระบุว่าเมื่อสถานะของโปรแกรมเล่นเป็น1
(กำลังเล่น) โปรแกรมเล่นควรเล่นเป็นเวลา 6 วินาที แล้วเรียกฟังก์ชันstopVideo
เพื่อหยุดวิดีโอ
กำลังโหลดโปรแกรมเล่นวิดีโอ
หลังจากโค้ด JavaScript ของ API โหลดแล้ว API จะเรียกฟังก์ชัน onYouTubeIframeAPIReady
ซึ่งในจุดนี้ คุณจะสร้างออบเจ็กต์ YT.Player
เพื่อแทรกโปรแกรมเล่นวิดีโอในหน้าเว็บได้ ข้อความ HTML ที่ตัดตอนมาด้านล่างแสดงฟังก์ชัน onYouTubeIframeAPIReady
จากตัวอย่างด้านบน
var player; function onYouTubeIframeAPIReady() { player = new YT.Player('player', { height: '390', width: '640', videoId: 'M7lc1UVf-VE', playerVars: { 'playsinline': 1 }, events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); }
เครื่องมือสร้างสำหรับโปรแกรมเล่นวิดีโอจะระบุพารามิเตอร์ต่อไปนี้
-
พารามิเตอร์แรกระบุองค์ประกอบ DOM หรือ
id
ขององค์ประกอบ HTML ที่ API จะแทรกแท็ก<iframe>
ที่มีโปรแกรมเล่นIFrame API จะแทนที่องค์ประกอบที่ระบุด้วยองค์ประกอบ
<iframe>
ที่มีโปรแกรมเล่น การทำเช่นนี้อาจส่งผลต่อเลย์เอาต์ของหน้าเว็บหากองค์ประกอบที่จะถูกแทนที่มีรูปแบบการแสดงผลต่างจากองค์ประกอบ<iframe>
ที่แทรกไว้ โดยค่าเริ่มต้น<iframe>
จะแสดงเป็นองค์ประกอบinline-block
- พารามิเตอร์ที่ 2 คือออบเจ็กต์ที่ระบุตัวเลือกโปรแกรมเล่น ออบเจ็กต์มีพร็อพเพอร์ตี้ต่อไปนี้
width
(ตัวเลข) – ความกว้างของวิดีโอเพลเยอร์ ค่าเริ่มต้นคือ640
height
(ตัวเลข) – ความสูงของวิดีโอเพลเยอร์ ค่าเริ่มต้นคือ390
videoId
(สตริง) – รหัสวิดีโอ YouTube ที่ระบุวิดีโอที่โปรแกรมเล่นจะโหลดplayerVars
(วัตถุ) – คุณสมบัติของออบเจ็กต์ระบุพารามิเตอร์โปรแกรมเล่น ที่สามารถใช้เพื่อปรับแต่งโปรแกรมเล่นevents
(ออบเจ็กต์) – พร็อพเพอร์ตี้ของออบเจ็กต์ระบุเหตุการณ์ที่ API เริ่มทำงานและฟังก์ชัน (Listener เหตุการณ์) ที่ API จะเรียกเมื่อเหตุการณ์เหล่านั้นเกิดขึ้น ในตัวอย่างนี้ เครื่องมือสร้างระบุว่าฟังก์ชันonPlayerReady
จะทำงานเมื่อเหตุการณ์onReady
เริ่มทำงาน และฟังก์ชันonPlayerStateChange
จะทำงานเมื่อเหตุการณ์onStateChange
เริ่มทำงาน
ดังที่กล่าวไว้ในส่วนเริ่มต้นใช้งาน แทนที่จะเขียนเอลิเมนต์ <div>
ว่างในหน้าเว็บ ซึ่งโค้ด JavaScript ของ API โปรแกรมเล่นจะแทนที่ด้วยเอลิเมนต์ <iframe>
คุณจะสร้างแท็ก <iframe>
ได้ด้วยตัวเอง ตัวอย่างแรกในส่วนตัวอย่างจะแสดงวิธีการ
<iframe id="player" type="text/html" width="640" height="390" src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com" frameborder="0"></iframe>
โปรดทราบว่าหากคุณเขียนแท็ก <iframe>
เมื่อสร้างออบเจ็กต์ YT.Player
คุณไม่จำเป็นต้องระบุค่าสำหรับ width
และ height
ซึ่งระบุเป็นแอตทริบิวต์ของแท็ก <iframe>
หรือ videoId
และพารามิเตอร์ Player ซึ่งระบุอยู่ใน URL ของ src
เพื่อเพิ่มมาตรการรักษาความปลอดภัย คุณควรใส่พารามิเตอร์ origin
ลงใน URL ด้วย โดยระบุชุดรูปแบบ URL (http://
หรือ https://
) และโดเมนแบบเต็มของหน้าโฮสต์เป็นค่าพารามิเตอร์ แม้ว่าคุณจะใช้ origin
หรือไม่ก็ได้ แต่ระบบจะช่วยป้องกันการแทรก JavaScript ของบุคคลที่สามที่เป็นอันตรายลงในหน้าเว็บและการควบคุมการลักลอบใช้บัญชีโปรแกรมเล่น YouTube ของคุณ
ส่วนตัวอย่างจะแสดงตัวอย่างอื่นๆ อีก 2 รายการสำหรับการสร้างออบเจ็กต์วิดีโอเพลเยอร์
การทำงาน
หากต้องการเรียกเมธอด API โปรแกรมเล่น ก่อนอื่นคุณจะต้องได้รับการอ้างอิงถึงออบเจ็กต์โปรแกรมเล่นที่คุณต้องการควบคุม คุณจะได้รับข้อมูลอ้างอิงโดยการสร้างออบเจ็กต์ YT.Player
ตามที่ได้อธิบายไว้ในส่วนการเริ่มต้นใช้งานและการโหลดวิดีโอเพลเยอร์ของเอกสารนี้
ฟังก์ชัน
ฟังก์ชันในคิว
ฟังก์ชันการจัดคิวให้คุณโหลดและเล่นวิดีโอ เพลย์ลิสต์ หรือรายการวิดีโออื่นๆ หากใช้ไวยากรณ์ออบเจ็กต์ที่อธิบายไว้ด้านล่างเพื่อเรียกใช้ฟังก์ชันเหล่านี้ คุณยังจัดคิวหรือโหลดรายการวิดีโอที่ผู้ใช้อัปโหลดได้อีกด้วย
API รองรับไวยากรณ์ 2 แบบที่แตกต่างกันสำหรับการเรียกใช้ฟังก์ชันการจัดคิว
-
ไวยากรณ์ของอาร์กิวเมนต์จำเป็นต้องมีการแสดงอาร์กิวเมนต์ของฟังก์ชันตามลำดับที่กำหนด
-
ไวยากรณ์ของออบเจ็กต์ช่วยให้คุณส่งออบเจ็กต์เป็นพารามิเตอร์เดียวได้ และกำหนดพร็อพเพอร์ตี้ของออบเจ็กต์สําหรับอาร์กิวเมนต์ฟังก์ชันที่คุณต้องการตั้งค่า นอกจากนี้ API อาจรองรับฟังก์ชันการทำงานเพิ่มเติมที่ไวยากรณ์ของอาร์กิวเมนต์ไม่รองรับด้วย
ตัวอย่างเช่น สามารถเรียกฟังก์ชัน loadVideoById
ด้วยวิธีใดก็ได้ต่อไปนี้ โปรดทราบว่าไวยากรณ์ของออบเจ็กต์รองรับพร็อพเพอร์ตี้ endSeconds
ซึ่งไวยากรณ์อาร์กิวเมนต์ไม่รองรับ
-
ไวยากรณ์อาร์กิวเมนต์
loadVideoById("bHQqvYy5KYo", 5, "large")
-
ไวยากรณ์ของออบเจ็กต์
loadVideoById({'videoId': 'bHQqvYy5KYo', 'startSeconds': 5, 'endSeconds': 60});
ฟังก์ชันการจัดคิวสำหรับวิดีโอ
cueVideoById
-
-
ไวยากรณ์อาร์กิวเมนต์
player.cueVideoById(videoId:String, startSeconds:Number):Void
-
ไวยากรณ์ของออบเจ็กต์
player.cueVideoById({videoId:String, startSeconds:Number, endSeconds:Number}):Void
ฟังก์ชันนี้จะโหลดภาพขนาดย่อของวิดีโอที่ระบุ และเตรียมโปรแกรมเล่นให้พร้อมเล่นวิดีโอ โปรแกรมเล่นจะไม่ขอ FLV จนกว่าจะมีการเรียกใช้
playVideo()
หรือseekTo()
- พารามิเตอร์
videoId
ที่จำเป็นจะระบุรหัสวิดีโอ YouTube ของวิดีโอที่จะเล่น ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้id
ของทรัพยากรvideo
จะระบุรหัส - พารามิเตอร์
startSeconds
ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็มและระบุเวลาที่วิดีโอควรเริ่มเล่นเมื่อมีการเรียกใช้playVideo()
หากคุณระบุค่าstartSeconds
แล้วเรียกseekTo()
โปรแกรมเล่นจะเล่นจากเวลาที่ระบุไว้ในการเรียกseekTo()
เมื่อระบบแนะนำวิดีโอและพร้อมเล่นแล้ว โปรแกรมเล่นจะประกาศเหตุการณ์video cued
(5
) - พารามิเตอร์
endSeconds
ที่ไม่บังคับ ซึ่งรองรับเฉพาะในไวยากรณ์ของออบเจ็กต์ ยอมรับจำนวนลอย/จำนวนเต็มและระบุเวลาที่วิดีโอควรหยุดเล่นเมื่อมีการเรียกplayVideo()
หากคุณระบุค่าendSeconds
แล้วเรียกใช้seekTo()
ค่าendSeconds
จะไม่มีผลอีกต่อไป
-
loadVideoById
-
-
ไวยากรณ์อาร์กิวเมนต์
player.loadVideoById(videoId:String, startSeconds:Number):Void
-
ไวยากรณ์ของออบเจ็กต์
player.loadVideoById({videoId:String, startSeconds:Number, endSeconds:Number}):Void
ฟังก์ชันนี้จะโหลดและเล่นวิดีโอที่ระบุ
- พารามิเตอร์
videoId
ที่จำเป็นจะระบุรหัสวิดีโอ YouTube ของวิดีโอที่จะเล่น ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้id
ของทรัพยากรvideo
จะระบุรหัส - พารามิเตอร์
startSeconds
ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็ม หากมีการระบุ วิดีโอจะเริ่มต้นจากคีย์เฟรมที่ใกล้กับเวลาที่ระบุไว้มากที่สุด - พารามิเตอร์
endSeconds
ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็ม หากระบุไว้ วิดีโอจะหยุดเล่นตามเวลาที่กำหนด
-
cueVideoByUrl
-
-
ไวยากรณ์อาร์กิวเมนต์
player.cueVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void
-
ไวยากรณ์ของออบเจ็กต์
player.cueVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number}):Void
ฟังก์ชันนี้จะโหลดภาพขนาดย่อของวิดีโอที่ระบุ และเตรียมโปรแกรมเล่นให้พร้อมเล่นวิดีโอ โปรแกรมเล่นจะไม่ขอ FLV จนกว่าจะมีการเรียกใช้
playVideo()
หรือseekTo()
- พารามิเตอร์
mediaContentUrl
ที่จำเป็นจะระบุ URL ของโปรแกรมเล่น YouTube ที่สมบูรณ์ในรูปแบบhttp://www.youtube.com/v/VIDEO_ID?version=3
- พารามิเตอร์
startSeconds
ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็มและระบุเวลาที่วิดีโอควรเริ่มเล่นเมื่อมีการเรียกใช้playVideo()
หากคุณระบุstartSeconds
แล้วเรียกseekTo()
โปรแกรมเล่นจะเล่นจากเวลาที่ระบุไว้ในการเรียกseekTo()
เมื่อระบบแนะนำวิดีโอและพร้อมเล่นแล้ว โปรแกรมเล่นจะประกาศเหตุการณ์video cued
(5) - พารามิเตอร์
endSeconds
ที่ไม่บังคับ ซึ่งรองรับเฉพาะในไวยากรณ์ของออบเจ็กต์ ยอมรับจำนวนลอย/จำนวนเต็มและระบุเวลาที่วิดีโอควรหยุดเล่นเมื่อมีการเรียกplayVideo()
หากคุณระบุค่าendSeconds
แล้วเรียกใช้seekTo()
ค่าendSeconds
จะไม่มีผลอีกต่อไป
-
loadVideoByUrl
-
-
ไวยากรณ์อาร์กิวเมนต์
player.loadVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void
-
ไวยากรณ์ของออบเจ็กต์
player.loadVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number}):Void
ฟังก์ชันนี้จะโหลดและเล่นวิดีโอที่ระบุ
- พารามิเตอร์
mediaContentUrl
ที่จำเป็นจะระบุ URL ของโปรแกรมเล่น YouTube ที่สมบูรณ์ในรูปแบบhttp://www.youtube.com/v/VIDEO_ID?version=3
- พารามิเตอร์
startSeconds
ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็มและระบุเวลาที่วิดีโอควรเริ่มเล่น หากระบุstartSeconds
(ตัวเลขเป็นแบบลอยได้) วิดีโอจะเริ่มต้นจากคีย์เฟรมที่ใกล้กับเวลาที่ระบุไว้มากที่สุด - พารามิเตอร์
endSeconds
ที่ไม่บังคับ ซึ่งรองรับเฉพาะในไวยากรณ์ของออบเจ็กต์ ยอมรับจำนวนลอย/จำนวนเต็มและระบุเวลาที่วิดีโอควรหยุดเล่น
-
ฟังก์ชันการจัดคิวสำหรับรายการ
ฟังก์ชัน cuePlaylist
และ loadPlaylist
ช่วยให้คุณโหลดและเล่นเพลย์ลิสต์ได้ หากใช้ไวยากรณ์ออบเจ็กต์เพื่อเรียกใช้ฟังก์ชันเหล่านี้ คุณยังจัดคิว (หรือโหลด) รายการวิดีโอที่อัปโหลดของผู้ใช้ได้ด้วย
เนื่องจากฟังก์ชันจะทำงานต่างกัน ขึ้นอยู่กับว่ามีการเรียกใช้โดยใช้ไวยากรณ์อาร์กิวเมนต์หรือไวยากรณ์ของออบเจ็กต์ วิธีการเรียกใช้ทั้ง 2 วิธีจะมีการบันทึกไว้ที่ด้านล่าง
cuePlaylist
-
-
ไวยากรณ์อาร์กิวเมนต์
player.cuePlaylist(playlist:String|Array, index:Number, startSeconds:Number):Void
จัดคิวเพลย์ลิสต์ที่ระบุ เมื่อระบบจัดลำดับเพลย์ลิสต์และพร้อมเล่นแล้ว โปรแกรมเล่นจะประกาศเหตุการณ์video cued
(5
)-
พารามิเตอร์
playlist
ที่จำเป็นจะระบุอาร์เรย์ของรหัสวิดีโอ YouTube ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้id
ของทรัพยากรvideo
จะระบุรหัสของวิดีโอ -
พารามิเตอร์
index
ที่ไม่บังคับจะระบุดัชนีของวิดีโอแรกในเพลย์ลิสต์ที่จะเล่น พารามิเตอร์นี้ใช้ดัชนีที่อิงตาม 0 และค่าพารามิเตอร์เริ่มต้นคือ0
ดังนั้นลักษณะการทำงานเริ่มต้นคือการโหลดและเล่นวิดีโอแรกในเพลย์ลิสต์ -
พารามิเตอร์
startSeconds
ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็ม และระบุเวลาที่วิดีโอแรกในเพลย์ลิสต์ควรเริ่มเล่นเมื่อมีการเรียกใช้ฟังก์ชันplayVideo()
หากคุณระบุค่าstartSeconds
แล้วเรียกseekTo()
โปรแกรมเล่นจะเล่นจากเวลาที่ระบุไว้ในการเรียกseekTo()
หากคุณแนะนำเพลย์ลิสต์แล้วเรียกใช้ฟังก์ชันplayVideoAt()
โปรแกรมเล่นจะเริ่มเล่นเมื่อเริ่มต้นวิดีโอที่ระบุ
-
-
ไวยากรณ์ของออบเจ็กต์
player.cuePlaylist({listType:String, list:String, index:Number, startSeconds:Number}):Void
จัดคิวรายการวิดีโอที่ระบุ รายการอาจเป็นเพลย์ลิสต์หรือฟีดวิดีโอที่อัปโหลดของผู้ใช้ ระบบเลิกใช้งานความสามารถในการจัดคิวรายการผลการค้นหาแล้ว และระบบจะไม่รองรับอีกต่อไปตั้งแต่วันที่15 พฤศจิกายน 2020 เมื่อระบบแนะนำรายการและพร้อมเล่นแล้ว โปรแกรมเล่นจะประกาศเหตุการณ์
video cued
(5
)-
พร็อพเพอร์ตี้
listType
ที่ไม่บังคับจะระบุประเภทของฟีดผลลัพธ์ที่คุณกำลังดึงข้อมูล ค่าที่ถูกต้องคือplaylist
และuser_uploads
ระบบจะไม่รองรับค่าsearch
ที่เลิกใช้งานแล้วอีกต่อไปตั้งแต่วันที่15 พฤศจิกายน 2020 ค่าเริ่มต้นคือplaylist
-
พร็อพเพอร์ตี้
list
ที่จำเป็นมีคีย์ที่ระบุรายการวิดีโอที่ YouTube ควรแสดงผล- หากค่าพร็อพเพอร์ตี้
listType
คือplaylist
พร็อพเพอร์ตี้list
จะระบุรหัสเพลย์ลิสต์หรืออาร์เรย์ของรหัสวิดีโอ ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้id
ของทรัพยากรplaylist
จะระบุรหัสของเพลย์ลิสต์ และพร็อพเพอร์ตี้id
ของทรัพยากรvideo
จะระบุรหัสวิดีโอ - หากค่าพร็อพเพอร์ตี้
listType
คือuser_uploads
พร็อพเพอร์ตี้list
จะระบุผู้ใช้ที่เป็นเจ้าของวิดีโอที่อัปโหลด - หากค่าพร็อพเพอร์ตี้
listType
คือsearch
พร็อพเพอร์ตี้list
จะระบุคำค้นหา หมายเหตุ: ฟังก์ชันการทำงานนี้เลิกใช้งานแล้ว และระบบจะไม่รองรับอีกต่อไปตั้งแต่วันที่15 พฤศจิกายน 2020
- หากค่าพร็อพเพอร์ตี้
-
พร็อพเพอร์ตี้
index
ที่ไม่บังคับจะระบุดัชนีของวิดีโอแรกในรายการที่จะเล่น พารามิเตอร์นี้ใช้ดัชนีที่อิงตาม 0 และค่าพารามิเตอร์เริ่มต้นคือ0
ดังนั้นลักษณะการทำงานเริ่มต้นคือการโหลดและเล่นวิดีโอแรกในรายการ -
พร็อพเพอร์ตี้
startSeconds
ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็ม และระบุเวลาที่วิดีโอแรกในรายการควรเริ่มเล่นเมื่อมีการเรียกใช้ฟังก์ชันplayVideo()
หากคุณระบุค่าstartSeconds
แล้วเรียกseekTo()
โปรแกรมเล่นจะเล่นจากเวลาที่ระบุไว้ในการเรียกseekTo()
หากคุณเริ่มรายการแล้วเรียกฟังก์ชันplayVideoAt()
โปรแกรมเล่นจะเริ่มเล่นเมื่อเริ่มต้นวิดีโอที่ระบุ
-
-
loadPlaylist
-
-
ไวยากรณ์อาร์กิวเมนต์
player.loadPlaylist(playlist:String|Array, index:Number, startSeconds:Number):Void
ฟังก์ชันนี้จะโหลดเพลย์ลิสต์ที่ระบุและเล่น-
พารามิเตอร์
playlist
ที่จำเป็นจะระบุอาร์เรย์ของรหัสวิดีโอ YouTube ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้id
ของทรัพยากรvideo
จะระบุรหัสวิดีโอ -
พารามิเตอร์
index
ที่ไม่บังคับจะระบุดัชนีของวิดีโอแรกในเพลย์ลิสต์ที่จะเล่น พารามิเตอร์นี้ใช้ดัชนีที่อิงตาม 0 และค่าพารามิเตอร์เริ่มต้นคือ0
ดังนั้นลักษณะการทำงานเริ่มต้นคือการโหลดและเล่นวิดีโอแรกในเพลย์ลิสต์ -
พารามิเตอร์
startSeconds
ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็ม และระบุเวลาที่วิดีโอแรกในเพลย์ลิสต์ควรเริ่มเล่น
-
-
ไวยากรณ์ของออบเจ็กต์
player.loadPlaylist({list:String, listType:String, index:Number, startSeconds:Number}):Void
ฟังก์ชันนี้จะโหลดรายการที่ระบุและเล่น รายการอาจเป็นเพลย์ลิสต์หรือฟีดวิดีโอที่อัปโหลดของผู้ใช้ เราเลิกใช้งานความสามารถในการโหลดรายการผลการค้นหาแล้ว และจะไม่รองรับอีกต่อไปตั้งแต่วันที่15 พฤศจิกายน 2020 -
พร็อพเพอร์ตี้
listType
ที่ไม่บังคับจะระบุประเภทของฟีดผลลัพธ์ที่คุณกำลังดึงข้อมูล ค่าที่ถูกต้องคือplaylist
และuser_uploads
ระบบจะไม่รองรับค่าsearch
ที่เลิกใช้งานแล้วอีกต่อไปตั้งแต่วันที่15 พฤศจิกายน 2020 ค่าเริ่มต้นคือplaylist
-
พร็อพเพอร์ตี้
list
ที่จำเป็นมีคีย์ที่ระบุรายการวิดีโอที่ YouTube ควรแสดงผล- หากค่าพร็อพเพอร์ตี้
listType
คือplaylist
พร็อพเพอร์ตี้list
จะระบุรหัสเพลย์ลิสต์หรืออาร์เรย์ของรหัสวิดีโอ ใน API ข้อมูลของ YouTube พร็อพเพอร์ตี้id
ของทรัพยากรplaylist
จะระบุรหัสของเพลย์ลิสต์ และพร็อพเพอร์ตี้id
ของทรัพยากรvideo
ระบุรหัสวิดีโอ - หากค่าพร็อพเพอร์ตี้
listType
คือuser_uploads
พร็อพเพอร์ตี้list
จะระบุผู้ใช้ที่เป็นเจ้าของวิดีโอที่อัปโหลด - หากค่าพร็อพเพอร์ตี้
listType
คือsearch
พร็อพเพอร์ตี้list
จะระบุคำค้นหา หมายเหตุ: ฟังก์ชันการทำงานนี้เลิกใช้งานแล้ว และระบบจะไม่รองรับอีกต่อไปตั้งแต่วันที่15 พฤศจิกายน 2020
- หากค่าพร็อพเพอร์ตี้
-
พร็อพเพอร์ตี้
index
ที่ไม่บังคับจะระบุดัชนีของวิดีโอแรกในรายการที่จะเล่น พารามิเตอร์นี้ใช้ดัชนีที่อิงตาม 0 และค่าพารามิเตอร์เริ่มต้นคือ0
ดังนั้นลักษณะการทำงานเริ่มต้นคือการโหลดและเล่นวิดีโอแรกในรายการ -
พร็อพเพอร์ตี้
startSeconds
ที่ไม่บังคับจะยอมรับจำนวนลอยตัว/จำนวนเต็ม และระบุเวลาที่วิดีโอแรกในรายการควรเริ่มเล่น
-
-
ส่วนควบคุมการเล่นและการตั้งค่าโปรแกรมเล่น
กำลังเล่นวิดีโอ
player.playVideo():Void
- เล่นวิดีโอที่เล่น/โหลดอยู่ในปัจจุบัน สถานะโปรแกรมเล่นสุดท้ายหลังจากดำเนินการฟังก์ชันนี้คือ
playing
(1)
หมายเหตุ: การเล่นจะนับรวมกับยอดดูอย่างเป็นทางการของวิดีโอหากการเล่นผ่านปุ่มเล่นภายในโปรแกรมเล่นเท่านั้น
player.pauseVideo():Void
- หยุดวิดีโอที่เล่นอยู่ชั่วคราว สถานะโปรแกรมเล่นสุดท้ายหลังจากที่ฟังก์ชันนี้ทำงานจะเป็น
paused
(2
) เว้นแต่โปรแกรมเล่นจะอยู่ในสถานะended
(0
) เมื่อมีการเรียกใช้ฟังก์ชัน ซึ่งในกรณีนี้สถานะของโปรแกรมเล่นจะไม่เปลี่ยนแปลง
player.stopVideo():Void
- หยุดและยกเลิกการโหลดวิดีโอปัจจุบัน ฟังก์ชันนี้ควรสงวนไว้สำหรับสถานการณ์ที่เกิดขึ้นไม่บ่อยนักเมื่อคุณทราบว่าผู้ใช้จะไม่ดูวิดีโอเพิ่มเติมในโปรแกรมเล่นแล้ว หากตั้งใจให้หยุดวิดีโอชั่วคราว คุณควรเรียกใช้ฟังก์ชัน
pauseVideo
หากต้องการเปลี่ยนวิดีโอที่โปรแกรมเล่นกำลังเล่น คุณสามารถเรียกใช้ฟังก์ชันการจัดคิวรายการใดรายการหนึ่งได้โดยไม่ต้องเรียกstopVideo
ก่อน
สำคัญ: ฟังก์ชันstopVideo
ต่างจากฟังก์ชันpauseVideo
ซึ่งปล่อยให้โปรแกรมเล่นอยู่ในสถานะpaused
(2
) ตรงที่สามารถทำให้โปรแกรมเล่นอยู่ในสถานะที่ไม่ได้เล่น ซึ่งรวมถึงended
(0
),paused
(2
),video cued
(5
) หรือunstarted
(-1
)
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
- กรอไปยังเวลาที่ระบุไว้ในวิดีโอ แต่หากเครื่องเล่นหยุดชั่วคราวเมื่อมีการเรียกใช้ฟังก์ชัน โปรแกรมเล่นก็จะหยุดชั่วคราวตามปกติ หากมีการเรียกฟังก์ชันจากสถานะอื่น (
playing
,video cued
ฯลฯ) โปรแกรมเล่นจะเล่นวิดีโอ-
พารามิเตอร์
seconds
ระบุเวลาที่โปรแกรมเล่นควรเล่นต่อโปรแกรมเล่นจะเลื่อนไปที่คีย์เฟรมที่ใกล้ที่สุดก่อนถึงเวลาดังกล่าว เว้นแต่โปรแกรมเล่นจะดาวน์โหลดวิดีโอส่วนที่ผู้ใช้กำลังมองหาไปแล้ว
-
พารามิเตอร์
allowSeekAhead
จะกำหนดว่าโปรแกรมเล่นจะส่งคำขอใหม่ไปยังเซิร์ฟเวอร์หรือไม่หากพารามิเตอร์seconds
ระบุเวลาที่อยู่นอกข้อมูลวิดีโอที่บัฟเฟอร์ในปัจจุบันเราขอแนะนำให้คุณตั้งค่าพารามิเตอร์นี้เป็น
false
ขณะที่ผู้ใช้ลากเมาส์ไปตามแถบความคืบหน้าของวิดีโอ แล้วตั้งค่าเป็นtrue
เมื่อผู้ใช้ปล่อยเมาส์ วิธีนี้จะทำให้ผู้ใช้สามารถเลื่อนไปยังจุดต่างๆ ของวิดีโอได้โดยไม่ต้องขอสตรีมวิดีโอใหม่โดยการเลื่อนผ่านจุดที่ยังไม่ได้บัฟเฟอร์ในวิดีโอ เมื่อผู้ใช้ปล่อยปุ่มเมาส์ เครื่องเล่นจะเลื่อนไปยังจุดที่ต้องการในวิดีโอและส่งคำขอสตรีมวิดีโอใหม่หากจำเป็น
-
การควบคุมการเล่นวิดีโอ 360°
หมายเหตุ: การเล่นวิดีโอ 360° มีการรองรับที่จำกัดในอุปกรณ์เคลื่อนที่ บนอุปกรณ์ที่ไม่รองรับ วิดีโอ 360° จะแสดงในรูปแบบบิดเบี้ยวและไม่มีวิธีที่รองรับในการเปลี่ยนมุมมองการดูเลย รวมถึงผ่านทาง API, การใช้เซ็นเซอร์การวางแนว หรือตอบสนองต่อการทำงานด้วยการแตะ/ลากบนหน้าจอของอุปกรณ์
player.getSphericalProperties():Object
- เรียกข้อมูลพร็อพเพอร์ตี้ที่อธิบายมุมมองหรือมุมมองปัจจุบันของผู้ชมสำหรับการเล่นวิดีโอ นอกจากนี้
- ออบเจ็กต์นี้สร้างขึ้นสำหรับวิดีโอ 360 องศาเท่านั้น ซึ่งเรียกอีกอย่างว่าวิดีโอ 360 องศา
- หากวิดีโอปัจจุบันไม่ใช่วิดีโอ 360° หรือหากมีการเรียกฟังก์ชันจากอุปกรณ์ที่ไม่รองรับ ฟังก์ชันจะแสดงผลเป็นวัตถุเปล่า
- ในอุปกรณ์เคลื่อนที่ที่รองรับ หากตั้งค่าพร็อพเพอร์ตี้
enableOrientationSensor
เป็นtrue
ฟังก์ชันนี้จะแสดงออบเจ็กต์ที่พร็อพเพอร์ตี้fov
มีค่าที่ถูกต้อง และมีการตั้งค่าพร็อพเพอร์ตี้อื่นๆ เป็น0
พร็อพเพอร์ตี้ yaw
ตัวเลขในช่วง [0, 360) ที่แสดงมุมแนวนอนของมุมมองเป็นองศา ซึ่งแสดงถึงขอบเขตที่ผู้ใช้หันมุมมองไปทางด้านซ้ายหรือขวา ตำแหน่งที่เป็นกลางซึ่งหันเข้าหากึ่งกลางของวิดีโอในเส้นโครงแบบทรงกลมจะแสดงถึง 0° และค่านี้จะเพิ่มขึ้นเมื่อผู้ชมหันไปทางซ้าย pitch
ตัวเลขในช่วง [-90, 90] แสดงมุมแนวตั้งของมุมมองเป็นองศา ซึ่งแสดงถึงขอบเขตที่ผู้ใช้ปรับมุมมองให้มองขึ้นหรือลง ตำแหน่งที่เป็นกลางซึ่งหันเข้าหากึ่งกลางของวิดีโอในเส้นโครงแบบทรงกลมจะแสดงถึง 0° และค่านี้จะเพิ่มขึ้นเมื่อผู้ชมมองขึ้น roll
ตัวเลขในช่วง [-180, 180] ที่แสดงมุมหมุนตามเข็มนาฬิกาหรือทวนเข็มนาฬิกาของมุมมองเป็นองศา ตำแหน่งที่เป็นกลางซึ่งมีแกนแนวนอนในเส้นโครงทรงกลมเป็นแนวขนานกับแกนแนวนอนของมุมมอง ค่าจะแสดงเป็น 0° ค่าจะเพิ่มขึ้นเมื่อมุมมองหมุนตามเข็มนาฬิกาและลดลงเมื่อมุมมองหมุนทวนเข็มนาฬิกา
โปรดทราบว่าโปรแกรมเล่นแบบฝังจะไม่แสดงอินเทอร์เฟซผู้ใช้สำหรับการปรับการหมุนของมุมมอง คุณปรับเปลี่ยนม้วนโฆษณาด้วยวิธีใดวิธีหนึ่งต่อไปนี้ไม่ได้- ใช้เซ็นเซอร์การวางแนวในเบราว์เซอร์บนอุปกรณ์เคลื่อนที่เพื่อหมุนมุมมอง หากเปิดใช้เซ็นเซอร์การวางแนว ฟังก์ชัน
getSphericalProperties
จะแสดงผล0
เป็นค่าของพร็อพเพอร์ตี้roll
เสมอ - หากเซ็นเซอร์การวางแนวปิดอยู่ ให้ตั้งค่าการหมุนเป็นค่าที่ไม่ใช่ 0 โดยใช้ API นี้
fov
ตัวเลขในช่วง [30, 120] ที่แสดงถึงขอบเขตการมองเห็นของมุมมองเป็นองศาที่วัดตามขอบที่ยาวขึ้นของวิวพอร์ต ระบบจะปรับขอบที่สั้นลงโดยอัตโนมัติให้เป็นสัดส่วนกับสัดส่วนภาพของมุมมอง
ค่าเริ่มต้นคือ 100 องศา การลดมูลค่าก็เหมือนการซูมเข้าในเนื้อหาวิดีโอ และการเพิ่มคุณค่าก็เหมือนกับการซูมออก คุณสามารถปรับค่านี้ได้โดยใช้ API หรือลูกกลิ้งเมาส์เมื่อวิดีโออยู่ในโหมดเต็มหน้าจอ
player.setSphericalProperties(properties:Object):Void
- กำหนดการวางแนวของวิดีโอสำหรับการเล่นวิดีโอ 360° (หากวิดีโอปัจจุบันไม่ใช่ 360 องศา เมธอดจะไม่มีตัวเลือกใดๆ โดยไม่คำนึงถึงอินพุต)
มุมมองโปรแกรมเล่นจะตอบสนองต่อการเรียกวิธีนี้ด้วยการอัปเดตเพื่อแสดงค่าของพร็อพเพอร์ตี้ที่รู้จักในออบเจ็กต์properties
มุมมองจะยังคงค่าสำหรับพร็อพเพอร์ตี้อื่นๆ ที่รู้จักซึ่งไม่ได้รวมอยู่ในออบเจ็กต์นั้น
นอกจากนี้- หากวัตถุมีพร็อพเพอร์ตี้ที่ไม่รู้จักและ/หรือที่ไม่คาดคิด โปรแกรมเล่นจะเพิกเฉยต่อวัตถุเหล่านั้น
- ตามที่อธิบายไว้ในตอนต้นของส่วนนี้ อุปกรณ์เคลื่อนที่บางรุ่นไม่รองรับประสบการณ์การเล่นวิดีโอ 360°
- โดยค่าเริ่มต้น ในอุปกรณ์เคลื่อนที่ที่รองรับ ฟังก์ชันนี้จะตั้งค่าพร็อพเพอร์ตี้
fov
เท่านั้น และไม่ส่งผลต่อพร็อพเพอร์ตี้yaw
,pitch
และroll
สำหรับการเล่นวิดีโอ 360° ดูรายละเอียดเพิ่มเติมได้จากพร็อพเพอร์ตี้enableOrientationSensor
ด้านล่าง
properties
ที่ส่งไปยังฟังก์ชันจะมีพร็อพเพอร์ตี้ต่อไปนี้พร็อพเพอร์ตี้ yaw
ดูคำจำกัดความด้านบน pitch
ดูคำจำกัดความด้านบน roll
ดูคำจำกัดความด้านบน fov
ดูคำจำกัดความด้านบน enableOrientationSensor
หมายเหตุ: พร็อพเพอร์ตี้นี้ส่งผลต่อประสบการณ์การดูแบบ 360° ในอุปกรณ์ที่รองรับเท่านั้นค่าบูลีนที่ระบุว่าการฝัง IFrame ควรตอบสนองต่อเหตุการณ์ที่สัญญาณการเปลี่ยนการวางแนวของอุปกรณ์ที่รองรับหรือไม่ เช่น DeviceOrientationEvent
ของเบราว์เซอร์ในอุปกรณ์เคลื่อนที่ ค่าพารามิเตอร์เริ่มต้นคือtrue
อุปกรณ์เคลื่อนที่ที่รองรับ- เมื่อค่านี้เป็น
true
โปรแกรมเล่นแบบฝังจะอาศัยการเคลื่อนไหวของอุปกรณ์เท่านั้นในการปรับคุณสมบัติyaw
,pitch
และroll
สำหรับการเล่นวิดีโอ 360° อย่างไรก็ตาม คุณยังเปลี่ยนแปลงพร็อพเพอร์ตี้fov
ผ่าน API ได้ และจริงๆ แล้ว API เป็นเพียงวิธีเดียวในการเปลี่ยนพร็อพเพอร์ตี้fov
ในอุปกรณ์เคลื่อนที่ นี่คือลักษณะการทำงานเริ่มต้น - เมื่อค่านี้เป็น
false
การเคลื่อนที่ของอุปกรณ์จะไม่ส่งผลต่อประสบการณ์การดูแบบ 360° และต้องตั้งค่าพร็อพเพอร์ตี้yaw
,pitch
,roll
และfov
ผ่าน API
อุปกรณ์เคลื่อนที่ที่ไม่รองรับ
ค่าพร็อพเพอร์ตี้enableOrientationSensor
จะไม่มีผลต่อประสบการณ์การเล่น
การเล่นวิดีโอในเพลย์ลิสต์
player.nextVideo():Void
- ฟังก์ชันนี้จะโหลดและเล่นวิดีโอถัดไปในเพลย์ลิสต์
-
หากมีการเรียก
player.nextVideo()
ขณะกำลังดูวิดีโอสุดท้ายในเพลย์ลิสต์ และมีการตั้งค่าเพลย์ลิสต์ให้เล่นอย่างต่อเนื่อง (loop
) โปรแกรมเล่นจะโหลดและเล่นวิดีโอแรกในรายการ -
หากมีการเรียก
player.nextVideo()
ขณะกำลังดูวิดีโอสุดท้ายในเพลย์ลิสต์ และเพลย์ลิสต์ไม่ได้ตั้งค่าให้เล่นอย่างต่อเนื่อง การเล่นจะสิ้นสุดลง
-
player.previousVideo():Void
- ฟังก์ชันนี้จะโหลดและเล่นวิดีโอก่อนหน้าในเพลย์ลิสต์
-
หากมีการเรียก
player.previousVideo()
ขณะกำลังดูวิดีโอแรกในเพลย์ลิสต์ และมีการตั้งค่าเพลย์ลิสต์ให้เล่นอย่างต่อเนื่อง (loop
) โปรแกรมเล่นจะโหลดและเล่นวิดีโอสุดท้ายในรายการ -
หากมีการเรียก
player.previousVideo()
ขณะที่มีการรับชมวิดีโอแรกในเพลย์ลิสต์และไม่ได้ตั้งค่าให้เล่นอย่างต่อเนื่อง โปรแกรมเล่นจะรีสตาร์ทวิดีโอในเพลย์ลิสต์แรกตั้งแต่ต้น
-
player.playVideoAt(index:Number):Void
- ฟังก์ชันนี้จะโหลดและเล่นวิดีโอที่ระบุในเพลย์ลิสต์
-
พารามิเตอร์
index
ที่จำเป็นจะระบุดัชนีของวิดีโอที่คุณต้องการเล่นในเพลย์ลิสต์ พารามิเตอร์นี้ใช้ดัชนีที่อิงตาม 0 ดังนั้นค่า0
จะระบุวิดีโอแรกในรายการ หากคุณสุ่มเพลงในเพลย์ลิสต์ ฟังก์ชันนี้จะเล่นวิดีโอในตำแหน่งที่ระบุไว้ในเพลย์ลิสต์ที่สุ่มเพลง
-
การเปลี่ยนระดับเสียงโปรแกรมเล่น
player.mute():Void
- ปิดเสียงโปรแกรมเล่น
player.unMute():Void
- เปิดเสียงโปรแกรมเล่น
player.isMuted():Boolean
- ส่งคืน
true
หากโปรแกรมเล่นปิดเสียงอยู่false
หากปิดเสียงอยู่
player.setVolume(volume:Number):Void
- ปรับระดับเสียง ยอมรับจำนวนเต็มระหว่าง
0
ถึง100
player.getVolume():Number
- ส่งคืนระดับเสียงปัจจุบันของโปรแกรมเล่น ซึ่งเป็นจำนวนเต็มระหว่าง
0
ถึง100
โปรดทราบว่าgetVolume()
จะปรับระดับเสียงให้แม้จะปิดเสียงโปรแกรมเล่นอยู่
การตั้งค่าขนาดของโปรแกรมเล่น
player.setSize(width:Number, height:Number):Object
- ตั้งค่าขนาดเป็นพิกเซลของ
<iframe>
ที่มีโปรแกรมเล่น
การตั้งค่าอัตราการเล่น
player.getPlaybackRate():Number
- ฟังก์ชันนี้จะดึงข้อมูลอัตราการเล่นของวิดีโอที่กำลังเล่นอยู่ อัตราการเล่นเริ่มต้นคือ
1
ซึ่งบ่งบอกว่าวิดีโอกำลังเล่นที่ความเร็วปกติ อัตราการเล่นอาจรวมค่าต่างๆ เช่น0.25
,0.5
,1
,1.5
และ2
player.setPlaybackRate(suggestedRate:Number):Void
- ฟังก์ชันนี้จะกำหนดอัตราการเล่นที่แนะนำสำหรับวิดีโอปัจจุบัน หากอัตราการเล่นมีการเปลี่ยนแปลง การเปลี่ยนแปลงจะเกิดขึ้นเฉพาะกับวิดีโอที่เล่นแล้วหรือกำลังเล่นอยู่ หากคุณตั้งค่าอัตราการเล่นสำหรับวิดีโอที่บันทึกไว้ อัตราดังกล่าวจะยังคงมีผลเมื่อมีการเรียกใช้ฟังก์ชัน
playVideo
หรือผู้ใช้เริ่มเล่นโดยตรงผ่านตัวควบคุมวิดีโอเพลเยอร์ นอกจากนี้ ฟังก์ชันการเรียกเพื่อกำหนดหรือโหลดวิดีโอหรือเพลย์ลิสต์ (cueVideoById
,loadVideoById
ฯลฯ) จะรีเซ็ตอัตราการเล่นเป็น1
การเรียกใช้ฟังก์ชันนี้ไม่ได้รับประกันว่าอัตราการเล่นจะเปลี่ยนแปลงจริง อย่างไรก็ตาม หากอัตราการเล่นมีการเปลี่ยนแปลง เหตุการณ์onPlaybackRateChange
จะเริ่มทำงาน และโค้ดของคุณควรตอบสนองต่อเหตุการณ์ดังกล่าวมากกว่าที่จะเรียกเหตุการณ์ว่าฟังก์ชันsetPlaybackRate
เมธอดgetAvailablePlaybackRates
จะแสดงอัตราการเล่นที่เป็นไปได้สำหรับวิดีโอที่กำลังเล่นอยู่ อย่างไรก็ตาม หากคุณตั้งค่าพารามิเตอร์suggestedRate
เป็นจำนวนเต็มหรือค่าจำนวนลอยตัวที่ไม่รองรับ โปรแกรมเล่นจะปัดค่านั้นลงเป็นค่าที่รองรับซึ่งใกล้เคียงที่สุดในทิศทางของ1
player.getAvailablePlaybackRates():Array
- ฟังก์ชันนี้จะแสดงชุดอัตราการเล่นที่สามารถเล่นวิดีโอปัจจุบันได้ ค่าเริ่มต้นคือ
1
ซึ่งระบุว่าวิดีโอกำลังเล่นด้วยความเร็วปกติ
ฟังก์ชันนี้จะแสดงผลอาร์เรย์ของตัวเลขที่เรียงลำดับจากความเร็วในการเล่นช้าที่สุดไปเร็วที่สุด แม้ว่าโปรแกรมเล่นจะไม่รองรับความเร็วในการเล่นที่เปลี่ยนแปลงได้ แต่อาร์เรย์ควรมีค่าอย่างน้อย 1 ค่าเสมอ (1
)
การตั้งค่าลักษณะการเล่นสำหรับเพลย์ลิสต์
player.setLoop(loopPlaylists:Boolean):Void
-
ฟังก์ชันนี้ระบุว่าโปรแกรมเล่นวิดีโอควรเล่นเพลย์ลิสต์อย่างต่อเนื่องหรือควรหยุดเล่นหลังจากวิดีโอสุดท้ายในเพลย์ลิสต์สิ้นสุดลง โดยมีลักษณะการทำงานเริ่มต้นคือเพลย์ลิสต์จะไม่วนซ้ำ
การตั้งค่านี้จะยังคงอยู่แม้ว่าคุณจะโหลดหรือแนะนำเพลย์ลิสต์อื่น ซึ่งหมายความว่าหากคุณโหลดเพลย์ลิสต์ ให้เรียกใช้ฟังก์ชัน
setLoop
ด้วยค่าtrue
แล้วโหลดเพลย์ลิสต์ที่ 2 เพลย์ลิสต์ที่ 2 ก็จะวนซ้ำด้วยเช่นกันพารามิเตอร์
loopPlaylists
ที่จำเป็นจะระบุพฤติกรรมการวนซ้ำ-
หากค่าพารามิเตอร์คือ
true
โปรแกรมเล่นวิดีโอจะเล่นเพลย์ลิสต์อย่างต่อเนื่อง หลังจากเล่นวิดีโอสุดท้ายในเพลย์ลิสต์แล้ว โปรแกรมเล่นวิดีโอจะกลับไปที่จุดเริ่มต้นของเพลย์ลิสต์และเล่นอีกครั้ง -
หากค่าพารามิเตอร์คือ
false
การเล่นจะสิ้นสุดลงหลังจากโปรแกรมเล่นวิดีโอเล่นวิดีโอสุดท้ายในเพลย์ลิสต์
-
player.setShuffle(shufflePlaylist:Boolean):Void
-
ฟังก์ชันนี้จะระบุว่าควรสุ่มวิดีโอในเพลย์ลิสต์หรือไม่ เพื่อให้เล่นตามลำดับที่ต่างจากวิดีโอที่ผู้สร้างเพลย์ลิสต์กำหนดไว้ หากคุณสุ่มเพลย์ลิสต์หลังจากที่เริ่มเล่นแล้ว รายการจะจัดเรียงใหม่ขณะที่วิดีโอที่กำลังเล่นจะยังคงเล่นต่อไป วิดีโอถัดไปที่จะเล่นจะถูกเลือกตามรายการที่เรียงลำดับใหม่
การตั้งค่านี้จะไม่คงอยู่หากคุณโหลดหรือแนะนำเพลย์ลิสต์อื่น ซึ่งหมายความว่าหากคุณโหลดเพลย์ลิสต์ ให้เรียกใช้ฟังก์ชัน
setShuffle
แล้วโหลดเพลย์ลิสต์ที่ 2 ระบบจะไม่สุ่มเล่นเพลย์ลิสต์ที่ 2พารามิเตอร์
shufflePlaylist
ที่จำเป็นจะระบุว่า YouTube ควรสุ่มเพลงในเพลย์ลิสต์หรือไม่-
หากค่าพารามิเตอร์คือ
true
YouTube จะสุ่มลำดับเพลย์ลิสต์ หากคุณสั่งให้ฟังก์ชันสุ่มเพลงในเพลย์ลิสต์ที่สุ่มเพลงแล้ว YouTube จะสุ่มลำดับอีกครั้ง -
หากค่าพารามิเตอร์คือ
false
YouTube จะเปลี่ยนลำดับเพลย์ลิสต์กลับไปเป็นลำดับเดิม
-
สถานะการเล่น
player.getVideoLoadedFraction():Float
- แสดงผลตัวเลขระหว่าง
0
ถึง1
ที่ระบุเปอร์เซ็นต์ของวิดีโอที่โปรแกรมเล่นแสดงเป็นบัฟเฟอร์ เมธอดนี้แสดงตัวเลขที่เชื่อถือได้มากกว่าเมธอดgetVideoBytesLoaded
และgetVideoBytesTotal
ที่เลิกใช้งานแล้ว
player.getPlayerState():Number
- ส่งคืนสถานะของโปรแกรมเล่น ค่าที่เป็นไปได้มีดังนี้
-1
– ยังไม่เริ่ม0
– สิ้นสุดแล้ว1
– กำลังเล่น2
– หยุดชั่วคราว3
– กำลังบัฟเฟอร์5
– แนะนำวิดีโอ
player.getCurrentTime():Number
- แสดงผลเวลาที่ผ่านไปเป็นวินาทีนับจากที่วิดีโอเริ่มเล่น
player.getVideoStartBytes():Number
- เลิกใช้งานตั้งแต่วันที่ 31 ตุลาคม 2012 แสดงผลจำนวนไบต์ของไฟล์วิดีโอที่เริ่มโหลด (ตอนนี้วิธีนี้จะแสดงค่า
0
เสมอ) สถานการณ์ตัวอย่าง: ผู้ใช้กรอไปยังจุดที่ยังไม่ได้โหลด และโปรแกรมเล่นส่งคำขอใหม่เพื่อเล่นส่วนของวิดีโอที่ยังไม่ได้โหลด
player.getVideoBytesLoaded():Number
-
เลิกใช้งานตั้งแต่วันที่ 18 กรกฎาคม 2012 ให้ใช้เมธอด
getVideoLoadedFraction
แทนเพื่อระบุเปอร์เซ็นต์ของวิดีโอที่มีบัฟเฟอร์
เมธอดนี้จะแสดงค่าระหว่าง0
ถึง1000
ซึ่งประมาณจำนวนของวิดีโอที่โหลดไปแล้ว คำนวณเศษส่วนของวิดีโอที่มีการโหลดได้โดยนำค่าgetVideoBytesLoaded
ไปหารด้วยค่าgetVideoBytesTotal
player.getVideoBytesTotal():Number
-
เลิกใช้งานตั้งแต่วันที่ 18 กรกฎาคม 2012 ให้ใช้เมธอด
getVideoLoadedFraction
แทนเพื่อระบุเปอร์เซ็นต์ของวิดีโอที่มีบัฟเฟอร์
แสดงผลขนาดเป็นไบต์ของวิดีโอที่กำลังโหลด/กำลังเล่น หรือขนาดโดยประมาณของวิดีโอ
เมธอดนี้จะแสดงค่า1000
เสมอ คำนวณเศษส่วนของวิดีโอที่มีการโหลดได้โดยนำค่าgetVideoBytesLoaded
ไปหารด้วยค่าgetVideoBytesTotal
กำลังดึงข้อมูลวิดีโอ
player.getDuration():Number
- แสดงผลระยะเวลาเป็นวินาทีของวิดีโอที่กำลังเล่นอยู่ โปรดทราบว่า
getDuration()
จะส่งกลับ0
จนกว่าข้อมูลเมตาของวิดีโอจะโหลดเสร็จ ซึ่งโดยปกติจะเกิดขึ้นหลังจากที่วิดีโอเริ่มเล่นพอดี
หากวิดีโอที่กำลังเล่นเป็นการถ่ายทอดสด ฟังก์ชันgetDuration()
จะแสดงผลเวลาที่ผ่านไปนับตั้งแต่เริ่มสตรีมวิดีโอสด กล่าวคือ เป็นระยะเวลาที่วิดีโอสตรีมโดยไม่รีเซ็ตหรือขัดจังหวะ นอกจากนี้ ระยะเวลานี้ยังมักนานกว่าเวลาจริงของกิจกรรม เนื่องจากการสตรีมอาจเริ่มก่อนเวลาเริ่มต้นของกิจกรรม
player.getVideoUrl():String
- แสดง URL ของ YouTube.com สำหรับวิดีโอที่โหลด/เล่นอยู่ในขณะนี้
player.getVideoEmbedCode():String
- ส่งคืนโค้ดสำหรับฝังสำหรับวิดีโอที่โหลด/เล่นอยู่ในขณะนี้
กำลังดึงข้อมูลเพลย์ลิสต์
player.getPlaylist():Array
- ฟังก์ชันนี้จะแสดงอาร์เรย์ของรหัสวิดีโอในเพลย์ลิสต์ตามการเรียงลำดับในขณะนี้ โดยค่าเริ่มต้น ฟังก์ชันนี้จะแสดงรหัสวิดีโอตามลำดับที่เจ้าของเพลย์ลิสต์กำหนด แต่หากคุณเรียกใช้ฟังก์ชัน
setShuffle
เพื่อสุ่มลำดับเพลย์ลิสต์ ค่าผลลัพธ์ของฟังก์ชันgetPlaylist()
จะแสดงลำดับการสับเปลี่ยน
player.getPlaylistIndex():Number
- ฟังก์ชันนี้จะแสดงดัชนีของวิดีโอในเพลย์ลิสต์ที่กำลังเล่นอยู่
-
หากคุณไม่ได้เล่นเพลย์ลิสต์แบบสุ่ม ค่าผลลัพธ์จะระบุตำแหน่งที่ผู้สร้างเพลย์ลิสต์วางวิดีโอ ค่าผลลัพธ์จะใช้ดัชนีแบบ 0 ดังนั้นค่า
0
จะเป็นตัวระบุวิดีโอแรกในเพลย์ลิสต์ -
หากคุณสุ่มเพลย์ลิสต์ ค่าการแสดงผลจะระบุลำดับของวิดีโอภายในเพลย์ลิสต์ที่สุ่มเพลง
-
การเพิ่มหรือนํา Listener เหตุการณ์ออก
player.addEventListener(event:String, listener:String):Void
- เพิ่มฟังก์ชัน Listener สำหรับ
event
ที่ระบุ ส่วนเหตุการณ์ด้านล่างระบุเหตุการณ์ต่างๆ ที่โปรแกรมเล่นอาจเริ่มทำงาน Listener คือสตริงที่ระบุฟังก์ชันที่จะทำงานเมื่อเหตุการณ์ที่ระบุเริ่มทำงาน
player.removeEventListener(event:String, listener:String):Void
- นำฟังก์ชัน Listener สำหรับ
event
ที่ระบุออกlistener
คือสตริงที่ระบุฟังก์ชันที่จะไม่ทำงานอีกต่อไปเมื่อเหตุการณ์ที่ระบุเริ่มทำงาน
การเข้าถึงและการแก้ไขโหนด DOM
player.getIframe():Object
- เมธอดนี้แสดงโหนด DOM สำหรับ
<iframe>
ที่ฝัง
player.destroy():Void
- นำ
<iframe>
ที่มีโปรแกรมเล่นออก
กิจกรรม
API จะเริ่มการทำงานของเหตุการณ์เพื่อแจ้งเตือนการใช้การเปลี่ยนแปลงของคุณกับโปรแกรมเล่นที่ฝัง ดังที่ระบุไว้ในส่วนก่อนหน้า คุณติดตามเหตุการณ์ได้โดยการเพิ่ม Listener เหตุการณ์เมื่อสร้างออบเจ็กต์ YT.Player
และคุณยังใช้ฟังก์ชัน addEventListener
ได้ด้วย
API จะส่งออบเจ็กต์เหตุการณ์เป็นอาร์กิวเมนต์เดียวไปยังแต่ละฟังก์ชันเหล่านั้น ออบเจ็กต์เหตุการณ์มีพร็อพเพอร์ตี้ต่อไปนี้
target
ของเหตุการณ์จะระบุโปรแกรมเล่นวิดีโอที่เกี่ยวข้องกับเหตุการณ์ดังกล่าวdata
ของเหตุการณ์จะระบุค่าที่เกี่ยวข้องกับเหตุการณ์ โปรดทราบว่าเหตุการณ์onReady
และonAutoplayBlocked
ไม่ได้ระบุพร็อพเพอร์ตี้data
รายการต่อไปนี้ระบุเหตุการณ์ที่ API เริ่มทำงาน
onReady
- เหตุการณ์นี้จะเริ่มทำงานเมื่อโปรแกรมเล่นโหลดเสร็จแล้วและพร้อมเริ่มรับการเรียก API แอปพลิเคชันของคุณควรใช้ฟังก์ชันนี้หากคุณต้องการให้ดำเนินการบางอย่างโดยอัตโนมัติ เช่น เล่นวิดีโอหรือแสดงข้อมูลเกี่ยวกับวิดีโอทันทีที่โปรแกรมเล่นพร้อม
ตัวอย่างด้านล่างแสดงฟังก์ชันตัวอย่างสำหรับการจัดการกิจกรรมนี้ ออบเจ็กต์เหตุการณ์ที่ API ส่งไปยังฟังก์ชันจะมีพร็อพเพอร์ตี้target
ซึ่งระบุโปรแกรมเล่น ฟังก์ชันนี้จะดึงโค้ดที่ฝังสำหรับวิดีโอที่โหลดอยู่ เริ่มเล่นวิดีโอ และแสดงโค้ดที่ฝังในองค์ประกอบของหน้าที่มีค่าid
เป็นembed-code
function onPlayerReady(event) { var embedCode = event.target.getVideoEmbedCode(); event.target.playVideo(); if (document.getElementById('embed-code')) { document.getElementById('embed-code').innerHTML = embedCode; } }
onStateChange
- เหตุการณ์นี้จะเริ่มทำงานเมื่อสถานะของผู้เล่นเปลี่ยนแปลง
พร็อพเพอร์ตี้
data
ของออบเจ็กต์เหตุการณ์ที่ API ส่งไปยังฟังก์ชัน Listener เหตุการณ์จะระบุจำนวนเต็มที่สอดคล้องกับสถานะโปรแกรมเล่นใหม่ โดยค่าที่เป็นไปได้มีดังนี้-1
(ยังไม่เริ่ม)0
(สิ้นสุดแล้ว)1
(กำลังเล่น)2
(หยุดชั่วคราว)3
(กำลังบัฟเฟอร์)5
(คิววิดีโอ)
unstarted
(-1
) เมื่อระบบแนะนำวิดีโอและพร้อมเล่นแล้ว โปรแกรมเล่นจะออกอากาศกิจกรรมvideo cued
(5
) คุณระบุค่าจำนวนเต็มหรือเลือกใช้ตัวแปรเนมสเปซต่อไปนี้ในโค้ดได้YT.PlayerState.ENDED
YT.PlayerState.PLAYING
YT.PlayerState.PAUSED
YT.PlayerState.BUFFERING
YT.PlayerState.CUED
onPlaybackQualityChange
- เหตุการณ์นี้จะเริ่มทำงานเมื่อคุณภาพการเล่นวิดีโอเปลี่ยนแปลง สิ่งนี้อาจเป็นสัญญาณของการเปลี่ยนแปลงสภาพแวดล้อมการเล่นของผู้ชม ไปที่ศูนย์ช่วยเหลือของ YouTube เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับปัจจัยที่ส่งผลต่อเงื่อนไขการเล่นหรือเหตุการณ์ที่อาจทำให้เหตุการณ์เริ่มทำงาน
ค่าพร็อพเพอร์ตี้data
ของออบเจ็กต์เหตุการณ์ที่ API ส่งไปยังฟังก์ชัน Listener เหตุการณ์จะเป็นสตริงที่ระบุคุณภาพการเล่นใหม่ โดยค่าที่เป็นไปได้มีดังนี้small
medium
large
hd720
hd1080
highres
onPlaybackRateChange
- เหตุการณ์นี้จะเริ่มทำงานเมื่ออัตราการเล่นวิดีโอเปลี่ยนแปลง เช่น หากคุณเรียกใช้ฟังก์ชัน
setPlaybackRate(suggestedRate)
เหตุการณ์นี้จะเริ่มทำงานหากอัตราการเล่นมีการเปลี่ยนแปลงจริง แอปพลิเคชันของคุณควรตอบสนองต่อเหตุการณ์และไม่ควรคิดว่าอัตราการเล่นจะเปลี่ยนแปลงโดยอัตโนมัติเมื่อมีการเรียกใช้ฟังก์ชันsetPlaybackRate(suggestedRate)
ในทำนองเดียวกัน โค้ดของคุณไม่ควรคิดว่าอัตราการเล่นวิดีโอจะเปลี่ยนไปเป็นผลของการเรียกsetPlaybackRate
อย่างชัดแจ้งเท่านั้น
ค่าพร็อพเพอร์ตี้data
ของออบเจ็กต์เหตุการณ์ที่ API ส่งไปยังฟังก์ชัน Listener เหตุการณ์จะเป็นตัวเลขที่ระบุอัตราการเล่นใหม่ เมธอดgetAvailablePlaybackRates
จะแสดงรายการอัตราการเล่นที่ถูกต้องสำหรับวิดีโอที่ระบุหรือกำลังเล่นอยู่
onError
- เหตุการณ์นี้จะเริ่มทำงานหากเกิดข้อผิดพลาดในโปรแกรมเล่น
API จะส่งออบเจ็กต์
event
ไปยังฟังก์ชัน Listener เหตุการณ์ พร็อพเพอร์ตี้data
ของออบเจ็กต์ดังกล่าวจะระบุจำนวนเต็มที่ระบุประเภทข้อผิดพลาดที่เกิดขึ้น โดยค่าที่เป็นไปได้มีดังนี้2
– คำขอมีค่าพารามิเตอร์ที่ไม่ถูกต้อง ตัวอย่างเช่น ข้อผิดพลาดนี้จะเกิดขึ้นหากคุณระบุรหัสวิดีโอที่มีอักขระไม่เกิน 11 ตัว หรือหากรหัสวิดีโอมีอักขระที่ไม่ถูกต้อง เช่น เครื่องหมายอัศเจรีย์หรือเครื่องหมายดอกจัน5
– เนื้อหาที่ขอไม่สามารถเล่นในโปรแกรมเล่น HTML5 หรือเกิดข้อผิดพลาดอื่นที่เกี่ยวข้องกับโปรแกรมเล่น HTML5 ขึ้น100
– ไม่พบวิดีโอที่ขอ ข้อผิดพลาดนี้เกิดขึ้นเมื่อวิดีโอถูกนำออก (ไม่ว่าด้วยเหตุผลใดก็ตาม) หรือถูกทำเครื่องหมายเป็นส่วนตัว101
– เจ้าของวิดีโอที่ร้องขอไม่อนุญาตให้เล่นวิดีโอดังกล่าวในโปรแกรมเล่นที่ฝัง150
– ข้อผิดพลาดนี้เหมือนกับ101
นี่เป็นข้อผิดพลาด101
ในการปลอมแปลง
onApiChange
- เหตุการณ์นี้จะเริ่มทำงานเพื่อระบุว่าโปรแกรมเล่นได้โหลด (หรือยกเลิกการโหลด) โมดูลด้วยเมธอด API ที่เปิดเผย แอปพลิเคชันของคุณสามารถฟังเหตุการณ์นี้แล้วสำรวจโปรแกรมเล่นเพื่อกำหนดตัวเลือกที่จะแสดงสำหรับโมดูลที่เพิ่งโหลด จากนั้นแอปพลิเคชันของคุณจะเรียกหรืออัปเดตการตั้งค่าที่มีอยู่สำหรับตัวเลือกเหล่านั้นได้
คำสั่งต่อไปนี้จะเรียกข้อมูลอาร์เรย์ของชื่อโมดูลที่คุณตั้งค่าตัวเลือกโปรแกรมเล่นได้
player.getOptions();
ปัจจุบันโมดูลเดียวที่คุณตั้งค่าตัวเลือกได้คือโมดูลcaptions
ซึ่งจัดการคำบรรยายแทนเสียงในโปรแกรมเล่น เมื่อได้รับเหตุการณ์onApiChange
แอปพลิเคชันจะใช้คำสั่งต่อไปนี้เพื่อกำหนดตัวเลือกที่จะตั้งค่าสำหรับโมดูลcaptions
ได้
player.getOptions('captions');
การใช้คำสั่งนี้ในการสอบถามโปรแกรมเล่น คุณจะยืนยันได้ว่าตัวเลือกที่ต้องการเข้าถึงนั้นเข้าถึงจริงๆ คำสั่งต่อไปนี้เรียกดูและอัปเดตตัวเลือกโมดูล
Retrieving an option: player.getOption(module, option); Setting an option player.setOption(module, option, value);
ตารางด้านล่างแสดงรายการตัวเลือกที่ API รองรับ
โมดูล ตัวเลือก คำอธิบาย captions fontSize ตัวเลือกนี้จะปรับขนาดแบบอักษรของคำบรรยายที่แสดงในโปรแกรมเล่น
ค่าที่ใช้ได้คือ-1
,0
,1
,2
และ3
ขนาดเริ่มต้นคือ0
และขนาดเล็กที่สุดคือ-1
การตั้งค่าตัวเลือกนี้เป็นจำนวนเต็มที่ต่ำกว่า-1
จะทำให้คำบรรยายแสดงขนาดที่เล็กที่สุด ขณะที่ตัวเลือกนี้เป็นจำนวนเต็มที่มากกว่า3
จะทำให้คำบรรยายแสดงขนาดที่ใหญ่ที่สุดcaptions โหลดซ้ำ ตัวเลือกนี้จะโหลดข้อมูลคำบรรยายแทนเสียงของวิดีโอที่กำลังเล่นอีกครั้ง ค่าจะเป็น null
หากคุณดึงค่าของตัวเลือก ตั้งค่าเป็นtrue
เพื่อโหลดข้อมูลคำบรรยายซ้ำ
onAutoplayBlocked
- เหตุการณ์นี้จะเริ่มทำงานทุกครั้งที่เบราว์เซอร์บล็อกฟีเจอร์เล่นอัตโนมัติหรือฟีเจอร์การเล่นวิดีโอตามสคริปต์ ซึ่งรวมเรียกว่า "เล่นอัตโนมัติ" ซึ่งรวมถึงการพยายามเล่นด้วย API โปรแกรมเล่นต่อไปนี้
- พารามิเตอร์
autoplay
รายการ - ฟังก์ชัน
loadPlaylist
- ฟังก์ชัน
loadVideoById
- ฟังก์ชัน
loadVideoByUrl
- ฟังก์ชัน
playVideo
โปรดดูรายละเอียดทั้งหมดได้ที่นโยบายเฉพาะเบราว์เซอร์ (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) และคู่มือการเล่นอัตโนมัติของ Mozilla - พารามิเตอร์
ตัวอย่าง
กำลังสร้างออบเจ็กต์ YT.Player
รายการ
-
ตัวอย่างที่ 1: ใช้ API กับ <iframe> ที่มีอยู่
ในตัวอย่างนี้ เอลิเมนต์
<iframe>
บนหน้าเว็บกำหนดโปรแกรมเล่นที่จะใช้ API อยู่แล้ว โปรดทราบว่า URLsrc
ของโปรแกรมเล่นต้องตั้งค่าพารามิเตอร์enablejsapi
เป็น1
หรือต้องตั้งค่าแอตทริบิวต์enablejsapi
ขององค์ประกอบ<iframe>
เป็นtrue
ฟังก์ชัน
onPlayerReady
จะเปลี่ยนสีของเส้นขอบรอบๆ โปรแกรมเล่นให้เป็นสีส้มเมื่อโปรแกรมเล่นพร้อมแล้ว จากนั้นฟังก์ชันonPlayerStateChange
จะเปลี่ยนสีเส้นขอบรอบโปรแกรมเล่นวิดีโอตามสถานะของโปรแกรมเล่นปัจจุบัน ตัวอย่างเช่น สีจะเป็นสีเขียวเมื่อโปรแกรมเล่นวิดีโอกำลังเล่น สีแดงเมื่อหยุดชั่วคราว สีน้ำเงินเมื่อบัฟเฟอร์ และอื่นๆตัวอย่างนี้ใช้โค้ดต่อไปนี้
<iframe id="existing-iframe-example" width="640" height="360" src="https://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1" frameborder="0" style="border: solid 4px #37474F" ></iframe> <script type="text/javascript"> var tag = document.createElement('script'); tag.id = 'iframe-demo'; tag.src = 'https://www.youtube.com/iframe_api'; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); var player; function onYouTubeIframeAPIReady() { player = new YT.Player('existing-iframe-example', { events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange } }); } function onPlayerReady(event) { document.getElementById('existing-iframe-example').style.borderColor = '#FF6D00'; } function changeBorderColor(playerStatus) { var color; if (playerStatus == -1) { color = "#37474F"; // unstarted = gray } else if (playerStatus == 0) { color = "#FFFF00"; // ended = yellow } else if (playerStatus == 1) { color = "#33691E"; // playing = green } else if (playerStatus == 2) { color = "#DD2C00"; // paused = red } else if (playerStatus == 3) { color = "#AA00FF"; // buffering = purple } else if (playerStatus == 5) { color = "#FF6DOO"; // video cued = orange } if (color) { document.getElementById('existing-iframe-example').style.borderColor = color; } } function onPlayerStateChange(event) { changeBorderColor(event.data); } </script>
-
ตัวอย่างที่ 2: การเล่นเสียงดัง
ตัวอย่างนี้สร้างโปรแกรมเล่นวิดีโอขนาด 1280 x 720 พิกเซล จากนั้น Listener เหตุการณ์ของเหตุการณ์
onReady
จะเรียกฟังก์ชันsetVolume
เพื่อปรับระดับเสียงเป็นการตั้งค่าสูงสุดfunction onYouTubeIframeAPIReady() { var player; player = new YT.Player('player', { width: 1280, height: 720, videoId: 'M7lc1UVf-VE', events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange, 'onError': onPlayerError } }); } function onPlayerReady(event) { event.target.setVolume(100); event.target.playVideo(); }
-
ตัวอย่างที่ 3: ตัวอย่างนี้ตั้งค่าพารามิเตอร์ของโปรแกรมเล่นให้เล่นวิดีโอโดยอัตโนมัติเมื่อโหลดขึ้นและซ่อนตัวควบคุมของโปรแกรมเล่นวิดีโอ นอกจากนี้ ยังเพิ่ม Listener เหตุการณ์สำหรับหลายๆ เหตุการณ์ที่ API เผยแพร่
function onYouTubeIframeAPIReady() { var player; player = new YT.Player('player', { videoId: 'M7lc1UVf-VE', playerVars: { 'autoplay': 1, 'controls': 0 }, events: { 'onReady': onPlayerReady, 'onStateChange': onPlayerStateChange, 'onError': onPlayerError } }); }
การควบคุมวิดีโอ 360°
ตัวอย่างนี้ใช้โค้ดต่อไปนี้
<style> .current-values { color: #666; font-size: 12px; } </style> <!-- The player is inserted in the following div element --> <div id="spherical-video-player"></div> <!-- Display spherical property values and enable user to update them. --> <table style="border: 0; width: 640px;"> <tr style="background: #fff;"> <td> <label for="yaw-property">yaw: </label> <input type="text" id="yaw-property" style="width: 80px"><br> <div id="yaw-current-value" class="current-values"> </div> </td> <td> <label for="pitch-property">pitch: </label> <input type="text" id="pitch-property" style="width: 80px"><br> <div id="pitch-current-value" class="current-values"> </div> </td> <td> <label for="roll-property">roll: </label> <input type="text" id="roll-property" style="width: 80px"><br> <div id="roll-current-value" class="current-values"> </div> </td> <td> <label for="fov-property">fov: </label> <input type="text" id="fov-property" style="width: 80px"><br> <div id="fov-current-value" class="current-values"> </div> </td> <td style="vertical-align: bottom;"> <button id="spherical-properties-button">Update properties</button> </td> </tr> </table> <script type="text/javascript"> var tag = document.createElement('script'); tag.id = 'iframe-demo'; tag.src = 'https://www.youtube.com/iframe_api'; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov']; var updateButton = document.getElementById('spherical-properties-button'); // Create the YouTube Player. var ytplayer; function onYouTubeIframeAPIReady() { ytplayer = new YT.Player('spherical-video-player', { height: '360', width: '640', videoId: 'FAtdv94yzp4', }); } // Don't display current spherical settings because there aren't any. function hideCurrentSettings() { for (var p = 0; p < PROPERTIES.length; p++) { document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = ''; } } // Retrieve current spherical property values from the API and display them. function updateSetting() { if (!ytplayer || !ytplayer.getSphericalProperties) { hideCurrentSettings(); } else { let newSettings = ytplayer.getSphericalProperties(); if (Object.keys(newSettings).length === 0) { hideCurrentSettings(); } else { for (var p = 0; p < PROPERTIES.length; p++) { if (newSettings.hasOwnProperty(PROPERTIES[p])) { currentValueNode = document.getElementById(PROPERTIES[p] + '-current-value'); currentValueNode.innerHTML = ('current: ' + newSettings[PROPERTIES[p]].toFixed(4)); } } } } requestAnimationFrame(updateSetting); } updateSetting(); // Call the API to update spherical property values. updateButton.onclick = function() { var sphericalProperties = {}; for (var p = 0; p < PROPERTIES.length; p++) { var propertyInput = document.getElementById(PROPERTIES[p] + '-property'); sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value); } ytplayer.setSphericalProperties(sphericalProperties); } </script>
การผสานรวม Android WebView Media Integrity API
YouTube ได้ขยายการใช้งาน Android WebView Media Integrity API เพื่อเปิดใช้มีเดียเพลเยอร์แบบฝัง ซึ่งรวมถึงการฝังโปรแกรมเล่น YouTube ในแอปพลิเคชัน Android เพื่อยืนยันความถูกต้องของแอปที่ฝัง การเปลี่ยนแปลงนี้จะทำให้แอปที่ฝังส่งรหัสแอปที่ได้รับการรับรองไปยัง YouTube โดยอัตโนมัติ ข้อมูลที่รวบรวมผ่านการใช้ API นี้คือข้อมูลเมตาของแอป (ชื่อแพ็กเกจ หมายเลขเวอร์ชัน และใบรับรองการรับรอง) และโทเค็นเอกสารรับรองของอุปกรณ์ที่สร้างโดยบริการ Google Play
ระบบจะใช้ข้อมูลนี้เพื่อยืนยันความสมบูรณ์ของแอปพลิเคชันและอุปกรณ์ โดยจะเข้ารหัส ไม่แชร์กับบุคคลที่สาม และลบทิ้งตามระยะเวลาเก็บรักษาคงที่ นักพัฒนาแอปจะกำหนดค่าข้อมูลระบุตัวตนของแอปใน WebView Media Integrity API ได้ การกำหนดค่านี้รองรับตัวเลือกในการเลือกไม่ใช้
ประวัติการแก้ไข
June 24, 2024
The documentation has been updated to note that YouTube has extended the Android WebView Media Integrity API to enable embedded media players, including YouTube player embeds in Android applications, to verify the embedding app's authenticity. With this change, embedding apps automatically send an attested app ID to YouTube.
November 20, 2023
The new onAutoplayBlocked
event API is now available.
This event notifies your application if the browser blocks autoplay or scripted playback.
Verification of autoplay success or failure is an
established paradigm
for HTMLMediaElements, and the onAutoplayBlocked
event now provides similar
functionality for the IFrame Player API.
April 27, 2021
The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars
object to customize the player.
October 13, 2020
Note: This is a deprecation announcement for the embedded player
functionality that lets you configure the player to load search results. This announcement affects
the IFrame Player API's queueing functions for lists,
cuePlaylist
and
loadPlaylist
.
This change will become effective on or after cuePlaylist
or loadPlaylist
functions that set the listType
property to search
will generate a 4xx
response code, such as
404
(Not Found
) or 410
(Gone
). This change
also affects the list
property for those functions as that property no longer
supports the ability to specify a search query.
As an alternative, you can use the YouTube Data API's
search.list
method to retrieve search
results and then load selected videos in the player.
October 24, 2019
The documentation has been updated to reflect the fact that the API no longer supports functions for setting or retrieving playback quality. As explained in this YouTube Help Center article, to give you the best viewing experience, YouTube adjusts the quality of your video stream based on your viewing conditions.
The changes explained below have been in effect for more than one year. This update merely aligns the documentation with current functionality:
- The
getPlaybackQuality
,setPlaybackQuality
, andgetAvailableQualityLevels
functions are no longer supported. In particular, calls tosetPlaybackQuality
will be no-op functions, meaning they will not actually have any impact on the viewer's playback experience. - The queueing functions for videos and playlists --
cueVideoById
,loadVideoById
, etc. -- no longer support thesuggestedQuality
argument. Similarly, if you call those functions using object syntax, thesuggestedQuality
field is no longer supported. IfsuggestedQuality
is specified, it will be ignored when the request is handled. It will not generate any warnings or errors. - The
onPlaybackQualityChange
event is still supported and might signal a change in the viewer's playback environment. See the Help Center article referenced above for more information about factors that affect playback conditions or that might cause the event to fire.
May 16, 2018
The API now supports features that allow users (or embedders) to control the viewing perspective for 360° videos:
- The
getSphericalProperties
function retrieves the current orientation for the video playback. The orientation includes the following data:- yaw - represents the horizontal angle of the view in degrees, which reflects the extent to which the user turns the view to face further left or right
- pitch - represents the vertical angle of the view in degrees, which reflects the extent to which the user adjusts the view to look up or down
- roll - represents the rotational angle (clockwise or counterclockwise) of the view in degrees.
- fov - represents the field-of-view of the view in degrees, which reflects the extent to which the user zooms in or out on the video.
- The
setSphericalProperties
function modifies the view to match the submitted property values. In addition to the orientation values described above, this function supports a Boolean field that indicates whether the IFrame embed should respond toDeviceOrientationEvents
on supported mobile devices.
This example demonstrates and lets you test these new features.
June 19, 2017
This update contains the following changes:
-
Documentation for the YouTube Flash Player API and YouTube JavaScript Player API has been removed and redirected to this document. The deprecation announcement for the Flash and JavaScript players was made on January 27, 2015. If you haven't done so already, please migrate your applications to use IFrame embeds and the IFrame Player API.
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.
June 29, 2016
This update contains the following changes:
-
The documentation has been corrected to note that the
onApiChange
method provides access to thecaptions
module and not thecc
module.
June 24, 2016
The Examples section has been updated to include an example that demonstrates how to use the API with an existing <iframe>
element.
January 6, 2016
The clearVideo
function has been deprecated and removed from the documentation. The function no longer has any effect in the YouTube player.
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.
April 28, 2014
This update contains the following changes:
-
The new removeEventListener function lets you remove a listener for a specified event.
March 25, 2014
This update contains the following changes:
-
The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.
July 23, 2013
This update contains the following changes:
-
The Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.
October 31, 2012
This update contains the following changes:
-
The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.
In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)
-
When called using object syntax, each of the video queueing functions supports an
endSeconds
property, which accepts a float/integer and specifies the time when the video should stop playing whenplayVideo()
is called. -
The
getVideoStartBytes
method has been deprecated. The method now always returns a value of0
.
August 22, 2012
This update contains the following changes:
-
The example in the Loading a video player section that demonstrates how to manually create the
<iframe>
tag has been updated to include a closing</iframe>
tag since theonYouTubeIframeAPIReady
function is only called if the closing</iframe>
element is present.
August 6, 2012
This update contains the following changes:
-
The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.
-
The API supports several new functions and one new event that can be used to control the video playback speed:
-
Functions
getAvailablePlaybackRates
– Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.getPlaybackRate
– Retrieve the playback rate for the cued or playing video.setPlaybackRate
– Set the playback rate for the cued or playing video.
-
Events
onPlaybackRateChange
– This event fires when the video's playback rate changes.
-
July 19, 2012
This update contains the following changes:
-
The new
getVideoLoadedFraction
method replaces the now-deprecatedgetVideoBytesLoaded
andgetVideoBytesTotal
methods. The new method returns the percentage of the video that the player shows as buffered. -
The
onError
event may now return an error code of5
, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred. -
The Requirements section has been updated to indicate that any web page using the IFrame API must also implement the
onYouTubeIframeAPIReady
function. Previously, the section indicated that the required function was namedonYouTubePlayerAPIReady
. Code samples throughout the document have also been updated to use the new name.Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has an onYouTubeIframeAPIReady
function and anonYouTubePlayerAPIReady
function, both functions will be called, and theonYouTubeIframeAPIReady
function will be called first. -
The code sample in the Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to
http://www.youtube.com/iframe_api
. To ensure that this change does not affect existing implementations, the old URL (http://www.youtube.com/player_api
) will continue to work.
July 16, 2012
This update contains the following changes:
-
The Operations section now explains that the API supports the
setSize()
anddestroy()
methods. ThesetSize()
method sets the size in pixels of the<iframe>
that contains the player and thedestroy()
method removes the<iframe>
.
June 6, 2012
This update contains the following changes:
-
We have removed the
experimental
status from the IFrame Player API. -
The Loading a video player section has been updated to point out that when inserting the
<iframe>
element that will contain the YouTube player, the IFrame API replaces the element specified in the constructor for the YouTube player. This documentation change does not reflect a change in the API and is intended solely to clarify existing behavior.In addition, that section now notes that the insertion of the
<iframe>
element could affect the layout of your page if the element being replaced has a different display style than the inserted<iframe>
element. By default, an<iframe>
displays as aninline-block
element.
March 30, 2012
This update contains the following changes:
-
The Operations section has been updated to explain that the IFrame API supports a new method,
getIframe()
, which returns the DOM node for the IFrame embed.
March 26, 2012
This update contains the following changes:
-
The Requirements section has been updated to note the minimum player size.