chrome.offscreen

Açıklama

İzinler

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

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

Kullanılabilirlik

Kavramlar ve kullanım

Service worker'lar DOM erişimine sahip değildir ve birçok web sitesinde içerik komut dosyalarının işlevselliğini sınırlayan içerik güvenlik politikaları bulunur. Offscreen API, uzantının yeni pencereler veya sekmeler açarak kullanıcı deneyimini kesintiye uğratmadan DOM API'lerini gizli bir dokümanda kullanmasına olanak tanır. runtime API, ekran dışı dokümanlar tarafından desteklenen tek uzantı API'sidir.

Ekran dışında 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 aktarılır ancak uzantı API'sine erişim sınırlıdır. Örneğin, chrome.runtime API, ekran dışı dokümanlar 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ışında kalan bir dokümanın URL'si, uzantıyla birlikte paketlenmiş statik bir HTML dosyası olmalıdır.
• Ekran dışında kalan dokümanlara odaklanılamaz.
• Ekran dışı belge, window örneğidir ancak opener özelliğinin değeri her zaman null olur.
• Bir uzantı paketi birden fazla ekran dışı belge içerebilse de, yüklenen bir uzantı aynı anda yalnızca bir belge açabilir. Uzantı, etkin bir gizli profil ile bölünmüş modda çalışıyorsa normal ve gizli profillerin her birinde birer tane ekran dışı doküman olabilir.

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

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, belgenin kullanım ömrünü belirlemek için belge oluşturma sırasında ayarlanır. AUDIO_PLAYBACK nedeni, belgeyi 30 saniye sonra ses çalmadan kapanacak şekilde ayarlar. Diğer tüm nedenler, yaşam boyu sınırları ayarlamaz.

Örnekler

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

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

Ekranda görünmeyen 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() işlevini ç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ışında bir dokümanın açık olup olmadığını kontrol etme

runtime.getContexts(), Chrome 116'da eklendi. Chrome'un önceki sürümlerinde, ekran dışında mevcut bir doküman olup olmadığını kontrol etmek için clients.matchAll() simgesini 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 matchedClients.some(client => {
      return client.url.includes(chrome.runtime.id);
    });
  }
}

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

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