chrome.offscreen

Deskripsi

Izin

Untuk menggunakan Offscreen API, deklarasikan izin "offscreen" dalam manifes ekstensi. Contoh:

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

Ketersediaan

Konsep dan penggunaan

Service worker tidak memiliki akses DOM, dan banyak situs memiliki kebijakan keamanan konten yang membatasi fungsi skrip konten. Offscreen API memungkinkan ekstensi menggunakan DOM API dalam dokumen tersembunyi tanpa mengganggu pengalaman pengguna dengan membuka jendela atau tab baru. The runtime API adalah satu-satunya ekstensi API yang didukung oleh dokumen offscreen.

Halaman yang dimuat sebagai dokumen offscreen ditangani secara berbeda dari jenis halaman ekstensi lainnya. Izin ekstensi diteruskan ke dokumen offscreen, tetapi dengan batasan pada akses ekstensi API. Misalnya, karena chrome.runtime API adalah satu-satunya ekstensi API yang didukung oleh dokumen offscreen, pesan harus ditangani menggunakan anggota API tersebut.

Berikut adalah cara lain dokumen offscreen berperilaku berbeda dari halaman normal:

• URL dokumen offscreen harus berupa file HTML statis yang disertakan dengan ekstensi.
• Dokumen offscreen tidak dapat difokuskan.
• Dokumen offscreen adalah instance window, tetapi nilai properti opener selalu null.
• Meskipun paket ekstensi dapat berisi beberapa dokumen offscreen, ekstensi yang diinstal hanya dapat memiliki satu yang terbuka dalam satu waktu. Jika ekstensi berjalan dalam mode terpisah dengan profil samaran yang aktif, profil normal dan samaran masing-masing dapat memiliki satu dokumen offscreen.

Gunakan chrome.offscreen.createDocument() dan chrome.offscreen.closeDocument() untuk membuat dan menutup dokumen offscreen. createDocument() memerlukan url dokumen, alasan, dan justifikasi:

chrome.offscreen.createDocument({
  url: 'off_screen.html',
  reasons: ['CLIPBOARD'],
  justification: 'reason for needing the document',
});

Alasan

Untuk mengetahui daftar alasan yang valid, lihat bagian Alasan. Alasan ditetapkan selama pembuatan dokumen untuk menentukan masa aktif dokumen. Alasan AUDIO_PLAYBACK menetapkan dokumen untuk ditutup setelah 30 detik tanpa audio diputar. Semua alasan lainnya tidak menetapkan batas masa aktif.

Contoh

Mempertahankan siklus proses dokumen offscreen

Contoh berikut menunjukkan cara memastikan dokumen offscreen ada. Fungsi setupOffscreenDocument() memanggil runtime.getContexts() untuk menemukan dokumen offscreen yang ada, atau membuat dokumen jika belum ada.

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;
  }
}

Sebelum mengirim pesan ke dokumen offscreen, panggil setupOffscreenDocument() untuk memastikan dokumen ada, seperti yang ditunjukkan dalam contoh berikut.

chrome.action.onClicked.addListener(async () => {
  await setupOffscreenDocument('off_screen.html');

  // Send message to offscreen document
  chrome.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

Untuk contoh lengkap, lihat demo offscreen-clipboard dan offscreen-dom di GitHub.

Sebelum Chrome 116: memeriksa apakah dokumen offscreen terbuka

runtime.getContexts() ditambahkan di Chrome 116. Di Chrome versi sebelumnya, gunakan clients.matchAll() untuk memeriksa dokumen offscreen yang ada:

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>

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