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

Jad Joubran

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

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

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

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

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

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

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

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

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

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 لاستكشاف أمثلة وحالات استخدام مختلفة لواجهة برمجة التطبيقات هذه.