chrome.offscreen

توضیحات

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

مجوزها

offscreen

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

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

در دسترس بودن

Chrome 109+ MV3+

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

کارکنان خدمات دسترسی به 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);
    });
  }
}

انواع

CreateParameters

خواص

• توجیه

  رشته

  رشته ای ارائه شده توسط توسعه دهنده که با جزئیات بیشتری نیاز به زمینه پس زمینه را توضیح می دهد. عامل کاربر _may_ از این در نمایش به کاربر استفاده می کند.

• دلایل

  دلیل []

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

• آدرس اینترنتی

  رشته

  URL (نسبی) برای بارگیری در سند.

Reason

Enum

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

"AUDIO_PLAYBACK"
مشخص می کند که سند خارج از صفحه وظیفه پخش صدا را بر عهده دارد.

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

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

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

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

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

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

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

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

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

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

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

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

"ژئولوکاسیون"
مشخص می کند که سند خارج از صفحه باید از navigator.geolocation استفاده کند.

روش ها

closeDocument()

قول بده

chrome.offscreen.closeDocument(
  callback?: function,
)

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

پارامترها

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

createDocument()

قول بده

chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)

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

پارامترها

• پارامترها

  ایجاد پارامترها

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

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.