chrome.offscreen

الوصف

الأذونات

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

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

مدى التوفّر

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

لا يمكن لموظفي الخدمة الوصول إلى نموذج العناصر في المستند (DOM)، والعديد من المواقع الإلكترونية لديها سياسات أمان محتوى تحد من وظائف النصوص البرمجية للمحتوى. تسمح واجهة برمجة التطبيقات Offscreen API للإضافة باستخدام نموذج العناصر في المستند (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: '...'
  });
});

للحصول على أمثلة كاملة، يمكنك الاطّلاع على الحافظة خارج الشاشة و عروض خارج الشاشة على 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 await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

chrome.offscreen.closeDocument(
  callback?: function,
)

chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)