browser.offscreen

شرح

اجازه‌ها

برای استفاده از «میانای برنامه‌سازی کاربردی Offscreen»، اجازه "offscreen" را در مانیفست افزونه اعلام کنید. برای مثال:

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

دردسترس بودن

مفاهیم و استفاده

کارکنان سرویس به DOM دسترسی ندارند و بسیاری از وب‌سایت‌ها خط‌مشی‌های امنیتی محتوایی دارند که عملکرد برنامه‌های محتوا را محدود می‌کند. «میانای برنامه‌سازی کاربردی خارج از صفحه» به افزونه امکان می‌دهد از میاناهای برنامه‌سازی کاربردی DOM در سند پنهان استفاده کند بدون اینکه با باز کردن پنجره‌ها یا برگه‌های جدید، تجربه کاربری را مختل کند. میانای برنامه‌سازی کاربردی runtime تنها میانای برنامه‌سازی کاربردی افزونه‌ها است که از اسناد خارج‌ازصفحه پشتیبانی می‌کند.

صفحه‌هایی که به‌عنوان سندهای خارج از صفحه بار می‌شوند، با انواع دیگر صفحه‌های افزونه متفاوت مدیریت می‌شوند. اجازه‌های افزونه به اسناد خارج از صفحه منتقل می‌شود، اما دسترسی به API افزونه محدود است. برای مثال، چون browser.runtime API تنها میانای برنامه‌سازی کاربردی افزونه‌ای است که از اسناد خارج‌ازصفحه پشتیبانی می‌کند، پیام‌رسانی باید بااستفاده از اعضای آن API مدیریت شود.

در زیر روش‌های دیگری که اسناد خارج از صفحه با صفحات عادی متفاوت هستند آورده شده است:

• نشانی وب سند خارج از صفحه باید فایل 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 باعث می‌شود سند پس‌از ۳۰ ثانیه بدون پخش صدا بسته شود. همه دلایل دیگر محدودیت‌های مادام‌العمر را تنظیم نمی‌کنند.

مثال‌ها

حفظ چرخه عمر سند خارج از صفحه

مثال زیر نشان می‌دهد که چگونه می‌توان مطمئن شد که سند خارج از صفحه وجود دارد. تابع 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 ببینید.

قبل‌از Chrome 116: بررسی کنید که سند خارج از صفحه باز است یا نه

runtime.getContexts() در Chrome 116 اضافه شد. در نسخه‌های قدیمی‌تر 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);
    });
  }
}

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

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

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