تتيح لك واجهة برمجة تطبيقات مشغّل IFrame تضمين مشغّل فيديو YouTube على موقعك الإلكتروني والتحكم في المشغّل باستخدام JavaScript.
باستخدام وظائف JavaScript لواجهة برمجة التطبيقات، يمكنك وضع الفيديوهات في قائمة انتظار للتشغيل أو تشغيلها أو إيقافها مؤقتًا أو إيقافها أو ضبط مستوى صوت المشغّل أو استرداد معلومات حول الفيديو الذي يتم تشغيله. ويمكنك أيضًا إضافة أدوات معالجة الأحداث التي سيتم تنفيذها استجابةً لأحداث معيّنة خاصة باللاعب، مثل تغيير حالة اللاعب.
يشرح هذا الدليل كيفية استخدام واجهة برمجة تطبيقات IFrame. وتحدِّد الأنواع المختلفة من الأحداث التي يمكن لواجهة برمجة التطبيقات إرسالها وتوضّح كيفية كتابة أدوات معالجة الأحداث للاستجابة لهذه الأحداث. ويوضّح أيضًا وظائف JavaScript المختلفة التي يمكنك طلبها للتحكّم في مشغّل الفيديو، بالإضافة إلى معلَمات المشغّل التي يمكنك استخدامها لتخصيص المشغّل بشكل أكبر.
المتطلّبات
يجب أن يتيح متصفّح المستخدم ميزة postMessage
HTML5. تتيح معظم المتصفحات الحديثة استخدام postMessage
.
يجب أن تحتوي المشغّلات المضمّنة على إطار عرض أبعاده 200 × 200 بكسل على الأقل. إذا كان المشغّل يعرض عناصر التحكّم، يجب أن يكون كبيرًا بما يكفي لعرض عناصر التحكّم بالكامل بدون تقليص إطار العرض إلى ما يقلّ عن الحد الأدنى للحجم. نوصي بأن تكون المشغّلات بنسبة 16:9 بعرض 480 بكسل وبطول 270 بكسل على الأقل.
يجب أيضًا على أي صفحة ويب تستخدم واجهة برمجة تطبيقات IFrame تنفيذ وظيفة JavaScript التالية:
-
onYouTubeIframeAPIReady
– ستستدعي واجهة برمجة التطبيقات هذه الوظيفة عند انتهاء الصفحة من تنزيل JavaScript لواجهة برمجة تطبيقات المشغّل، والتي تمكّنك بعد ذلك من استخدام واجهة برمجة التطبيقات على صفحتك. وبالتالي، قد تنشئ هذه الدالة كائنات المشغّل التي تريد عرضها عند تحميل الصفحة.
البدء
تعمل صفحة نموذج 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. تحدد الدالة الإنشائية لكائن المشغِّل، الموضحة في القسم تحميل مشغّل فيديو، العلامة<div>
من خلالid
لضمان أن واجهة برمجة التطبيقات تضع<iframe>
في المكان الصحيح. وعلى وجه التحديد، ستستبدل واجهة برمجة التطبيقات IFrame العلامة<div>
بالعلامة<iframe>
.يمكنك بدلاً من ذلك وضع العنصر
<iframe>
مباشرةً على الصفحة. ويوضّح القسم تحميل مشغّل فيديو كيفية إجراء ذلك. -
يحمِّل الرمز في هذا القسم رمز JavaScript لواجهة برمجة تطبيقات IFrame Player. يستخدم المثال تعديل DOM لتنزيل رمز واجهة برمجة التطبيقات لضمان استرداد الرمز بشكل غير متزامن. (إنّ السمة
async
للعلامة<script>
، والتي تتيح أيضًا عمليات التنزيل غير المتزامنة، غير متاحة حتى الآن في جميع المتصفحات الحديثة، كما هو موضّح في إجابة Stack Overflow هذه. -
سيتم تنفيذ الدالة
onYouTubeIframeAPIReady
فور تنزيل رمز واجهة برمجة تطبيقات المشغّل. يحدّد هذا الجزء من الرمز المتغيّر العامplayer
الذي يشير إلى مشغّل الفيديو الذي تريد تضمينه، ثم تنشئ الدالة كائن مشغّل الفيديو. -
سيتم تنفيذ الدالة
onPlayerReady
عند تنشيط حدثonReady
. في هذا المثال، تشير الدالة إلى أنّه عندما يكون مشغّل الفيديو جاهزًا، يجب أن يبدأ تشغيله. -
ستستدعي واجهة برمجة التطبيقات الوظيفة
onPlayerStateChange
عندما تتغيّر حالة المشغّل، ما قد يشير إلى أنّ المشغّل قيد التشغيل أو متوقف مؤقتًا أو انتهى، وما إلى ذلك. وتشير الدالة إلى أنه عندما تكون حالة المشغّل1
(قيد التشغيل)، يجب أن يتم تشغيل المشغّل لمدة ست ثوانٍ، ثم يستدعي وظيفةstopVideo
لإيقاف الفيديو.
تحميل مشغّل فيديو
بعد تحميل رمز JavaScript لواجهة برمجة التطبيقات، ستستدعي واجهة برمجة التطبيقات الوظيفة 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 حيث ستُدرج واجهة برمجة التطبيقات العلامة<iframe>
التي تحتوي على المشغّل.ستستبدل واجهة برمجة تطبيقات IFrame العنصر المحدد بالعنصر
<iframe>
الذي يشتمل على المشغّل. قد يؤثر ذلك في تنسيق صفحتك إذا كان العنصر الذي يتم استبداله له نمط عرض مختلف عن عنصر<iframe>
المدرج. يتم عرض<iframe>
تلقائيًا كعنصرinline-block
. - المعلمة الثانية عبارة عن كائن يحدد خيارات المشغّل. يحتوي الكائن على السمات التالية:
width
(رقم) – عرض مشغّل الفيديو القيمة التلقائية هي640
.height
(رقم) – ارتفاع مشغّل الفيديو القيمة التلقائية هي390
.videoId
(سلسلة) – معرّف فيديو YouTube الذي يحدد الفيديو الذي سيحمّله المشغّل.playerVars
(كائن) – تحدد خصائص الكائن معلَمات المشغّل التي يمكن استخدامها لتخصيص المشغّل.events
(الكائن) – تحدد خصائص العنصر الأحداث التي تنشطها واجهة برمجة التطبيقات والوظائف (أدوات معالجة الأحداث) التي ستستدعيها واجهة برمجة التطبيقات عند وقوع هذه الأحداث. في المثال، تشير الدالة الإنشائية إلى أنه سيتم تنفيذ الدالةonPlayerReady
عند تنشيط الحدثonReady
وأنّ الدالةonPlayerStateChange
سيتم تنفيذها عند تنشيط حدثonStateChange
.
كما هو مذكور في قسم البدء، يمكنك إنشاء علامة <iframe>
بنفسك بدلاً من كتابة عنصر <div>
فارغ على صفحتك ليتم بعد ذلك استبدال رمز JavaScript لواجهة برمجة تطبيقات المشغّل بعنصر <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.
يعرض قسم الأمثلة أيضًا أمثلة أخرى لإنشاء كائنات مشغّل الفيديو.
العمليات
لاستدعاء طرق واجهة برمجة تطبيقات المشغّل، يجب أولاً الحصول على مرجع لكائن المشغّل الذي تريد التحكّم فيه. ويمكنك الحصول على المرجع من خلال إنشاء عنصر YT.Player
كما هو موضّح في القسمين البدء وتحميل مشغّل فيديو من هذا المستند.
الدوال
دوال الإضافة في قائمة المحتوى التالي
تتيح لك وظائف الإضافة إلى قائمة المحتوى التالي تحميل فيديو أو قائمة تشغيل أو قائمة أخرى من الفيديوهات وتشغيلها. إذا كنت تستخدم بنية الكائن الموضحة أدناه لاستدعاء هذه الدوال، يمكنك أيضًا وضع قائمة انتظار أو تحميل قائمة بالفيديوهات التي حمّلها المستخدم.
تدعم واجهة برمجة التطبيقات بناءي جملة مختلفين لاستدعاء دوال قائمة الانتظار.
-
يتطلب بناء جملة الوسيطة أن يتم إدراج وسيطات الدوال بترتيب محدد.
-
تتيح لك بنية الكائن تمرير كائن كمعلمة واحدة وتحديد خصائص الكائن لوسيطات الدالة التي تريد تعيينها. وبالإضافة إلى ذلك، قد توفّر واجهة برمجة التطبيقات وظائف إضافية لا تتوافق معها بنية الوسيطة.
على سبيل المثال، يمكن استدعاء الدالة 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
. لن تتوفّر القيمة المتوقّفة نهائيًا،search
، اعتبارًا من15 تشرين الثاني (نوفمبر) 2020 . القيمة التلقائية هي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
. لن تتوفّر القيمة المتوقّفة نهائيًا،search
، اعتبارًا من15 تشرين الثاني (نوفمبر) 2020 . القيمة التلقائية هي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 درجة مشوهة ولا تتوفّر طريقة متاحة لتغيير منظور العرض على الإطلاق، بما في ذلك من خلال واجهة برمجة التطبيقات أو استخدام أدوات استشعار الاتجاه أو الاستجابة لإجراءات اللمس/السحب على شاشة الجهاز.
player.getSphericalProperties():Object
- استرداد الخصائص التي تصف وجهة نظر المُشاهد الحالية أو طريقة المشاهدة الحالية لتشغيل فيديو بالإضافة إلى ذلك:
- وتتم تعبئة هذا العنصر للفيديوهات بنطاق 360 درجة فقط، والتي تُسمّى أيضًا الفيديوهات بنطاق كروي.
- إذا لم يكن الفيديو الحالي فيديو بنطاق 360 درجة أو إذا تم استدعاء الوظيفة من جهاز غير متوافق، تعرِض الدالة عنصرًا فارغًا.
- على الأجهزة الجوّالة المتوافقة، إذا تم ضبط السمة
enableOrientationSensor
علىtrue
، تعرض هذه الدالة عنصرًا حيث تحتوي السمةfov
على القيمة الصحيحة ويتم ضبط السمات الأخرى على0
.
أماكن إقامة yaw
رقم في النطاق [0، 360) يمثل الزاوية الأفقية للعرض بالدرجات، والتي تعكس مدى تدوير المستخدم للعرض باتجاه اليسار أو اليمين أكثر. يمثل الموضع المحايد، المواجه لمركز الفيديو بإسقاطه المتساوي المستطيلات، 0 درجة وتزداد هذه القيمة كلما اتّجه المشاهد إلى اليسار. pitch
رقم في النطاق [-90، 90] يمثل الزاوية الرأسية للعرض بالدرجات، ويعكس مدى تعديل المستخدم للعرض لينظر لأعلى أو لأسفل. يمثل الموضع المحايد، المواجه لمركز الفيديو بإسقاطه المتساوي المستطيلات، 0 درجة وتزداد هذه القيمة عندما ينظر المشاهد إلى الأعلى. roll
رقم في النطاق [-180، 180] يمثل زاوية الدوران في اتجاه عقارب الساعة أو عكس اتجاه عقارب الساعة للعرض بالدرجات. يمثل الموضع المحايد 0 درجة، مع تدوير المحور الأفقي في الإسقاط المتساوي المستطيلات للمحور الأفقي للعرض. وتزيد القيمة كلما دورت العرض في اتجاه عقارب الساعة وتنخفض مع تدوير العرض عكس اتجاه عقارب الساعة.
تجدر الإشارة إلى أنّ المشغّل المضمّن لا يقدّم واجهة مستخدم لضبط قائمة التشغيل في قسم العرض. يمكن تعديل قائمة التشغيل باستخدام إحدى الطريقتَين التاليتَين التبادليتَين:- استخدم أداة استشعار الاتجاه في متصفح الجوال لتوفير العرض. إذا تم تفعيل أداة استشعار الاتجاه، تعرض الدالة
getSphericalProperties
دائمًا القيمة0
كقيمة للسمةroll
. - إذا تم إيقاف أداة استشعار الاتجاه، اضبط اللفة على قيمة غير صفرية باستخدام واجهة برمجة التطبيقات هذه.
fov
رقم في النطاق [30، 120] يمثل مجال رؤية العرض بالدرجات كما يتم قياسه على طول الحافة الأطول لإطار العرض. ويتم ضبط الحافة الأقصر تلقائيًا لتصبح متناسبة مع نسبة العرض إلى الارتفاع للعرض.
القيمة التلقائية هي 100 درجة. إنّ تقليل القيمة يشبه تكبير محتوى الفيديو، وتشبه زيادة القيمة ميزة التصغير. يمكن تعديل هذه القيمة إما باستخدام واجهة برمجة التطبيقات أو باستخدام عجلة الماوس عندما يكون الفيديو في وضع ملء الشاشة.
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
من خلال واجهة برمجة التطبيقات، علمًا بأنّ هذه الواجهة هي في الواقع الطريقة الوحيدة لتغيير سمةfov
على جهاز جوّال. وهذا هو الخيار التلقائي. - وعندما تكون القيمة
false
، لن تؤثر حركة الجهاز في تجربة العرض بزاوية 360 درجة، ويجب ضبط جميع الخصائصyaw
وpitch
وroll
وfov
من خلال واجهة برمجة التطبيقات.
الأجهزة الجوّالة غير المتوافقة
لن يكون لقيمة السمة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
- عرض عنوان URL لموقع YouTube.com للفيديو الذي تم تحميله/تشغيله حاليًا.
player.getVideoEmbedCode():String
- عرض رمز التضمين للفيديو الذي يتم تحميله/تشغيله حاليًا.
استرداد معلومات قائمة التشغيل
player.getPlaylist():Array
- تعرض هذه الدالة صفيفًا من معرّفات الفيديوهات في قائمة التشغيل كما هي مرتبة حاليًا. بشكل افتراضي، ستعرض هذه الدالة معرّفات الفيديو بالترتيب الذي حدده مالك قائمة التشغيل. مع ذلك، إذا طلبت من الدالة
setShuffle
ترتيب ترتيب قائمة التشغيل عشوائيًا، ستعكس القيمة المعروضة في الدالةgetPlaylist()
الترتيب العشوائي.
player.getPlaylistIndex():Number
- تعرض هذه الدالة فهرس فيديو قائمة التشغيل الذي يتم تشغيله حاليًا.
-
إذا لم ترتّب قائمة التشغيل عشوائيًا، ستحدّد القيمة المعروضة الموضع الذي وضع فيه منشئ قائمة التشغيل الفيديو. تستخدم القيمة المعروضة فهرسًا يستند إلى صفر، وبالتالي فإن القيمة
0
تحدد أول فيديو في قائمة التشغيل. -
إذا شغّلت قائمة التشغيل بترتيب عشوائي، فستحدد القيمة المعروضة ترتيب الفيديو ضمن قائمة التشغيل التي تم ترتيبها بشكل عشوائي.
-
إضافة أداة معالجة حدث أو إزالتها
player.addEventListener(event:String, listener:String):Void
- إضافة دالة استماع إلى الإصدار
event
المحدَّد يحدّد قسم الأحداث أدناه الأحداث المختلفة التي قد ينشطها المشغّل. المستمع هو سلسلة تحدِّد الدالة التي سيتم تنفيذها عند تنشيط الحدث المحدّد.
player.removeEventListener(event:String, listener:String):Void
- يؤدي هذا الإجراء إلى إزالة دالة استماع لـ
event
المحدّدة.listener
هو سلسلة تحدِّد الدالة التي لن يتم تنفيذها بعد الآن عند تنشيط الحدث المحدّد.
الوصول إلى عُقد DOM وتعديلها
player.getIframe():Object
- تعرض هذه الطريقة عقدة DOM لـ
<iframe>
المضمَّنة.
player.destroy():Void
- لإزالة
<iframe>
التي تتضمّن المشغّل.
فعاليات
تنشط واجهة برمجة التطبيقات الأحداث لإشعار التطبيق بحدوث التغييرات في المشغّل المضمَّن. كما هو موضّح في القسم السابق، يمكنك الاشتراك في الأحداث من خلال إضافة أداة معالجة حدث عند إنشاء الكائن YT.Player
، ويمكنك أيضًا استخدام الدالة addEventListener
.
ستمرر واجهة برمجة التطبيقات كائن حدث باعتباره الوسيطة الوحيدة لكل دالة من هذه الدوال. يحتوي كائن الحدث على السمات التالية:
- وتحدّد سمة
target
للحدث مشغّل الفيديو المقابل للحدث. - وتحدّد الخاصية
data
للحدث قيمة ذات صلة بالحدث. وتجدر الإشارة إلى أنّ الحدثَينonReady
وonAutoplayBlocked
لا يحدّدان السمةdata
.
تحدّد القائمة التالية الأحداث التي تنشطها واجهة برمجة التطبيقات:
onReady
- يتم تنشيط هذا الحدث عندما ينتهي اللاعب من التحميل ويكون جاهزًا لبدء تلقّي طلبات البيانات من واجهة برمجة التطبيقات. يجب أن ينفِّذ تطبيقك هذه الوظيفة إذا كنت تريد تنفيذ عمليات معيّنة تلقائيًا، مثل تشغيل الفيديو أو عرض معلومات عن الفيديو عندما يصبح المشغّل جاهزًا.
يعرض المثال أدناه نموذجًا لدالة للتعامل مع هذا الحدث. يحتوي كائن الحدث الذي تمرِّره واجهة برمجة التطبيقات إلى الدالة على السمة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
لكائن الحدث الذي تمرِّره واجهة برمجة التطبيقات إلى وظيفة أداة معالجة الحدث عددًا صحيحًا يتوافق مع حالة المشغّل الجديدة. القيم المتاحة هي:-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
لكائن الحدث الذي تمرِّره واجهة برمجة التطبيقات إلى وظيفة استماع الحدث عبارة عن سلسلة تحدِّد جودة التشغيل الجديدة. القيم المتاحة هي:small
medium
large
hd720
hd1080
highres
onPlaybackRateChange
- يتم تنشيط هذا الحدث كلما تغيّر معدّل تشغيل الفيديو. على سبيل المثال، إذا استدعيت الدالة
setPlaybackRate(suggestedRate)
، سيتم تنشيط هذا الحدث إذا تغيّر معدّل التشغيل فعليًا. يجب أن يستجيب التطبيق للحدث، ويجب ألا يفترض أن معدل التشغيل سيتغير تلقائيًا عند استدعاء الدالةsetPlaybackRate(suggestedRate)
. وبالمثل، يجب ألا يفترض الرمز أن معدل تشغيل الفيديو سيتغير فقط نتيجة لاستدعاء صريح إلىsetPlaybackRate
.
ستكون قيمة السمةdata
لكائن الحدث الذي تمرِّره واجهة برمجة التطبيقات إلى وظيفة استماع الحدث رقمًا يُحدِّد معدل التشغيل الجديد. تعرض الطريقةgetAvailablePlaybackRates
قائمة بمعدلات التشغيل الصالحة للفيديو الذي يتم تشغيله أو الذي يتم تشغيله حاليًا.
onError
- يتم تنشيط هذا الحدث في حال حدوث خطأ في المشغّل.
ستمرِّر واجهة برمجة التطبيقات العنصر
event
إلى دالة أداة معالجة الحدث. ستحدِّد السمةdata
في ذلك الكائن عددًا صحيحًا يحدّد نوع الخطأ الذي حدث. القيم المتاحة هي:2
– يحتوي الطلب على قيمة معلمة غير صالحة. على سبيل المثال، يحدث هذا الخطأ إذا حددت معرّف فيديو لا يحتوي على 11 حرفًا، أو إذا كان معرّف الفيديو يحتوي على أحرف غير صالحة، مثل علامات التعجب أو العلامات النجمية.5
– لا يمكن تشغيل المحتوى المطلوب في مشغّل HTML5 أو حدث خطأ آخر متعلق بمشغّل HTML5.100
– لم يتم العثور على الفيديو المطلوب. يحدث هذا الخطأ عند إزالة فيديو (لأي سبب) أو عند وضع علامة "خاص" عليه.101
– لا يسمح مالك الفيديو المطلوب بتشغيله في المشغّلات المضمّنة.150
– هذا الخطأ هو نفسه الخطأ101
. إنّه مجرد خطأ101
متخفي.
onApiChange
- يتم تنشيط هذا الحدث للإشارة إلى أنّ المشغّل قد حمّل (أو ألغى تحميل) وحدة تتضمّن طُرقًا مكشوفة من واجهة برمجة التطبيقات. يمكن لتطبيقك رصد هذا الحدث ثم استطلاع رأي المشغّل لتحديد الخيارات المعروضة للوحدة التي تم تحميلها مؤخرًا. ويمكن للتطبيق بعد ذلك استرداد الإعدادات الحالية لهذه الخيارات أو تحديثها.
يسترد الأمر التالي مصفوفة من أسماء الوحدات التي يمكنك ضبط خيارات المشغّل لها:
player.getOptions();
في الوقت الحالي، الوحدة الوحيدة التي يمكنك ضبط خيارات لها هي وحدةcaptions
التي تعالج الترجمة والشرح في المشغّل. عند استلام حدثonApiChange
، يمكن لتطبيقك استخدام الأمر التالي لتحديد الخيارات التي يمكن ضبطها لوحدةcaptions
:
player.getOptions('captions');
من خلال استطلاع رأي المشغِّل باستخدام هذا الأمر، يمكنك التأكد من إمكانية الوصول إلى الخيارات التي تريد الوصول إليها. تعمل الأوامر التالية على استرداد خيارات الوحدات وتعديلها:
Retrieving an option: player.getOption(module, option); Setting an option player.setOption(module, option, value);
يعرض الجدول أدناه الخيارات المتوافقة مع واجهة برمجة التطبيقات:
الوحدة Option الوصف ترجمة وشرح fontSize يضبط هذا الخيار حجم خط الترجمة المعروضة في المشغّل.
القيم الصالحة هي-1
و0
و1
و2
و3
. الحجم التلقائي هو0
، وأصغر حجم هو-1
. عند ضبط هذا الخيار على عدد صحيح أقل من-1
، سيتم عرض أصغر حجم للتسمية التوضيحية، في حين سيؤدي ضبط هذا الخيار على عدد صحيح أعلى من3
إلى عرض أكبر حجم للشرح.ترجمة وشرح إعادة التحميل يؤدي هذا الخيار إلى إعادة تحميل بيانات الترجمة والشرح للفيديو الذي يتم تشغيله. ستكون القيمة null
في حال استرداد قيمة الخيار. اضبط القيمة علىtrue
لإعادة تحميل بيانات الترجمة والشرح.
onAutoplayBlocked
- يتم تنشيط هذا الحدث عندما يحظر المتصفّح ميزات التشغيل التلقائي أو تشغيل الفيديوهات النصية، ويُشار إليها مجتمعةً باسم "التشغيل التلقائي". ويتضمن ذلك محاولة التشغيل باستخدام أي من واجهات برمجة تطبيقات المشغّل التالية:
- مَعلمة
autoplay
- دالة
loadPlaylist
- دالة
loadVideoById
- دالة
loadVideoByUrl
- دالة
playVideo
للحصول على التفاصيل الكاملة، يُرجى الاطّلاع على السياسات الخاصة بالمتصفّح (Apple Safari أو Webkit وGoogle Chrome وMozilla Firefox) ودليل التشغيل التلقائي في Mozilla. - مَعلمة
أمثلة
جارٍ إنشاء كائنات YT.Player
-
المثال 1: استخدام واجهة برمجة التطبيقات مع إطار <iframe> الحالي
في هذا المثال، يحدّد عنصر
<iframe>
على الصفحة المشغّل الذي سيتم استخدام واجهة برمجة التطبيقات معه. يُرجى العِلم أنّ عنوان 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 بكسل. بعد ذلك، تستدعي أداة معالجة الحدث للحدث
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: يحدّد هذا المثال معلَمات المشغّل لتشغيل الفيديو تلقائيًا عند تحميله وإخفاء عناصر التحكّم في مشغّل الفيديو. وتضيف أيضًا أدوات معالجة الأحداث لعدة أحداث تبثّها واجهة برمجة التطبيقات.
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.