chrome.offscreen

توضیحات

مجوزها

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

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

در دسترس بودن

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

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

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

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

• 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: '...'
  });
});

برای مثال‌های کامل، به دموی offscreen-clipboard و offscreen-dom در GitHub مراجعه کنید.

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

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