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+ MV3+

Konsep dan penggunaan

Pekerja layanan 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. runtime API adalah satu-satunya API ekstensi yang didukung oleh dokumen offscreen.

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

Berikut adalah cara lain perilaku dokumen di luar layar yang 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 luar layar adalah instance window, tetapi nilai properti opener-nya selalu null.
  • Meskipun paket ekstensi dapat berisi beberapa dokumen di balik layar, ekstensi yang diinstal hanya dapat dibuka satu per satu. Jika ekstensi berjalan dalam mode terpisah dengan profil samaran aktif, profil normal dan samaran masing-masing dapat memiliki satu dokumen di balik layar.

Gunakan chrome.offscreen.createDocument() dan chrome.offscreen.closeDocument() untuk membuat dan menutup dokumen di luar layar. 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 pemutaran audio. Semua alasan lainnya tidak menetapkan batas masa aktif.

Contoh

Mempertahankan siklus proses dokumen di balik layar

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

Sebelum Chrome 116: periksa apakah dokumen di balik layar terbuka

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

Jenis

CreateParameters

Properti

  • justifikasi

    string

    String yang disediakan developer yang menjelaskan secara lebih mendetail perlunya konteks latar belakang. Agen pengguna _mungkin_ menggunakan ini dalam tampilan kepada pengguna.

  • alasan

    Alasan[]

    Alasan ekstensi ini membuat dokumen di balik layar.

  • url

    string

    URL (relatif) yang akan dimuat dalam dokumen.

Reason

Enum

"TESTING"
Alasan yang digunakan hanya untuk tujuan pengujian.

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

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

"DOM_SCRAPING"
Menentukan bahwa dokumen di luar layar perlu menyematkan iframe dan menyalin DOM-nya untuk mengekstrak informasi.

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

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

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

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

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

"CLIPBoard"
Menentukan bahwa dokumen di luar layar perlu berinteraksi dengan Clipboard API.

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

"PEKERJA"
Menentukan bahwa dokumen di balik layar perlu memunculkan pekerja.

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

"MATCH_MEDIA"
Menentukan bahwa dokumen offscreen perlu menggunakan window.matchMedia.

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

Metode

closeDocument()

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

Menutup dokumen di luar layar yang sedang dibuka untuk ekstensi.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

createDocument()

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

Membuat dokumen di balik layar baru untuk ekstensi.

Parameter

  • parameter

    CreateParameters

    Parameter yang menjelaskan dokumen offscreen yang akan dibuat.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.