chrome.offscreen

Açıklama

Ekran dışı dokümanlar oluşturmak ve yönetmek için offscreen API'yi kullanın.

İzinler

offscreen

Offscreen API'yi kullanmak için uzantı manifestinde "offscreen" iznini tanımlayın. Örneğin:

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

Kullanılabilirlik

Chrome 109 ve sonraki sürümler MV3 ve sonraki sürümler

Kavramlar ve kullanım

Service Worker'ların DOM erişimi yoktur ve birçok web sitesi, içerik komut dosyalarının işlevlerini sınırlayan içerik güvenliği politikalarına sahiptir. 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üman olarak yüklenen sayfalar, diğer uzantı sayfalarından farklı şekilde işlenir. Uzantının izinleri ekran dışı dokümanlara aktarılır ancak uzantı API erişimiyle ilgili sınırlar uygulanır. Örneğin, chrome.runtime API ekran dışı belgeler tarafından desteklenen tek uzantı API'si olduğundan mesajlar, bu API'nin üyeleri kullanılarak ele alınmalıdır.

Ekran dışı dokümanların normal sayfalardan farklı olarak davrandığı diğer noktalar şunlardır:

  • Ekran dışındaki bir dokümanın URL'si, uzantıyla birlikte gelen statik bir HTML dosyası olmalıdır.
  • Ekran dışındaki dokümanlara odaklanılamaz.
  • Ekran dışı doküman, window öğesinin bir örneğidir ancak opener özelliğinin değeri her zaman null olur.
  • Bir uzantı paketi birden fazla ekran dışı doküman içerebilir, ancak yüklenen bir uzantıda aynı anda yalnızca bir tane açık olabilir. Uzantı, etkin bir gizli profille bölünmüş modda çalışıyorsa normal ve gizli profillerin her birinde bir tane ekran dışı doküman olabilir.

Ekran dışı doküman oluşturmak ve kapatmak için chrome.offscreen.createDocument() ve chrome.offscreen.closeDocument() araçlarını kullanın. createDocument(), doküman için url, neden ve gerekçe gerektiriyor:

chrome.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. Belgenin kullanım ömrünü belirlemek için, doküman oluşturulurken nedenler belirlenir. AUDIO_PLAYBACK nedeni, dokümanı ses çalınmadan 30 saniye sonra kapanacak şekilde ayarlar. Diğer nedenlerin hiçbiri ömür boyu sınır belirlemez.

Örnekler

Ekran dışı bir dokümanın yaşam döngüsünü koruma

Aşağıdaki örnekte, ekran dışı bir dokümanın nasıl sağlanacağı gösterilmektedir. setupOffscreenDocument() işlevi, mevcut bir ekran dışı dokümanı bulmak için runtime.getContexts() yöntemini çağırır veya dokümanı zaten yoksa 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 = 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;
  }
}

Ekran dışındaki 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() öğesini çağırın.

chrome.action.onClicked.addListener(async () => {
  await setupOffscreenDocument('off_screen.html');

  // Send message to offscreen document
  chrome.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 sürümünde eklendi. Chrome'un önceki sürümlerinde, ekran dışı mevcut bir doküman olup olmadığını kontrol etmek için clients.matchAll()'i kullanın:

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);
    });
  }
}

Türler

CreateParameters

Özellikler

  • iki yana yaslama

    dize

    Arka plan bağlamı ihtiyacını daha ayrıntılı olarak açıklayan, geliştirici tarafından sağlanan bir dize. Kullanıcı aracısı _may_ bunu kullanıcıya göstermek için kullanır.

  • neden

    Neden[]

    Uzantının ekran dışı dokümanı oluşturma nedenleri.

  • url

    dize

    Dokümanda yüklenecek (göreli) URL.

Reason

Enum

"TEST"
Yalnızca test amaçlı kullanılan bir neden.

"AUDIO_PLAYBACK"
Ses çalmadan ekran dışı dokümanın sorumlu olduğunu belirtir.

"IFRAME_SCRIPTING"
iframe'in içeriğini değiştirebilmek için ekran dışı dokümanın bir iframe yerleştirmesi ve komut dosyası yazması gerektiğini belirtir.

"DOM_SCRAPING"
Bilgilerin ayıklanması için ekran dışı dokümanın bir iframe yerleştirmesi ve DOM'sini kazıması gerektiğini belirtir.

"BLOBS"
Ekran dışındaki dokümanın Blob nesneleri (URL.createObjectURL() dahil) ile etkileşimde bulunması gerektiğini belirtir.

"DOM_PARSER"
Ekran dışındaki dokümanın DOMParser API'yi kullanması gerektiğini belirtir.

"USER_MEDIA"
Ekran dışındaki dokümanın, kullanıcının medyasındaki (ör. getUserMedia()) medya akışlarıyla etkileşimde bulunması gerektiğini belirtir.

"DISPLAY_MEDIA"
Ekran dışındaki dokümanın görüntülü medyadan (ör. getDisplayMedia()) medya akışlarıyla etkileşimde bulunması gerektiğini belirtir.

"WEB_RTC"
Ekran dışındaki dokümanın WebRTC API'lerini kullanması gerektiğini belirtir.

"CLIPBOARD"
Ekran dışındaki dokümanın Clipboard API ile etkileşime geçmesi gerektiğini belirtir.

"LOCAL_STORAGE"
Ekran dışındaki dokümanın localStorage'a erişmesi gerektiğini belirtir.

"İŞÇİLER"
Ekran dışı dokümanın çalışan oluşturması gerektiğini belirtir.

"BATTERY_STATUS"
Ekran dışı dokümanın navigator.getBattery kullanması gerektiğini belirtir.

"MATCH_MEDIA"
Ekran dışı dokümanda window.matchMedia'yı kullanması gerektiğini belirtir.

"GEOLOCATION"
Ekran dışındaki dokümanın navigator.geolocation kullanması gerektiğini belirtir.

Yöntemler

closeDocument()

Söz 
chrome.offscreen.closeDocument(
  callback?: function,
)

Uzantı için o anda açık olan ekran dışı dokümanını kapatır.

Parametreler

  • geri çağırma

    Functions (isteğe bağlı)

    callback parametresi şu şekilde görünür: 

    ()=>void

İlerlemeler

  • Promise<void>

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

createDocument()

Söz 
chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)

Uzantı için yeni bir ekran dışı doküman oluşturur.

Parametreler

  • Parametreler

    CreateParameters

    Oluşturulacak ekran dışı dokümanı açıklayan parametreler.

  • geri çağırma

    Functions (isteğe bağlı)

    callback parametresi şu şekilde görünür: 

    ()=>void

İlerlemeler

  • Promise<void>

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.