browser.offscreen

الوصف

استخدِم واجهة برمجة التطبيقات offscreen لإنشاء مستندات خارج الشاشة وإدارتها.

الأذونات

offscreen

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

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

مدى التوفّر

الإصدار 109 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome الإصدار 3 من MV والإصدارات الأحدث

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

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

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

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

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

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

browser.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 = browser.runtime.getURL(path);
  const existingContexts = await browser.runtime.getContexts({
    contextTypes: ['OFFSCREEN_DOCUMENT'],
    documentUrls: [offscreenUrl]
  });

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

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

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

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

  // Send message to offscreen document
  browser.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 browser.runtime) {
    const contexts = await browser.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(browser.runtime.id);
    });
  }
}

الأنواع

CreateParameters

الخصائص

• التبرير

  سلسلة

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

• سبب

  السبب[]

  الأسباب التي تدفع الإضافة إلى إنشاء مستند خارج الشاشة

• url

  سلسلة

  عنوان URL (النسبي) الذي سيتم تحميله في المستند

Reason

Enum

"TESTING"
سبب يُستخدَم لأغراض الاختبار فقط

‫"AUDIO_PLAYBACK"
يحدّد أنّ المستند خارج الشاشة مسؤول عن تشغيل الصوت.

‫"IFRAME_SCRIPTING"
يشير إلى أنّ المستند خارج الشاشة يحتاج إلى تضمين إطار iframe وإضافة نص برمجي إليه لتعديل محتوى الإطار.

"DOM_SCRAPING"
تحدّد أنّ المستند خارج الشاشة يحتاج إلى تضمين إطار iframe واستخراج DOM الخاص به لاستخراج المعلومات.

"BLOBS"
تحدّد هذه القيمة أنّ المستند خارج الشاشة يحتاج إلى التفاعل مع عناصر Blob (بما في ذلك URL.createObjectURL()).

"DOM_PARSER"
يشير إلى أنّ المستند خارج الشاشة يحتاج إلى استخدام واجهة برمجة التطبيقات DOMParser API.

"USER_MEDIA"
تحدّد هذه القيمة أنّ المستند خارج الشاشة يحتاج إلى التفاعل مع مصادر الوسائط من وسائط المستخدم (مثل getUserMedia()).

"DISPLAY_MEDIA"
تحدّد أنّ المستند خارج الشاشة يحتاج إلى التفاعل مع مصادر الوسائط من وسائط العرض (مثل getDisplayMedia()).

"WEB_RTC"
تحدّد أنّ المستند خارج الشاشة يحتاج إلى استخدام واجهات برمجة تطبيقات WebRTC.

"CLIPBOARD"
يحدّد أنّ المستند خارج الشاشة يحتاج إلى التفاعل مع Clipboard API.

"LOCAL_STORAGE"
يشير إلى أنّ المستند خارج الشاشة يحتاج إلى الوصول إلى localStorage.

"WORKERS"
تشير إلى أنّ المستند خارج الشاشة يحتاج إلى إنشاء عمال.

"BATTERY_STATUS"
يشير إلى أنّ المستند خارج الشاشة يحتاج إلى استخدام navigator.getBattery.

"MATCH_MEDIA"
تشير إلى أنّ المستند خارج الشاشة يحتاج إلى استخدام window.matchMedia.

"GEOLOCATION"
يشير إلى أنّ المستند خارج الشاشة يحتاج إلى استخدام navigator.geolocation.

الطُرق

closeDocument()

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

يغلق هذا الإجراء المستند المفتوح حاليًا خارج الشاشة للإضافة.

المرتجعات

• وعد<فراغ>

  وعد يتم حلّه عند إغلاق المستند خارج الشاشة.

createDocument()

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

يتم إنشاء مستند جديد خارج الشاشة للإضافة.

المعلمات

• المعلمات

  CreateParameters

  المَعلمات التي تصف مستند الشاشة الخارجية المطلوب إنشاؤه

المرتجعات

• وعد<فراغ>

  وعد يتم حله عند إنشاء المستند خارج الشاشة وإكمال تحميل الصفحة الأولية.

hasDocument()

الإصدار 150 من Chrome والإصدارات الأحدث

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

تحدّد ما إذا كانت الإضافة تحتوي على مستند نشط.

المرتجعات

• Promise<boolean>

  وعد يتم حله بنتيجة ما إذا كانت الإضافة تحتوي على مستند نشط خارج الشاشة.