chrome.offscreen

الوصف

الأذونات

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

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

مدى التوفّر

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

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

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

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

• يجب أن يكون عنوان 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.

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

runtime.getContexts() تمت إضافته في Chrome 116. في الإصدارات السابقة من 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>

chrome.offscreen.hasDocument(): Promise<boolean>