chrome.offscreen

Açıklama

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

İzinler

offscreen

Offscreen API kullanmak için uzantı manifestinde "offscreen" iznini beyan edin. Örneğin:

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

Kullanılabilirlik

Chrome 109 ve sonraki sürümler MV3+

Kavramlar ve kullanım

Service Worker'ların DOM erişimi yoktur ve birçok web sitesinin içerik güvenliği politikaları vardır. içerik komut dosyalarının işlevselliğini sınırlandırır. Offscreen API, uzantının DOM kullanmasına izin verir Yeni pencereler açarak veya oluşturarak kullanıcı deneyimini kesintiye uğratmadan gizli dokümanlardaki API'leri sekmelerinde görebilirsiniz. Uzantılar tek API runtime API'dir ekran dışı dokümanlar tarafından desteklenir.

Ekran dışı dokümanlar olarak yüklenen sayfalar, diğer uzantı sayfası türlerinden farklı şekilde işlenir. Uzantının izinleri ekran dışındaki dokümanlara aktarılır, ancak uzantı API'sinde sınırlamalar vardır erişim. Örneğin, tek başına chrome.runtime API uzantılar API'si ekran dışı dokümanlar tarafından desteklenir, mesajlar işlenmelidir bu API'nin üyelerini kullanabilirsiniz.

Aşağıda, ekran dışı dokümanların normal sayfalardan farklı davrandığı diğer durumlar verilmiştir:

  • Ekran dışı dokümanın URL'si, uzantıyla birlikte gruplanmış 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çerse de, yüklenen bir uzantı yalnızca aynı anda bir tane açık olmalıdır. Uzantı çalışıyorsa bölünmüş moddayken, normal ve gizli profillerin her biri tek bir ekran dışı dokümana sahip olabilir.

chrome.offscreen.createDocument() ve Ekran dışı bir resim oluşturup kapatmak için chrome.offscreen.closeDocument() uygulayacaksınız. createDocument() için doküman url, bir neden ve gerekçe gereklidir:

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. Nedenler şu koşulda belirtilir: dokümanın kullanım ömrünü belirlemek üzere doküman oluşturma sürecidir. AUDIO_PLAYBACK nedeni, dokümanın 30 saniye boyunca ses çalınmadan kapanmasını sağlar. Diğer tüm nedenler için ömür boyu sınır koyulmaz.

Örnekler

Ekran dışındaki bir 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. İlgili içeriği oluşturmak için kullanılan setupOffscreenDocument() işlevi, şunu bulmak için runtime.getContexts() komutunu çağırır mevcut bir ekran dışı dokümanı seçer veya doküman mevcut değilse 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 öncesetupOffscreenDocument() doküman mevcut olmalıdır.

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

  // Send message to offscreen document
  chrome.runtime.sendMessage({
    type: '...',
    target: 'offscreen',
    data: '...'
  });
});

Tüm örnekler için ekran dışı pano GitHub'da offscreen-dom demoları yapabilirsiniz.

Chrome 116'dan önce: Ekran dışındaki bir dokümanın açık olup olmadığını kontrol etme

runtime.getContexts(), Chrome 116 sürümünde eklendi. Önceki sürümlerinde Chrome, clients.matchAll() kullan mevcut bir ekran dışı dokümanı kontrol etmek için:

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ına duyulan ihtiyacı daha ayrıntılı olarak açıklayan ve 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 nedeni.

  • url

    dize

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

Reason

Enum

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

"AUDIO_PLAYBACK"
Ekran dışındaki dokümanın ses çalmaktan sorumlu olduğunu belirtir.

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

"DOM_SCRAPING"
Bilgileri ayıklamak için ekran dışı dokümanın bir iframe yerleştirmesi ve DOM'sini 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ışındaki dokümanın DOMParser API'yi kullanması gerektiğini belirtir.

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

"DISPLAY_MEDIA"
Ekran dışındaki dokümanın, görüntülü medyadan (ör. getDisplayMedia()) medya akışlarıyla etkileşim kurması 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şim kurması gerektiğini belirtir.

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

"WORKERS"
Ekran dışındaki dokümanın çalışan oluşturması gerektiğini belirtir.

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

"MATCH_MEDIA"
Ekran dışındaki dokümanın window.matchMedia kullanması gerektiğini belirtir.

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

Yöntemler

closeDocument()

Söz 'nı inceleyin.
chrome.offscreen.closeDocument(
  callback?: function,
)

Uzantıya ilişkin o anda açık olan ekran dışı dokümanı kapatır.

Parametreler

  • geri çağırma

    işlev isteğe bağlı

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

    () => void

İadeler

  • Taahhüt<void>

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

createDocument()

Söz 'nı inceleyin.
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

    işlev isteğe bağlı

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

    () => void

İadeler

  • Taahhüt<void>

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.