Документи offscreen у розширеннях Chrome

Коротка відповідь

Позаекранний документ — прихована HTML-сторінка пакета для обґрунтованого завдання з DOM API, недоступними воркеру. Оголосіть offscreen, задайте документовану причину й конкретне пояснення та спілкуйтеся runtime-повідомленнями. Він не замінює постійну фонову сторінку.

У позаекранному документі підтримується лише Runtime із API розширення. Сховище й іншу привілейовану роботу передавайте відповідному контексту. Якщо користувач має дослідити чи змінити результат, видима сторінка часто підходить краще.

Практичні кроки реалізації

1. Визначте відсутню можливість. Розбір HTML через DOM може обґрунтувати DOM_PARSER; запис у буфер обміну — інша причина з власними вимогами. Не вибирайте причину лише для довшого життя прихованої сторінки.
2. Пакуйте статичний HTML і зовнішні скрипти. Документ не може бути віддаленим URL і не отримує фокус. Загальний API доступний із Chrome 109.
3. Упорядкуйте створення й перевіряйте наявні контексти. Зазвичай розширення має один відкритий документ; окремі incognito-профілі мають документовану поведінку. runtime.getContexts потребує Chrome 116: установіть цю межу або підтримувану старішу альтернативу.
4. Надсилайте вузьке повідомлення з визначеною ціллю й повертайте лише результат. Воркер та інші контексти чують runtime, тому сторонні слухачі не мають відповідати випадково. Перевіряйте завдання й розмір даних з обох боків.
5. Закривайте документ після завершення його завдань. За спільного використання визначте власників або лічильник: одне завдання не має закривати ресурс іншого. Відтворення аудіо має спеціальне правило простою; інші причини не гарантують збереженого стану.

HTML-експорт на зразок LocaleStress можна створити рядком без прихованого DOM. Використовуйте позаекранний документ лише за фактичної потреби експорту в DOM. Подібність продукту не доводить, що LocaleStress використовує цей API.

Приклад реалізації

Помічник воркера створює один документ розбору DOM та скидає поточний проміс після успіху чи відмови. Він передбачає Chrome 116+ і дозвіл offscreen.

let creating;
export async function ensureParserDocument() {
  if (creating) return creating;
  creating = (async () => {
    const url = chrome.runtime.getURL("parser.html");
    const contexts = await chrome.runtime.getContexts({
      contextTypes: ["OFFSCREEN_DOCUMENT"], documentUrls: [url],
    });
    if (contexts.length) return;
    await chrome.offscreen.createDocument({
      url: "parser.html",
      reasons: ["DOM_PARSER"],
      justification: "Parse user-provided HTML into a bounded text-only summary",
    });
  })();
  try { await creating; } finally { creating = undefined; }
}

Помічник створює поверхню, а не повний безпечний процес розбору. Отримувачу потрібні обмежене введення, безпечне отримання тексту та підтвердження завершення. Наявний документ за іншим шляхом — конфлікт конфігурації, а не причина створювати другий.

Компроміси та альтернативи

Видима вкладка дає контекст і керування; прихований документ не перериває користувача за короткого механічного завдання. Чисте оброблення рядків залиште воркеру, якщо DOM не потрібен. Вибирайте найпростішу придатну поверхню.

Поширені помилки

• Використовувати позаекранний документ як постійний прихований сервер застосунку.
• Викликати storage API безпосередньо в ньому.
• Створювати документи паралельно без координації.
• Вибирати невідповідну причину заради іншого життєвого циклу.

Контрольний список випуску

• ☐ Реальна потреба DOM і причина створення задокументовані.
• ☐ Мінімальна версія охоплює перевірку контекстів.
• ☐ Відмова створення допускає повторення.
• ☐ Повідомлення мають ціль, перевірку й значення завершення.
• ☐ Закриття враховує кожне активне завдання.

Поширені запитання

Чи завантажити довільний сайт?

Ні. URL документа має бути статичним HTML-ресурсом пакета.

Чи offscreen захищає дані від перезапуску?

Ні. Збережений стан усе одно потребує явного запису й відновлення.

Що довести спочатку?

Реальну потребу DOM, потім спільне використання одного документа двома одночасними запитами та повторне створення після відмови.

Первинні джерела

• API Offscreen
• Контексти Runtime
• Життєвий цикл воркера

Пов’язані посібники та приклади

• Тематичний розділ
• Як створити розширення Chrome з Manifest V3
• Структура проєкту розширення Chrome, що масштабується
• Як написати файл manifest.json для Manifest V3
• Явні завдання звітів та експорту LocaleStress