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
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 propertiopener
-nya selalunull
. - 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()
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()
chrome.offscreen.createDocument(
parameters: CreateParameters,
callback?: function,
)
Membuat dokumen di balik layar baru untuk ekstensi.
Parameter
-
parameter
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.