chrome.offscreen

Deskripsi

Izin

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

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

Ketersediaan

Konsep dan penggunaan

Service worker 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 Extensions API 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 diteruskan ke dokumen di luar layar, tetapi dengan batasan pada akses API ekstensi. Misalnya, karena API chrome.runtime adalah satu-satunya API ekstensi yang didukung oleh dokumen di luar layar, pengiriman 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 dibundel 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 luar layar, ekstensi yang diinstal hanya dapat membuka satu dokumen dalam satu waktu. Jika ekstensi berjalan dalam mode terpisah dengan profil samaran yang 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 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 = 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 luar 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 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 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 matchedClients.some(client => {       return client.url.includes(chrome.runtime.id);     });   } } 

chrome.offscreen.closeDocument(): Promise<void>

chrome.offscreen.createDocument(
  parameters: CreateParameters,
): Promise<void>