ממשק API של נגן IFrame מאפשר לכם להטמיע נגן וידאו של YouTube באתר שלכם ולשלוט בנגן באמצעות JavaScript.
באמצעות פונקציות ה-JavaScript של ממשק ה-API, ניתן להוסיף סרטונים לרשימת הבאים בתור להפעלה, להפעיל, להשהות או לעצור את הסרטונים האלה, לשנות את עוצמת הקול של הנגן או לאחזר מידע על הסרטון שמופעל. אפשר גם להוסיף פונקציות event listener שיופעלו בתגובה לאירועי נגן מסוימים, כמו שינוי מצב הנגן.
במדריך הזה מוסבר איך להשתמש ב-IFrame API. היא מזהה את סוגי האירועים השונים שה-API יכול לשלוח, ומסביר איך לכתוב פונקציות event listener כדי להגיב לאירועים האלה. הוא גם מפרט את הפונקציות השונות של JavaScript שאפשר להשתמש בהן כדי לשלוט בנגן הווידאו, כמו גם את הפרמטרים של הנגן שבהם אפשר להשתמש כדי להתאים אישית את הנגן.
דרישות
הדפדפן של המשתמש חייב לתמוך בתכונה postMessage
HTML5. רוב הדפדפנים המודרניים תומכים ב-postMessage
.
נגנים מוטמעים חייבים להשתמש באזור תצוגה של לפחות 200px על 200px. אם הנגן מציג פקדים, הוא חייב להיות גדול מספיק כדי להציג את הפקדים במלואם בלי לכווץ את אזור התצוגה מתחת לגודל המינימלי. אנחנו ממליצים על נגנים בפורמט 16:9 להיות ברוחב של 480 פיקסלים ואורך של 270 פיקסלים לפחות.
כל דף אינטרנט שמשתמש ב-IFrame API חייב להטמיע גם את פונקציית JavaScript הבאה:
-
onYouTubeIframeAPIReady
– ה-API יקרא לפונקציה הזו לאחר שהדף יסיים להוריד את ה-JavaScript עבור ממשק ה-API של הנגן, וכך תוכלו להשתמש ב-API בדף. לכן, הפונקציה הזו עשויה ליצור את האובייקטים של הנגן שתרצו להציג כשהדף נטען.
תחילת העבודה
דף ה-HTML לדוגמה הבא יוצר נגן מוטמע שיטען סרטון, יפעיל אותו למשך שש שניות ולאחר מכן יעצור את ההפעלה. ההערות הממוספרות ב-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
(פועל), הנגן צריך לפעול במשך שש שניות ולאחר מכן להפעיל את הפונקציה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
. - הפרמטר השני הוא אובייקט שמציין את אפשרויות הנגן. האובייקט מכיל את המאפיינים הבאים:
width
(מספר) – הרוחב של נגן הווידאו. ערך ברירת המחדל הוא640
.height
(מספר) – הגובה של נגן הווידאו. ערך ברירת המחדל הוא390
.videoId
(מחרוזת) – מזהה הווידאו ב-YouTube שמזהה את הסרטון שהנגן יטען.playerVars
(אובייקט) – מאפייני האובייקט מזהים פרמטרים של הנגן שניתן להשתמש בהם כדי להתאים אישית את הנגן.events
(אובייקט) – מאפייני האובייקט מזהים את האירועים שה-API מפעיל ואת הפונקציות (פונקציות event 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
והנגן, שמצוינים בכתובת ה-URL של src
. כאמצעי אבטחה נוסף, צריך לכלול גם את הפרמטר origin
בכתובת ה-URL, ולציין את סכימת כתובת ה-URL (http://
או https://
) ואת הדומיין המלא של הדף המארח כערך הפרמטר. origin
הוא אופציונלי, אבל הוא מספק הגנה מפני JavaScript זדוני של צד שלישי שהוחדר לדף שלך והשתלטות על נגן YouTube שלך.
בקטע דוגמאות מוצגות גם כמה דוגמאות לבניית אובייקטים של נגן וידאו.
פעולות
כדי לקרוא לשיטות ה-API של הנגן, קודם צריך לקבל הפניה לאובייקט הנגן שרוצים לשלוט בו. כדי לקבל את קובץ העזר, צריך ליצור אובייקט YT.Player
כפי שמתואר בקטעים תחילת העבודה וטעינת נגן וידאו במסמך הזה.
פונקציות
פונקציות הוספה לתור
פונקציות התור מאפשרות לכם לטעון ולהפעיל סרטון, פלייליסט או רשימה אחרת של סרטונים. אם אתם משתמשים בתחביר האובייקטים שמתואר בהמשך כדי להפעיל את הפונקציות האלה, תוכלו גם להוסיף לרשימה 'הבאים בתור' או לטעון רשימה של סרטונים שהועלו על ידי משתמש.
ה-API תומך בשני תחבירים שונים לקריאה לפונקציות התור.
-
תחביר הארגומנטים מחייב שהארגומנטים של הפונקציות יהיו רשומים בסדר שנקבע מראש.
-
תחביר האובייקטים מאפשר להעביר אובייקט כפרמטר יחיד ולהגדיר מאפייני אובייקט לארגומנטים של פונקציה שרוצים להגדיר. בנוסף, ה-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 שיופעל. ב-YouTube Data API, המאפיין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 שיופעל. ב-YouTube Data API, המאפיין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
מאפשרות לטעון ולהפעיל פלייליסט. אם משתמשים בתחביר של אובייקטים כדי להפעיל את הפונקציות האלה, אפשר גם להוסיף לרשימת 'הבאים בתור' (או לטעון) רשימת סרטונים שהועלו על ידי משתמש.
מאחר שהפונקציות פועלות באופן שונה בהתאם לאופן ההפעלה שלהן (באמצעות תחביר הארגומנט או תחביר של האובייקט), שתי שיטות הקריאות מתועדות בהמשך.
cuePlaylist
-
-
תחביר הארגומנט
player.cuePlaylist(playlist:String|Array, index:Number, startSeconds:Number):Void
מוסיף את הפלייליסט שצוין לתור. כשהפלייליסט מאושר ומוכן להפעלה, הנגן ישדר אירוע שלvideo cued
(5
).-
הפרמטר
playlist
הנדרש מציין מערך של מזהי וידאו ב-YouTube. ב-YouTube Data API, המאפייןid
של המשאבvideo
מזהה את מזהה הסרטון. -
הפרמטר האופציונלי
index
מציין את האינדקס של הסרטון הראשון בפלייליסט שיופעל. הפרמטר משתמש באינדקס מבוסס אפס. ערך הפרמטר שמוגדר כברירת מחדל הוא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
. החל מ-15 בנובמבר 2020 לא תהיה יותר תמיכה בערך שהוצא משימוש,search
. ערך ברירת המחדל הואplaylist
. -
המאפיין הנדרש
list
מכיל מפתח שמזהה את הרשימה הספציפית של הסרטונים שמערכת YouTube צריכה להחזיר.- אם ערך המאפיין
listType
הואplaylist
, המאפייןlist
מציין את מזהה הפלייליסט או מערך של מזהי וידאו. ב-YouTube Data API, המאפייןid
של המשאבplaylist
מזהה את מזהה הפלייליסט, והמאפייןid
של המשאבvideo
מציין מזהה וידאו. - אם ערך המאפיין
listType
הואuser_uploads
, המאפייןlist
מזהה את המשתמש שהסרטונים שהועלו יוחזרו. - אם ערך המאפיין
listType
הואsearch
, המאפייןlist
מציין את שאילתת החיפוש. הערה: החל מ-15 בנובמבר 2020 , הפונקציונליות הזו הוצאה משימוש והתמיכה בה תופסק.
- אם ערך המאפיין
-
המאפיין האופציונלי
index
מציין את האינדקס של סרטון הווידאו הראשון ברשימה שיופעל. הפרמטר משתמש באינדקס מבוסס אפס, וערך ברירת המחדל של הפרמטר הוא0
, כך שהתנהגות ברירת המחדל היא טעינה והפעלה של הסרטון הראשון ברשימה. -
המאפיין האופציונלי
startSeconds
מקבל מספר צף/מספר שלם ומציין את הזמן שבו סרטון הווידאו הראשון ברשימה יתחיל לפעול כאשר תופעל הפונקציהplayVideo()
. אם מזינים ערך שלstartSeconds
ואז מפעילים אתseekTo()
, הנגן יופעל מהתקופה שצוינה בקריאה ל-seekTo()
. אם מסמנים רשימה ואז מפעילים את הפונקציהplayVideoAt()
, הנגן יתחיל לפעול בתחילת הסרטון שצוין.
-
-
loadPlaylist
-
-
תחביר הארגומנט
player.loadPlaylist(playlist:String|Array, index:Number, startSeconds:Number):Void
הפונקציה הזו טוענת את הפלייליסט שצוין ומפעילה אותו.-
הפרמטר
playlist
הנדרש מציין מערך של מזהי וידאו ב-YouTube. ב-YouTube Data API, המאפייןid
של המשאבvideo
מציין מזהה וידאו. -
הפרמטר האופציונלי
index
מציין את האינדקס של הסרטון הראשון בפלייליסט שיופעל. הפרמטר משתמש באינדקס מבוסס אפס. ערך הפרמטר שמוגדר כברירת מחדל הוא0
, כך שהתנהגות ברירת המחדל היא טעינה והפעלה של הסרטון הראשון בפלייליסט. -
הפרמטר
startSeconds
האופציונלי מקבל מספר צף/מספר שלם ומציין את הזמן שבו הסרטון הראשון בפלייליסט צריך להתחיל לפעול.
-
-
תחביר של אובייקטים
player.loadPlaylist({list:String, listType:String, index:Number, startSeconds:Number}):Void
הפונקציה הזו טוענת את הרשימה שצוינה ומפעילה אותה. הרשימה יכולה להיות פלייליסט או פיד סרטונים שהועלה על ידי משתמש. החל מ-15 בנובמבר 2020 , האפשרות לטעון רשימה של תוצאות חיפוש הוצאה משימוש והתמיכה בה תופסק.-
המאפיין האופציונלי
listType
מציין את הסוג של פיד התוצאות שמאחזר. הערכים החוקיים הםplaylist
ו-user_uploads
. החל מ-15 בנובמבר 2020 לא תהיה יותר תמיכה בערך שהוצא משימוש,search
. ערך ברירת המחדל הואplaylist
. -
המאפיין הנדרש
list
מכיל מפתח שמזהה את הרשימה הספציפית של הסרטונים שמערכת YouTube צריכה להחזיר.- אם ערך המאפיין
listType
הואplaylist
, אז המאפייןlist
מציין מזהה פלייליסט או מערך של מזהי וידאו. ב-YouTube Data API, המאפייןid
של המשאבplaylist
מציין את מזהה הפלייליסט, והמאפייןid
של המשאבvideo
מציין מזהה וידאו. - אם ערך המאפיין
listType
הואuser_uploads
, המאפייןlist
מזהה את המשתמש שהסרטונים שהועלו יוחזרו. - אם ערך המאפיין
listType
הואsearch
, המאפייןlist
מציין את שאילתת החיפוש. הערה: החל מ-15 בנובמבר 2020 , הפונקציונליות הזו הוצאה משימוש והתמיכה בה תופסק.
- אם ערך המאפיין
-
המאפיין האופציונלי
index
מציין את האינדקס של סרטון הווידאו הראשון ברשימה שיופעל. הפרמטר משתמש באינדקס מבוסס אפס, וערך ברירת המחדל של הפרמטר הוא0
, כך שהתנהגות ברירת המחדל היא טעינה והפעלה של הסרטון הראשון ברשימה. -
המאפיין האופציונלי
startSeconds
מקבל מספר צף/מספר שלם ומציין את הזמן שבו הסרטון הראשון ברשימה צריך להתחיל לפעול.
-
-
פקדי הפעלה והגדרות הנגן
הפעלת סרטון
player.playVideo():Void
- הפעלה של הסרטון שנאמר/נטען עכשיו. המצב הסופי של הנגן לאחר הפעלת הפונקציה הזו יהיה
playing
(1).
הערה: הפעלה נספרת רק בספירת הצפיות הרשמית של הסרטון, אם היא מופעלת באמצעות לחצן הפעלה מקומי בנגן.
player.pauseVideo():Void
- משהה את הסרטון שפועל כעת. מצב השחקן האחרון אחרי הפעלת הפונקציה הזו יהיה
paused
(2
), אלא אם הנגן נמצא במצבended
(0
) כשהפונקציה מופעלת. במקרה כזה מצב הנגן לא ישתנה.
player.stopVideo():Void
- מפסיק ומבטל את הטעינה של הסרטון הנוכחי. יש לשמור את הפונקציה הזו למצבים נדירים שבהם ידוע לכם שהמשתמש לא יצפה בסרטונים נוספים בנגן. אם הכוונה היא להשהות את הסרטון, צריך פשוט להפעיל את הפונקציה
pauseVideo
. כדי להחליף את הסרטון שמופעל בנגן, אפשר להפעיל את אחת מהפונקציות האלה בלי להפעיל קודם אתstopVideo
.
חשוב: בשונה מהפונקציהpauseVideo
, שמשאירה את השחקן במצבpaused
(2
), פונקצייתstopVideo
יכולה להעביר את השחקן למצב שהוא לא פועל, כולל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 מעלות, או אם הפונקציה מופעלת ממכשיר שאינו נתמך, הפונקציה מחזירה אובייקט ריק.
- במכשירים ניידים נתמכים, אם המאפיין
enableOrientationSensor
מוגדר לערךtrue
, הפונקציה הזו מחזירה אובייקט שבו המאפייןfov
מכיל את הערך הנכון ושאר המאפיינים מוגדרים כ-0
.
תכונות yaw
מספר בטווח [0, 360) שמייצג את הזווית האופקית של התצוגה במעלות, שמשקף את המידה שבה המשתמש מסובב את התצוגה שמאלה או ימינה. המיקום הנייטרלי, מול מרכז הסרטון בתצוגה המלבנית שלו, מייצג את הערך 0, והערך הזה גדל ככל שהצופה פונה שמאלה. pitch
מספר בטווח [ -90, 90] שמייצג את הזווית האנכית של התצוגה במעלות, שמשקף את המידה שבה המשתמש מתאים את התצוגה כדי להסתכל למעלה או למטה. המיקום הנייטרלי, מול מרכז הסרטון בהקרנה הכדורית, מייצג את הערך 0, והערך הזה גדל ככל שהצופה מביט קדימה. roll
מספר בטווח [ -180, 180] שמייצג את זווית הסיבוב של התצוגה במעלות או בכיוון השעון. המיקום הנייטרלי, שבו הציר האופקי בהיטל הכדורי שווה לציר האופקי של התצוגה, מייצג את הערך 0. הערך גדל ככל שהתצוגה מסתובבת בכיוון השעון והוא קטן ככל שהתצוגה מסתובבת נגד כיוון השעון.
חשוב לדעת שהנגן המוטמע לא מציג ממשק משתמש לשינוי הסיבוב של התצוגה. ניתן להתאים את הסכום בכל אחת מהדרכים הבלעדיות הבאות:- יש להשתמש בחיישן הכיוון בדפדפן לנייד כדי לבצע היפוך של התצוגה. אם חיישן הכיוון מופעל, הפונקציה
getSphericalProperties
תמיד מחזירה את0
כערך של המאפייןroll
. - אם חיישן הכיוון מושבת, צריך להגדיר את הרוגלה לערך שאינו אפס באמצעות ה-API הזה.
fov
מספר בטווח [30, 120] שמייצג את שדה הראייה של התצוגה במעלות, כפי שנמדד לאורך הקצה הארוך יותר של אזור התצוגה. הקצה הקצר יותר מותאם באופן אוטומטי ליחס הגובה-רוחב של התצוגה.
ערך ברירת המחדל הוא 100 מעלות. הקטנת הערך דומה להגדלת התצוגה של תוכן הווידאו, והגדלת הערך דומה להקטנת התצוגה. ניתן להתאים ערך זה באמצעות ממשק ה-API או באמצעות גלגל העכבר כאשר הסרטון במצב מסך מלא.
player.setSphericalProperties(properties:Object):Void
- מגדיר את כיוון הווידאו להפעלת סרטון ב-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
משמש לזיהוי הסרטון הראשון ברשימה. אם בחרתם בסדר אקראי את הפלייליסט, הפונקציה הזו תפעיל את הסרטון במיקום שצוין ברשימת ההשמעה האקראית.
-
שינוי עוצמת הקול של הנגן
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
).
הגדרת התנהגות ההפעלה של פלייליסטים
player.setLoop(loopPlaylists:Boolean):Void
-
הפונקציה הזו מציינת אם נגן הווידאו צריך להפעיל פלייליסט באופן רציף או אם ההפעלה שלו תופסק אחרי שהסרטון האחרון בפלייליסט מסתיים. התנהגות ברירת המחדל היא שפלייליסטים אינם מוצגים בלופ.
ההגדרה הזו תישאר בתוקף גם אם תטען פלייליסט אחר או מסמנת אותו. המשמעות היא שאם תטען פלייליסט, תפעיל את הפונקציה
setLoop
עם הערךtrue
ולאחר מכן תטען פלייליסט נוסף, גם הפלייליסט השני יושמע בלופ.הפרמטר
loopPlaylists
הנדרש מזהה את התנהגות הלולאה.-
אם ערך הפרמטר הוא
true
, נגן הווידאו יפעיל פלייליסטים. אחרי הפעלת הסרטון האחרון בפלייליסט, נגן הווידאו יחזור לתחילת הפלייליסט ויפעיל אותו שוב. -
אם ערך הפרמטר הוא
false
, ההפעלות יסתיימו אחרי שנגן הווידאו יפעיל את הסרטון האחרון בפלייליסט.
-
player.setShuffle(shufflePlaylist:Boolean):Void
-
הפונקציה הזו מציינת אם יש לסדר את הסרטונים בפלייליסט בצורה אקראית כך שהם יופעלו בסדר שונה מזה שהוגדר על ידי יוצר הפלייליסט. אם תפעילו פלייליסט אקראי אחרי שהוא כבר התחיל, הרשימה תסדר מחדש בזמן שהסרטון מופעל. לאחר מכן, הסרטון הבא שיופעל ייבחר לפי הרשימה שסדרת מחדש.
ההגדרה הזו לא תישמר אם תטען פלייליסט אחר או סימנתם פלייליסט אחר. כלומר, אם תטען פלייליסט, תפעילו את הפונקציה
setShuffle
ולאחר מכן תטען פלייליסט נוסף, הפלייליסט השני לא יושמע בסדר אקראי.הפרמטר
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
- מחזיר את כתובת האתר YouTube.com של הסרטון שנטען/פועל כרגע.
player.getVideoEmbedCode():String
- מחזיר את קוד ההטמעה של הסרטון שנטען/מופעל עכשיו.
המערכת מאחזרת את פרטי הפלייליסט
player.getPlaylist():Array
- הפונקציה מחזירה מערך של מזהי הווידאו בפלייליסט כפי שהם מסודרים נכון לעכשיו. כברירת מחדל, הפונקציה הזו תחזיר את מזהי הווידאו לפי הסדר שהבעלים של הפלייליסט הגדירו. לעומת זאת, אם הפעלתם את הפונקציה
setShuffle
כדי להשמיע את הסדר של הפלייליסט באופן אקראי, הערך שמוחזר בפונקציהgetPlaylist()
ישקף את הסדר שבו האירועים בסדר אקראי.
player.getPlaylistIndex():Number
- הפונקציה מחזירה את האינדקס של סרטון הפלייליסט שמופעל כרגע.
-
אם לא סימנתם את הפלייליסט בסדר אקראי, הערך המוחזר יציין את המיקום שבו יוצר הפלייליסט הציב את הסרטון. הערך המוחזר משתמש באינדקס שמבוסס על אפס, ולכן הערך
0
משמש לזיהוי הסרטון הראשון בפלייליסט. -
אם להשמיע את הפלייליסט בסדר אקראי, הערך המוחזר יקבע את הסדר של הסרטון בפלייליסט לאחר ההשמעה האקראית.
-
הוספה או הסרה של event 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 מפעיל אירועים כדי להודיע לאפליקציה על שינויים בנגן המוטמע. כפי שצוין בקטע הקודם, ניתן להירשם לאירועים על ידי הוספת event 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 מעביר אל פונקציית event 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 מעביר לפונקציית event listener יהיה מחרוזת שמזהה את איכות ההפעלה החדשה. הערכים האפשריים הם:small
medium
large
hd720
hd1080
highres
onPlaybackRateChange
- האירוע הזה מופעל בכל פעם שקצב ההפעלה של הסרטון משתנה. לדוגמה, אם מפעילים את הפונקציה
setPlaybackRate(suggestedRate)
, האירוע הזה יופעל אם קצב ההפעלה ישתנה בפועל. האפליקציה צריכה להגיב לאירוע ולא להניח שקצב ההפעלה ישתנה באופן אוטומטי בעת ההפעלה של הפונקציהsetPlaybackRate(suggestedRate)
. באופן דומה, לא אמורה להיות הנחה בקוד שקצב ההפעלה של סרטונים ישתנה רק כתוצאה מקריאה מפורשת ל-setPlaybackRate
.
ערך המאפייןdata
של אובייקט האירוע שה-API מעביר לפונקציית event listener יהיה מספר שמזהה את קצב ההפעלה החדש. השיטהgetAvailablePlaybackRates
מחזירה רשימה של שיעורי ההפעלה התקינים של הסרטון שמסומן כרגע או מופעל עכשיו.
onError
- האירוע הזה מופעל אם מתרחשת שגיאה בנגן.
ה-API יעביר אובייקט
event
לפונקציית 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:
מודול אפשרות התיאור כתוביות fontSize האפשרות הזו משנה את גודל הגופן של הכתוביות שמוצגות בנגן.
הערכים החוקיים הם-1
,0
,1
,2
ו-3
. גודל ברירת המחדל הוא0
, והגודל הקטן ביותר הוא-1
. הגדרת אפשרות זו למספר שלם מתחת ל--1
תגרום להצגת גודל הכתוביות הקטן ביותר, בעוד הגדרת אפשרות זו למספר שלם מעל3
תגרום להצגת גודל הכתוביות הגדול ביותר.כתוביות reload אפשרות זו טוענת מחדש את נתוני הכתוביות עבור הסרטון המוצג. אם מאחזרים את ערך האפשרות, הערך יהיה null
. יש להגדיר את הערך כ-true
כדי לטעון מחדש את נתוני הכתוביות.
onAutoplayBlocked
- האירוע הזה מופעל בכל פעם שהדפדפן חוסם תכונות של הפעלה אוטומטית או הפעלת סקריפטים,
שנקראות יחד "הפעלה אוטומטית". הפעולות כוללות ניסיון הפעלה באמצעות אחד מממשקי ה-API הבאים של הנגן:
- פרמטר אחד (
autoplay
) - פונקציית
loadPlaylist
- פונקציית
loadVideoById
- פונקציית
loadVideoByUrl
- פונקציית
playVideo
לקבלת פרטים מלאים, ניתן לעיין במדיניות הספציפית לדפדפן (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) ובמדריך להפעלה אוטומטית של Mozilla. - פרמטר אחד (
דוגמאות
המערכת יוצרת YT.Player
אובייקטים
-
דוגמה 1: שימוש ב-API עם רכיב <iframe> קיים
בדוגמה הזו, רכיב
<iframe>
בדף כבר מגדיר את הנגן שבו ייעשה שימוש ב-API. חשוב לשים לב שכתובת ה-URL שלsrc
של הנגן חייבת להגדיר את הפרמטר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 על 720 פיקסלים. לאחר מכן, הפונקציה event 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: בדוגמה הזו המערכת מגדירה את הפרמטרים של הנגן כך שהסרטון יופעל באופן אוטומטי כשהוא נטען, וכדי להסתיר את הפקדים של נגן הווידאו. היא גם מוסיפה פונקציות event 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>
היסטוריית גרסאות
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.