YouTube Player API Reference for iframe Embeds

تتيح لك واجهة برمجة التطبيقات IFrame Player API تضمين مشغّل فيديو YouTube على موقعك الإلكتروني والتحكّم في المشغّل باستخدام JavaScript.

باستخدام دوال JavaScript في واجهة برمجة التطبيقات، يمكنك إضافة الفيديوهات إلى "قائمة المحتوى التالي" لتشغيلها، أو تشغيل هذه الفيديوهات أو إيقافها مؤقتًا أو إيقافها، أو ضبط مستوى صوت المشغّل، أو استرداد معلومات عن الفيديو الذي يتم تشغيله. يمكنك أيضًا إضافة مستمعي أحداث سيتم تنفيذهم استجابةً لأحداث معيّنة للمشغّل، مثل تغيير حالة المشغّل.

يوضّح هذا الدليل كيفية استخدام واجهة برمجة التطبيقات IFrame API. ويحدِّد الأنواع المختلفة للأحداث التي يمكن أن ترسلها واجهة برمجة التطبيقات ويوضِّح كيفية كتابة مستمعي الأحداث للردّ على هذه الأحداث. ويوضّح أيضًا تفاصيل وظائف JavaScript المختلفة التي يمكنك استدعاؤها للتحكّم في مشغّل الفيديو، بالإضافة إلى مَعلمات المشغّل التي يمكنك استخدامها لتخصيصه بشكل أكبر.

المتطلبات

يجب أن يكون متصفّح المستخدم متوافقًا مع ميزة postMessage في HTML5. تتوافق معظم المتصفحات الحديثة مع postMessage.

يجب أن يكون لأدوات التشغيل المضمّنة إطار عرض أبعاده 200 × 200 بكسل على الأقل. إذا كان المشغّل يعرض عناصر تحكّم، يجب أن يكون كبيرًا بما يكفي لعرض عناصر التحكّم بالكامل بدون تصغير مساحة العرض إلى ما دون الحدّ الأدنى. ننصحك باستخدام مشغّلات بتنسيق ‎16:9 لا يقلّ عرضها عن 480 بكسل وارتفاعها عن 270 بكسل.

يجب أن تنفِّذ أيضًا أي صفحة ويب تستخدم واجهة برمجة التطبيقات IFrame API وظيفة 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>

تقدّم القائمة التالية مزيدًا من التفاصيل حول العيّنة أعلاه:

  1. تحدِّد العلامة <div> في هذا القسم الموقع على الصفحة الذي ستضع فيه واجهة برمجة التطبيقات IFrame مشغِّل الفيديو. يحدِّد مُنشئ كائن المشغّل، الموضّح في قسم تحميل مشغّل فيديو، علامة <div> من خلال id لضمان وضع واجهة برمجة التطبيقات <iframe> في الموضع الصحيح. على وجه التحديد، ستستبدل واجهة برمجة التطبيقات IFrame علامة <div> بعلامة <iframe>.

    كخيار بديل، يمكنك أيضًا وضع عنصر <iframe> مباشرةً على الصفحة. يوضّح قسم تحميل مشغّل فيديو كيفية إجراء ذلك.

  2. يُحمِّل الرمز البرمجي في هذا القسم رمز JavaScript لواجهة برمجة التطبيقات IFrame Player API. يستخدم المثال تعديل DOM لتنزيل رمز واجهة برمجة التطبيقات لضمان استرداد الرمز بشكل غير متزامن. (لا تتوفّر سمة async لعلامة <script>، والتي تتيح أيضًا عمليات التنزيل غير المتزامنة، في جميع المتصفحات الحديثة حتى الآن، كما هو موضّح في إجابة Stack Overflow هذه.

  3. سيتم تنفيذ الدالة onYouTubeIframeAPIReady فور تنزيل رمز واجهة برمجة التطبيقات الخاص باللاعب. يحدِّد هذا الجزء من الرمز المتغير العام player الذي يشير إلى مشغّل الفيديو الذي يتم تضمينه، ثم تنشئ الدالة عنصر مشغّل الفيديو.

  4. سيتم تنفيذ الدالة onPlayerReady عند بدء الحدث onReady. في هذا المثال، تشير الدالة إلى أنّه عندما يكون مشغّل الفيديو جاهزًا، يجب أن يبدأ تشغيله.

  5. ستستدعي واجهة برمجة التطبيقات الدالة 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
    }
  });
}

يحدِّد مُنشئ مشغّل الفيديو المَعلمات التالية:

  1. تحدّد المَعلمة الأولى عنصر نموذج عناصر المستند (DOM) أو id عنصر HTML الذي ستُدرج فيه واجهة برمجة التطبيقات علامة <iframe> التي تحتوي على المشغّل.

    ستستبدل IFrame API العنصر المحدّد بعنصر <iframe> الذي يحتوي على المشغّل. وقد يؤثر ذلك في تنسيق صفحتك إذا كان العنصر الذي يتم استبداله يعرض نمطًا مختلفًا عن نمط عنصر <iframe> الذي تم إدراجه. يتم عرض <iframe> تلقائيًا كعنصر inline-block.

  2. والمَعلمة الثانية هي عنصر يحدِّد خيارات المشغِّل. يحتوي الكائن على السمات التالية:
    • ‫width (رقم) – عرض مشغّل الفيديو تكون القيمة التلقائية 640.
    • ‫height (رقم) – ارتفاع مشغّل الفيديو تكون القيمة التلقائية 390.
    • ‫videoId (سلسلة) - معرّف فيديو YouTube الذي يحدّد الفيديو الذي سيحمّله المشغّل
    • ‫playerVars (عنصر) – تحدّد سمات العنصر مَعلمات المشغّل التي يمكن استخدامها لتخصيص المشغّل.
    • events (العنصر) – تحدِّد خصائص العنصر الأحداث التي تطلقها واجهة برمجة التطبيقات والوظائف (المستمعون إلى الأحداث) التي ستستدعيها واجهة برمجة التطبيقات عند وقوع هذه الأحداث. في المثال، يشير أسلوب الإنشاء إلى أنّه سيتم تنفيذ الدالة onPlayerReady عند بدء الحدث onReady، وأنّه سيتم تنفيذ الدالة onPlayerStateChange عند بدء الحدث onStateChange.

كما هو موضّح في قسم البدء، بدلاً من كتابة عنصر <div> فارغ على صفحتك، والذي سيستبدله رمز JavaScript الخاص بواجهة برمجة التطبيقات الخاصة بالّاعبين بعنصر <iframe>، يمكنك إنشاء علامة <iframe> بنفسك. يوضّح المثال الأول في قسم الأمثلة كيفية إجراء ذلك.

<iframe id="player" type="text/html" width="640" height="390"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com"
  frameborder="0"></iframe>

يُرجى العلم أنّه في حال كتابة علامة <iframe>، عند إنشاء عنصر YT.Player، لن تحتاج إلى تحديد قيم لسمتَي width وheight اللتين تم تحديدهما كسمتَين لعلامة <iframe>، أو لمعلَمتَي videoId وplayer اللتين تم تحديدهما في عنوان URL الخاص بـ src. كإجراء أمان إضافي، يجب أيضًا تضمين المَعلمة origin في عنوان URL، مع تحديد مخطّط عنوان URL (http:// أو https://) والنطاق الكامل لصفحة المضيف كقيمة للمَعلمة. على الرغم من أنّ origin اختياري، إلا أنّ تضمينه يحمي من حقن JavaScript الضار التابع لجهة خارجية في صفحتك واختراق التحكّم في مشغّل YouTube.

للحصول على أمثلة أخرى حول إنشاء عناصر مشغّلات الفيديو، يُرجى الاطّلاع على الأمثلة.

العمليات

لاستدعاء طرق واجهة برمجة التطبيقات الخاصة بالمشغّل، يجب أولاً الحصول على إشارة إلى عنصر المشغّل الذي تريد التحكّم فيه. يمكنك الحصول على المرجع من خلال إنشاء عنصر 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