chrome.offscreen

توضیحات

مجوزها

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

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

در دسترس بودن

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

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

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

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

• آدرس اینترنتی (URL) یک سند خارج از صفحه باید یک فایل HTML استاتیک همراه با پسوند باشد.
• اسناد خارج از صفحه نمایش قابل فوکوس نیستند.
• یک سند خارج از صفحه (offscreen) نمونه‌ای از 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 مراجعه کنید.

قبل از کروم ۱۱۶: بررسی کنید که آیا یک سند خارج از صفحه نمایش باز است یا خیر

runtime.getContexts() در کروم نسخه ۱۱۶ اضافه شد. در نسخه‌های قبلی کروم، از 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 matchedClients.some(client => {
      return client.url.includes(chrome.runtime.id);
    });
  }
}

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

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