browser.offscreen

شرح

از offscreen API برای ایجاد و مدیریت اسناد خارج‌از صفحه استفاده کنید.

اجازه‌ها

offscreen

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

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

دردسترس بودن

Chrome نسخه ۱۰۹ و بالاتر browser.* از Chrome نسخه ۱۴۸ MV3 و بالاتر

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

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

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

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

• نشانی وب سند خارج‌از صفحه باید فایل 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);
    });
  }
}

انواع

CreateParameters

مشخصات

• توجیه

  رشته

  رشته‌ای که توسعه‌دهنده ارائه کرده است و با جزئیات بیشتر توضیح می‌دهد که چرا به زمینه پس‌زمینه نیاز است. نماینده کاربر _ممکن است_ از این در نمایش به کاربر استفاده کند.

• دلیل

  دلیل[]

  دلیل(های) ایجاد سند خارج‌از صفحه توسط افزونه.

• نشانی وب

  رشته

  نشانی وب (نسبی) برای بار کردن در سند.

Reason

شمارشی

«آزمایش»
دلیلی که فقط برای اهداف آزمایشی استفاده می‌شود.

"AUDIO_PLAYBACK"
مشخص می‌کند که سند خارج از صفحه مسئول پخش صدا است.

"IFRAME_SCRIPTING"
مشخص می‌کند که سند خارج‌از صفحه برای اصلاح محتوای iframe باید یک iframe را جاسازی و اسکریپت‌نویسی کند.

«DOM_SCRAPING»
مشخص می‌کند که سند خارج‌از صفحه باید یک iframe جاسازی کند و DOM آن را برای استخراج اطلاعات بتراشد.

"BLOBS"
مشخص می‌کند که سند خارج‌از صفحه باید با اشیای Blob (ازجمله URL.createObjectURL()) تعامل داشته باشد.

"DOM_PARSER"
مشخص می‌کند که سند خارج‌از صفحه باید از DOMParser API استفاده کند.

«USER_MEDIA»
مشخص می‌کند که سند خارج‌از صفحه باید با جاری‌سازی‌های رسانه از رسانه کاربر (مثلاً getUserMedia()) تعامل داشته باشد.

"DISPLAY_MEDIA"
مشخص می‌کند که سند خارج‌از صفحه باید با جاری‌سازی‌های رسانه از رسانه نمایش (مثلاً getDisplayMedia()) تعامل داشته باشد.

«WEB_RTC»
مشخص می‌کند که سند خارج‌از صفحه باید از WebRTC APIs استفاده کند.

"CLIPBOARD"
مشخص می‌کند که سند خارج از صفحه باید با Clipboard API تعامل داشته باشد.

"LOCAL_STORAGE"
مشخص می‌کند که سند خارج‌از صفحه به localStorage نیاز دارد.

«WORKERS»
مشخص می‌کند که سند خارج‌از صفحه باید کارگر ایجاد کند.

"BATTERY_STATUS"
مشخص می‌کند که سند خارج از صفحه باید از navigator.getBattery استفاده کند.

"MATCH_MEDIA"
مشخص می‌کند که سند خارج‌از صفحه باید از window.matchMedia استفاده کند.

«GEOLOCATION»
مشخص می‌کند که سند خارج‌از صفحه باید از navigator.geolocation استفاده کند.

روش‌ها

closeDocument()

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

سند خارج‌ازصفحه بازشده فعلی را برای افزونه می‌بندد.

بازگشتی‌ها

• Promise<void>

  Promise که وقتی سند خارج از صفحه بسته می‌شود، حل می‌شود.

createDocument()

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

سند خارج‌ازصفحه جدیدی برای افزونه ایجاد می‌کند.

پارامترها

• پارامترها

  CreateParameters

  پارامترهایی که سند خارج از صفحه را برای ایجاد توصیف می‌کنند.

بازگشتی‌ها

• Promise<void>

  Promise که وقتی سند خارج از صفحه ایجاد می‌شود و بارگیری صفحه اولیه آن تکمیل می‌شود، حل می‌شود.

hasDocument()

Chrome نسخه ۱۵۰ و بالاتر

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

تعیین می‌کند که آیا افزونه سند فعالی دارد یا نه.

بازگشتی‌ها

• Promise<boolean>

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