chrome.offscreen

Deskripsi

Gunakan offscreen API untuk membuat dan mengelola dokumen di balik layar.

Izin

offscreen

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

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

Ketersediaan

Chrome 109 dan yang lebih baru MV3 dan yang lebih baru

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

Jenis

CreateParameters

Properti

  • justifikasi

    string

    String yang disediakan developer yang menjelaskan, secara lebih mendetail, kebutuhan akan konteks latar belakang. Agen pengguna _mungkin_ menggunakan atribut ini agar ditampilkan kepada pengguna.

  • alasan

    Alasan[]

    Alasan ekstensi adalah membuat dokumen di balik layar.

  • url

    string

    URL (relatif) yang akan dimuat dalam dokumen.

Reason

Enum

"PENGUJIAN"
Alasan yang digunakan hanya untuk tujuan pengujian.

"AUDIO_PLAYBACK"
Menentukan bahwa dokumen di luar layar bertanggung jawab untuk memutar audio.

"IFRAME_SCRIPTING"
Menentukan bahwa dokumen di luar layar harus menyematkan dan membuat skrip iframe untuk mengubah konten iframe.

"DOM_SCRAPING"
Menentukan bahwa dokumen di balik layar harus menyematkan iframe dan melakukan scraping DOM-nya untuk mengekstrak informasi.

"BLOBS"
Menentukan bahwa dokumen di luar layar harus berinteraksi dengan objek Blob (termasuk URL.createObjectURL()).

"DOM_PARSER"
Menentukan bahwa dokumen di luar layar harus menggunakan DOMParser API.

"USER_MEDIA"
Menentukan bahwa dokumen di luar layar harus berinteraksi dengan streaming media dari media pengguna (misalnya, getUserMedia()).

"DISPLAY_MEDIA"
Menentukan bahwa dokumen di luar layar harus berinteraksi dengan streaming media dari media tampilan (misalnya, getDisplayMedia()).

"WEB_RTC"
Menentukan bahwa dokumen di luar layar perlu menggunakan API WebRTC.

"CLIPBOARD"
Menentukan bahwa dokumen di luar layar harus berinteraksi dengan Clipboard API.

"LOCAL_STORAGE"
Menentukan bahwa dokumen di luar layar memerlukan akses ke localStorage.

"WORKERS"
Menentukan bahwa dokumen di luar layar perlu memunculkan pekerja.

"BATTERY_STATUS"
Menentukan bahwa dokumen di luar layar perlu menggunakan navigator.getBattery.

"MATCH_MEDIA"
Menentukan bahwa dokumen di luar layar harus menggunakan window.matchMedia.

"GEOLOCATION"
Menentukan bahwa dokumen di luar layar harus menggunakan navigator.geolocation.

Metode

closeDocument()

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

Menutup dokumen di luar layar yang saat ini terbuka untuk ekstensi.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

createDocument()

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

Membuat dokumen baru di balik layar untuk ekstensi.

Parameter

  • parameter

    CreateParameters

    Parameter yang menjelaskan dokumen di balik layar yang akan dibuat.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.