الاستفادة من حالات استخدام مثيرة باستخدام واجهة برمجة التطبيقات Document Picture-in-Picture API

Jad Joubran

تاريخ النشر: 4 مارس 2025

تتيح واجهة برمجة التطبيقات "نافذة ضمن النافذة للمستندات" (Document PiP API) لتطبيقات الويب فتح نافذة عائمة تظهر دائمًا في المقدّمة (نافذة "نافذة ضمن النافذة") يمكنها عرض أي محتوى HTML عشوائي.

تستند واجهة برمجة التطبيقات هذه إلى واجهة برمجة التطبيقات "نافذة ضمن النافذة" لنظام التشغيل <video>، ما يتيح لك مواصلة مشاهدة الفيديو في نافذة "نافذة ضمن النافذة".

بما أنّ واجهة برمجة التطبيقات Document PiP API يمكنها عرض أي محتوى HTML عشوائي، يمكنك استخدامها لفتح حالات استخدام جديدة ومثيرة.

توافُق المتصفّح والتحسين التدريجي

في وقت كتابة هذا المقال، تتوفّر واجهة برمجة التطبيقات Document Picture-in-Picture API بشكل محدود.

ومع ذلك، لا ينبغي أن يمنعك ذلك من استخدامها مع تحسين متدرّج أو التكيّف مع الإصدارات الأقدم.

عند التخطيط لحالة الاستخدام، احرص على التعامل معها على أنّها تحسين متدرّج وليس ميزة عادية. في هذه المقالة، ستجد مثالاً على التكيّف مع الإصدارات الأقدم.

تحسين تجربة المستخدمين من خلال واجهة برمجة التطبيقات Document PiP

LearnHTMLCSS.online هي منصة تعليمية تفاعلية تعلّم كيفية استخدام HTML وCSS بشكل دلالي ومناسب لذوي الاحتياجات الخاصة. توفّر هذه الأداة محرّر نصوص تفاعليًا ونافذة معاينة في المتصفّح.

يعرض تسجيل الشاشة التالي تخطيط التطبيق؛ حيث تنقسم الشاشة إلى عمودَين. يحتوي العمود الأول على محرّر الرموز البرمجية. يحتوي العمود الثاني على تخطيط بعلامات تبويب. وبشكلٍ تلقائي، يمكن للمستخدم الاطّلاع على تعليمات التحدي، ويمكنه النقر على علامة التبويب المتصفّح لعرض معاينة مباشرة.

بصفتك طالبًا، قد تحتاج أحيانًا إلى تكبير نافذة معاينة المتصفّح. هذه فرصة مثالية لإضافة دعم لواجهة برمجة التطبيقات Document Picture-in-Picture API.

لتنفيذ ذلك، ابدأ بالتحقّق من توافق المتصفّح:

const isPipSupported = "documentPictureInPicture" in window;

يمكنك الآن استخدام هذا المتغيّر لتضمين أي طلبات documentPictureInPicture، أو للرجوع مبكرًا من دالة تعتمد على ميزة "نافذة مستند في وضع "نافذة ضمن النافذة"". يتحقّق الرمز التالي من توفّر ميزة "نافذة مستند في وضع "نافذة ضمن النافذة""، ثم يفتح نافذة "نافذة مستند في وضع "نافذة ضمن النافذة"".

async function initDocumentPip() {
  if (!isPipSupported) {
    return false;
  }

  const pipWindow = await documentPictureInPicture.requestWindow({
    width: window.innerWidth,
    height: window.innerHeight,
  });
}

استنادًا إلى حالة الاستخدام، يمكنك تحديد أي عرض وارتفاع للنافذة. يمكنك محاولة مطابقة عنصر معيّن أو المستند الحالي أو حتى تقديم قيم ثابتة.

حتى الآن، لديك مستند فارغ، وعليك الآن ملؤه بالمحتوى.

// htmlCode is the HTML code of the challenge
pipWindow.document.documentElement.innerHTML = htmlCode;

بالنسبة إلى المشاكل المتعلّقة برمز CSS، عليك أيضًا مزامنة CSS.

هذا كل شيء! يتوفّر الآن زر تكبير يفتح في نافذة منفصلة ضمن النافذة.بالإضافة إلى تكبير علامة تبويب معاينة المتصفّح، يمكنك أيضًا نقلها إلى شاشة منفصلة إذا كان لديك شاشة خارجية، أو حتى إعادة ترتيب تطبيق الويب الرئيسي وعلامة تبويب معاينة المتصفّح في تخطيط عمودي.

Fallback

يُرجى العِلم أنّ هذه الواجهة متاحة بشكل محدود. على المتصفّحات والأجهزة التي لا تتوافق مع واجهة برمجة التطبيقات هذه، عليك توفير سلوك احتياطي (تدهور تدريجي).

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

جرِّب هذا السلوك في متصفّحات مختلفة: https://learnhtmlcss.online/app.html?id=2096

يجب الانتباه إلى التفاصيل الصغيرة في التلميحات. عندما تكون قيمة isPipSupported هي true، يتم التبديل بين الدخول إلى وضع "نافذة ضمن النافذة" والخروج من وضع "نافذة ضمن النافذة" في تلميح زر التكبير/التصغير. أما عندما تكون قيمة isPipSupported هي false، فيتم وصف السلوك الاحتياطي باستخدام تكبير وتصغير.

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

لا تدع التوافق المحدود مع المتصفحات يقيّدك، ولا تنسَ توفير حالة استخدام احتياطية مناسبة.

يمكنك الاطّلاع على مستندات Document PiP لاستكشاف أمثلة وحالات استخدام مختلفة لواجهة برمجة التطبيقات هذه.