تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

Jad Joubran

تاريخ النشر: 4 آذار (مارس) 2025

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

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

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

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

Browser Support

Source

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

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

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

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

LearnHTMLCSS.online هي منصة تعلّم تفاعلية تعلّم لغتَي HTML وCSS الدلالية وسهلتَي الاستخدام. ويقدّم محرِّر نصوص تفاعليًا ونافذة معاينة للمتصفّح.

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

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

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

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 Picture-in-Picture API حالات استخدام جديدة ومثيرة لتطبيق الويب عند دمجها مع ميزة "التحسين التدريجي" أو "التشغيل السلس".

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

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