browser.offscreen

شرح

اجازه‌ها

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

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

دردسترس بودن

مفاهیم و کاربرد

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

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

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

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

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