Deskripsi
Gunakan offscreen API untuk membuat dan mengelola dokumen di luar layar.
Izin
offscreenUntuk menggunakan Offscreen API, deklarasikan izin "offscreen" di manifes ekstensi. Contoh:
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}
Ketersediaan
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 di luar layar.
Halaman yang dimuat sebagai dokumen di luar layar ditangani secara berbeda dari jenis halaman ekstensi lainnya.
Izin ekstensi akan diterapkan ke dokumen di luar layar, tetapi dengan batasan pada akses API
ekstensi. Misalnya, karena browser.runtime API adalah satu-satunya
API ekstensi yang didukung oleh dokumen di luar layar, pesan harus ditangani
menggunakan anggota API tersebut.
Berikut adalah cara lain dokumen di balik layar berperilaku berbeda dari halaman normal:
- URL dokumen di balik 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 propertiopener-nya selalunull. - Meskipun paket ekstensi dapat berisi beberapa dokumen di luar layar, ekstensi yang diinstal hanya dapat membuka satu dokumen dalam satu waktu. Jika ekstensi berjalan dalam mode terpisah dengan profil samaran aktif, profil normal dan samaran masing-masing dapat memiliki satu dokumen offscreen.
Gunakan browser.offscreen.createDocument() dan
browser.offscreen.closeDocument() untuk membuat dan menutup dokumen
di luar layar. createDocument() memerlukan url dokumen, alasan, dan justifikasi:
browser.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 di luar layar
Contoh berikut menunjukkan cara memastikan bahwa dokumen di luar layar ada. 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 = browser.runtime.getURL(path);
const existingContexts = await browser.runtime.getContexts({
contextTypes: ['OFFSCREEN_DOCUMENT'],
documentUrls: [offscreenUrl]
});
if (existingContexts.length > 0) {
return;
}
// create offscreen document
if (creating) {
await creating;
} else {
creating = browser.offscreen.createDocument({
url: path,
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});
await creating;
creating = null;
}
}
Sebelum mengirim pesan ke dokumen di luar layar, panggil setupOffscreenDocument() untuk memastikan
dokumen ada, seperti yang ditunjukkan dalam contoh berikut.
browser.action.onClicked.addListener(async () => {
await setupOffscreenDocument('off_screen.html');
// Send message to offscreen document
browser.runtime.sendMessage({
type: '...',
target: 'offscreen',
data: '...'
});
});
Untuk contoh lengkap, lihat demo offscreen-clipboard dan offscreen-dom di GitHub.
Sebelum Chrome 116: memeriksa apakah dokumen di balik layar terbuka
runtime.getContexts() ditambahkan di Chrome 116. Di Chrome versi sebelumnya, gunakan clients.matchAll() untuk memeriksa dokumen di luar layar yang ada:
async function hasOffscreenDocument() {
if ('getContexts' in browser.runtime) {
const contexts = await browser.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(browser.runtime.id);
});
}
}
Jenis
CreateParameters
Properti
-
justification
string
String yang disediakan developer yang menjelaskan, secara lebih mendetail, kebutuhan akan konteks latar belakang. Agen pengguna _dapat_ menggunakannya dalam tampilan kepada pengguna.
-
alasan
Alasan[]
Alasan ekstensi membuat dokumen di balik layar.
-
url
string
URL (relatif) yang akan dimuat dalam dokumen.
Reason
Enum
"TESTING"
Alasan yang hanya digunakan untuk tujuan pengujian.
"AUDIO_PLAYBACK"
Menentukan bahwa dokumen di luar 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 mengikis 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 luar layar perlu 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 tampilan (misalnya, getDisplayMedia()).
"WEB_RTC"
Menentukan bahwa dokumen di luar layar perlu menggunakan WebRTC API.
"CLIPBOARD"
Menentukan bahwa dokumen di luar layar perlu berinteraksi dengan Clipboard API.
"LOCAL_STORAGE"
Menentukan bahwa dokumen di luar layar memerlukan akses ke localStorage.
"WORKERS"
Menentukan bahwa dokumen di luar layar perlu membuat worker.
"BATTERY_STATUS"
Menentukan bahwa dokumen di luar layar perlu menggunakan navigator.getBattery.
"MATCH_MEDIA"
Menentukan bahwa dokumen di luar layar perlu menggunakan window.matchMedia.
"GEOLOCATION"
Menentukan bahwa dokumen di luar layar perlu menggunakan navigator.geolocation.
Metode
closeDocument()
browser.offscreen.closeDocument(): Promise<void>
Menutup dokumen di luar layar yang saat ini terbuka untuk ekstensi.
Hasil
-
Promise<void>
Promise yang di-resolve saat dokumen di luar layar telah ditutup.
createDocument()
browser.offscreen.createDocument(
parameters: CreateParameters,
): Promise<void>
Membuat dokumen di balik layar baru untuk ekstensi.
Parameter
-
parameter
Parameter yang menjelaskan dokumen di luar layar yang akan dibuat.
Hasil
-
Promise<void>
Promise yang di-resolve saat dokumen di balik layar dibuat dan telah menyelesaikan pemuatan halaman awalnya.
hasDocument()
browser.offscreen.hasDocument(): Promise<boolean>
Menentukan apakah ekstensi memiliki dokumen aktif.
Hasil
-
Promise<boolean>
Promise yang di-resolve dengan hasil apakah ekstensi memiliki dokumen di luar layar yang aktif.