Açıklama
Ekran dışı dokümanlar oluşturmak ve yönetmek için offscreen API'yi kullanın.
İzinler
offscreenOffscreen API'yi kullanmak için uzantı manifest dosyasında "offscreen" iznini belirtin. Örneğin:
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}
Kullanılabilirlik
Kavramlar ve kullanım
Hizmet çalışanlarının DOM erişimi yoktur ve birçok web sitesinde, içerik komut dosyalarının işlevini sınırlayan içerik güvenliği politikaları bulunur. Offscreen API, uzantının yeni pencereler veya sekmeler açarak kullanıcı deneyimini kesintiye uğratmadan gizli bir dokümanda DOM API'lerini kullanmasına olanak tanır. runtime API, ekran dışı dokümanlar tarafından desteklenen tek uzantı API'sidir.
Ekran dışı dokümanlar olarak yüklenen sayfalar, diğer uzantı sayfası türlerinden farklı şekilde işlenir.
Uzantının izinleri, ekran dışı dokümanlara da uygulanır ancak uzantı API'si erişimi sınırlıdır. Örneğin, browser.runtime API, ekran dışı belgeler tarafından desteklenen tek uzantı API'si olduğundan mesajlaşma, bu API'nin üyeleri kullanılarak yapılmalıdır.
Ekran dışı dokümanların normal sayfalardan farklı davrandığı diğer durumlar şunlardır:
- Ekran dışı dokümanın URL'si, uzantıyla birlikte gelen statik bir HTML dosyası olmalıdır.
- Ekran dışı dokümanlara odaklanılamaz.
- Ekran dışı doküman,
windowörneğidir ancakopenerözelliğinin değeri her zamannullolur. - Bir uzantı paketi birden fazla ekran dışı doküman içerebilse de yüklü bir uzantının aynı anda yalnızca bir dokümanı açık olabilir. Uzantı, etkin bir gizli profille bölünmüş modda çalışıyorsa normal ve gizli profillerin her birinde bir ekran dışı doküman bulunabilir.
Ekran dışı doküman oluşturmak ve kapatmak için browser.offscreen.createDocument() ve browser.offscreen.closeDocument() API'lerini kullanın. createDocument() için belgenin url, bir neden ve bir gerekçe gerekir:
browser.offscreen.createDocument({
url: 'off_screen.html',
reasons: ['CLIPBOARD'],
justification: 'reason for needing the document',
});
Nedenler
Geçerli nedenlerin listesi için Nedenler bölümüne bakın. Nedenler, dokümanın kullanım ömrünü belirlemek için doküman oluşturma sırasında ayarlanır. AUDIO_PLAYBACK nedeni, dokümanın ses çalmadan 30 saniye sonra kapanmasını sağlar. Diğer tüm nedenler, yaşam boyu sınırları belirlemez.
Örnekler
Ekran dışı dokümanın yaşam döngüsünü yönetme
Aşağıdaki örnekte, ekran dışı bir dokümanın mevcut olduğundan nasıl emin olunacağı gösterilmektedir. setupOffscreenDocument() işlevi, mevcut bir ekran dışı dokümanı bulmak için runtime.getContexts() işlevini çağırır veya mevcut değilse dokümanı oluşturur.
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;
}
}
Ekran dışı bir dokümana mesaj göndermeden önce, aşağıdaki örnekte gösterildiği gibi dokümanın mevcut olduğundan emin olmak için setupOffscreenDocument() yöntemini çağırın.
browser.action.onClicked.addListener(async () => {
await setupOffscreenDocument('off_screen.html');
// Send message to offscreen document
browser.runtime.sendMessage({
type: '...',
target: 'offscreen',
data: '...'
});
});
Eksiksiz örnekler için GitHub'daki offscreen-clipboard ve offscreen-dom demolarına bakın.
Chrome 116'dan önce: Ekran dışı bir dokümanın açık olup olmadığını kontrol etme
runtime.getContexts(), Chrome 116'ya eklendi. Chrome'un önceki sürümlerinde, mevcut bir ekran dışı dokümanı kontrol etmek için clients.matchAll() kullanın:
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);
});
}
}
Türler
CreateParameters
Özellikler
-
gerekçe
dize
Geliştirici tarafından sağlanan ve arka plan bağlamı ihtiyacını daha ayrıntılı açıklayan bir dize. Kullanıcı aracısı, bunu kullanıcıya göstermek için _kullanabilir_.
-
neden
Neden[]
Uzantının ekran dışı dokümanı oluşturma nedenleri.
-
url
dize
Dokümana yüklenecek (göreli) URL.
Reason
Enum
"TESTING"
Yalnızca test amacıyla kullanılan bir neden.
"AUDIO_PLAYBACK"
Ekran dışı dokümanın ses çalmaktan sorumlu olduğunu belirtir.
"IFRAME_SCRIPTING"
Ekran dışı dokümanın, içeriğini değiştirmek için bir iFrame yerleştirmesi ve komut dosyası oluşturması gerektiğini belirtir.
"DOM_SCRAPING"
Ekran dışı dokümanın bir iframe yerleştirmesi ve bilgi ayıklamak için DOM'unu kazıması gerektiğini belirtir.
"BLOBS"
Ekran dışı dokümanın Blob nesneleriyle (URL.createObjectURL() dahil) etkileşim kurması gerektiğini belirtir.
"DOM_PARSER"
Ekran dışı dokümanın DOMParser API'yi kullanması gerektiğini belirtir.
"USER_MEDIA"
Ekran dışı dokümanın, kullanıcı medyasından gelen medya akışlarıyla (ör. getUserMedia()) etkileşim kurması gerektiğini belirtir.
"DISPLAY_MEDIA"
Ekran dışı dokümanın, ekran medyasındaki medya akışlarıyla (ör. getDisplayMedia()) etkileşim kurması gerektiğini belirtir.
"WEB_RTC"
Ekran dışı dokümanın WebRTC API'lerini kullanması gerektiğini belirtir.
"CLIPBOARD"
Ekran dışı dokümanın Clipboard API ile etkileşim kurması gerektiğini belirtir.
"LOCAL_STORAGE"
Ekran dışı dokümanın localStorage'a erişmesi gerektiğini belirtir.
"WORKERS"
Ekran dışı dokümanın çalışanlar oluşturması gerektiğini belirtir.
"BATTERY_STATUS"
Ekran dışı dokümanın navigator.getBattery kullanması gerektiğini belirtir.
"MATCH_MEDIA"
Ekran dışı dokümanın window.matchMedia kullanması gerektiğini belirtir.
"GEOLOCATION"
Ekran dışı dokümanın navigator.geolocation kullanması gerektiğini belirtir.
Yöntemler
closeDocument()
browser.offscreen.closeDocument(): Promise<void>
Uzantı için açık olan ekran dışı dokümanı kapatır.
İadeler
-
Promise<void>
Ekran dışı doküman kapatıldığında çözümlenen Promise.
createDocument()
browser.offscreen.createDocument(
parameters: CreateParameters,
): Promise<void>
Uzantı için yeni bir ekran dışı doküman oluşturur.
Parametreler
-
parametreler
Oluşturulacak ekran dışı dokümanı açıklayan parametreler.
İadeler
-
Promise<void>
Ekran dışı belge oluşturulduğunda ve ilk sayfa yüklemesini tamamladığında çözümlenen Promise.
hasDocument()
browser.offscreen.hasDocument(): Promise<boolean>
Uzantının etkin bir dokümanı olup olmadığını belirler.
İadeler
-
Promise<boolean>
Uzantının etkin bir ekran dışı dokümanı olup olmadığına dair sonuçla çözümlenen Promise.