chrome.offscreen

Deskripsi

Izin

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

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

Ketersediaan

Konsep dan penggunaan

Pekerja layanan tidak memiliki akses DOM, dan banyak situs web memiliki kebijakan keamanan konten yang membatasi fungsi skrip konten. Offscreen API memungkinkan ekstensi menggunakan DOM API dalam dokumen tersembunyi tanpa mengganggu pengalaman pengguna tab. runtime API adalah satu-satunya API ekstensi didukung oleh dokumen di balik layar.

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

Berikut adalah cara lain di balik layar dokumen berperilaku berbeda dari halaman normal:

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

Gunakan chrome.offscreen.createDocument() dan chrome.offscreen.closeDocument() untuk membuat dan menutup offscreen dokumen. 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 ditutup setelah 30 detik tanpa memutar audio. Semua alasan lain tidak menetapkan batas masa aktif.

Contoh

Mempertahankan siklus proses dokumen di luar layar

Contoh berikut menunjukkan cara memastikan bahwa ada dokumen di balik layar. Tujuan Fungsi setupOffscreenDocument() memanggil runtime.getContexts() untuk menemukan dokumen di luar layar 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 di balik layar, panggil setupOffscreenDocument() untuk memastikan dokumen itu 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 selengkapnya, lihat papan klip di luar layar dan demo offscreen-dom di GitHub.

Sebelum Chrome 116: periksa apakah dokumen di balik layar terbuka

runtime.getContexts() ditambahkan di Chrome 116. Di versi sebelumnya Chrome, gunakan clients.matchAll() untuk memeriksa dokumen di luar layar yang sudah 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 await matchedClients.some(client => {
        client.url.includes(chrome.runtime.id);
    });
  }
}

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

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