chrome.offscreen

الوصف

الأذونات

لاستخدام Offscreen API، يجب الإفصاح عن إذن "offscreen" في بيان الإضافة. على سبيل المثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "offscreen"
  ],
  ...
}

مدى التوفّر

المفاهيم والاستخدام

لا يمكن للعاملين في الخدمة الوصول إلى نموذج المستند (DOM)، وتتضمّن العديد من المواقع الإلكترونية سياسات أمان المحتوى التي تحدّ من وظائف النصوص البرمجية للمحتوى. تتيح واجهة برمجة التطبيقات Offscreen للإضافة استخدام واجهات برمجة تطبيقات DOM في مستند مخفي بدون مقاطعة تجربة المستخدم من خلال فتح نوافذ أو علامات تبويب جديدة. إنّ واجهة برمجة التطبيقات runtime هي واجهة برمجة التطبيقات الوحيدة للإضافات التي تتيح استخدام المستندات خارج الشاشة.

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

في ما يلي طرق أخرى يختلف بها سلوك المستندات خارج الشاشة عن الصفحات العادية:

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

استخدِم chrome.offscreen.createDocument() وchrome.offscreen.closeDocument() لإنشاء مستند خارج الشاشة وإغلاقه. يتطلّب createDocument() url المستند وسببًا ومبررًا:

chrome.offscreen.createDocument({
  url: 'off_screen.html',
  reasons: ['CLIPBOARD'],
  justification: 'reason for needing the document',
});

الأسباب

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

أمثلة

الحفاظ على مراحل نشاط مستند خارج الشاشة

يوضّح المثال التالي كيفية التأكّد من توفّر مستند خارج الشاشة. تستدعي الدالة setupOffscreenDocument() الدالة runtime.getContexts() للعثور على مستند غير معروض على الشاشة، أو تنشئ المستند إذا لم يكن متوفّرًا.

let creating; // A global promise to avoid concurrency issues
async function setupOffscreenDocument(path) {
  // Check all windows controlled by the service worker to see if one
  // of them is the offscreen document with the given path
  const offscreenUrl = chrome.runtime.getURL(path);
  const existingContexts = await chrome.runtime.getContexts({
    contextTypes: ['OFFSCREEN_DOCUMENT'],
    documentUrls: [offscreenUrl]
  });

  if (existingContexts.length > 0) {
    return;
  }

  // create offscreen document
  if (creating) {
    await creating;
  } else {
    creating = chrome.offscreen.createDocument({
      url: path,
      reasons: ['CLIPBOARD'],
      justification: 'reason for needing the document',
    });
    await creating;
    creating = null;
  }
}

قبل إرسال رسالة إلى مستند غير معروض على الشاشة، اتّصِل بالدالة setupOffscreenDocument() للتأكّد من توفّر المستند، كما هو موضّح في المثال التالي.

chrome.action.onClicked.addListener(async () => {
  await setupOffscreenDocument('off_screen.html');

  // Send message to offscreen document
  chrome.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

للاطّلاع على أمثلة كاملة، راجِع العرضَين التوضيحيَين offscreen-clipboard وoffscreen-dom على GitHub.

قبل الإصدار 116 من Chrome: التحقّق مما إذا كان مستند خارج الشاشة مفتوحًا

تمت إضافة runtime.getContexts() في الإصدار 116 من Chrome. في الإصدارات السابقة من Chrome، استخدِم clients.matchAll() للتحقّق من وجود مستند خارج الشاشة:

async function hasOffscreenDocument() {
  if ('getContexts' in chrome.runtime) {
    const contexts = await chrome.runtime.getContexts({
      contextTypes: ['OFFSCREEN_DOCUMENT'],
      documentUrls: [OFFSCREEN_DOCUMENT_PATH]
    });
    return Boolean(contexts.length);
  } else {
    const matchedClients = await clients.matchAll();
    return matchedClients.some(client => {
      return client.url.includes(chrome.runtime.id);
    });
  }
}

chrome.offscreen.closeDocument(): Promise<void>

chrome.offscreen.createDocument(
  parameters: CreateParameters,
): Promise<void>