chrome.offscreen

說明

使用 offscreen API 建立及管理畫面外文件。

權限

offscreen

如要使用 Offscreen API，請在擴充功能資訊清單中宣告 "offscreen" 權限。例如：

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

適用國家/地區

Chrome 109 以上版本 MV3 以上版本

概念和用法

Service Worker 沒有 DOM 存取權，且許多網站的內容安全政策會限制內容指令碼的功能。Offscreen API 可讓擴充功能在隱藏文件中使用 DOM API，而且不會因為開啟新視窗或分頁而中斷使用者體驗。runtime API 是畫面外文件唯一支援的擴充功能 API。

以畫面外文件形式載入的網頁，處理方式與其他類型的擴充功能頁面不同。擴充功能的權限會沿用至螢幕外的文件，但對擴充功能 API 存取權設有限制。舉例來說，由於 chrome.runtime API 是畫面外文件唯一支援的擴充功能 API，因此訊息必須透過該 API 的成員來處理。

以下是畫面外文件與一般頁面的其他行為差異：

  • 畫面外文件的網址必須是隨附擴充功能的靜態 HTML 檔案。
  • 無法將焦點移至畫面外的文件。
  • 螢幕外文件是 window 的執行個體，但其 opener 屬性的值一律為 null。
  • 雖然擴充功能套件可以包含多個畫面外的文件，但已安裝的擴充功能一次只能開啟一個文件。如果擴充功能透過已啟用的無痕模式設定檔以分割模式執行，一般設定檔和無痕模式設定檔可以有一份畫面外文件。

使用 chrome.offscreen.createDocument() 和 chrome.offscreen.closeDocument() 建立及關閉螢幕外文件。createDocument() 需要文件的 url、原因和理由：

chrome.offscreen.createDocument({
  url: 'off_screen.html',
  reasons: ['CLIPBOARD'],
  justification: 'reason for needing the document',
});

原因

如需實際原因清單，請參閱「原因」一節。系統會在建立文件時設定原因，以確定文件的效期。AUDIO_PLAYBACK 原因會將文件設為在 30 秒後關閉，且未播放音訊。其餘原因則不受生命週期限制。

示例

維持畫面外文件的生命週期

以下範例說明如何確保文件外存在文件。setupOffscreenDocument() 函式會呼叫 runtime.getContexts() 尋找現有的畫面外文件，如果文件不存在，則會建立文件。

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

將訊息傳送至螢幕外的文件之前，請先呼叫 setupOffscreenDocument() 確保文件存在，如以下範例所示。

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

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

如需完整範例，請參閱 GitHub 上的「offscreen-clipboard」和「offscreen-dom」示範。

適用於 Chrome 116 之前的版本：檢查畫面外的文件是否為開啟狀態

已在 Chrome 116 中新增 runtime.getContexts()。在舊版 Chrome 中，請使用 clients.matchAll() 檢查現有的畫面外文件：

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

類型

CreateParameters

屬性

  • 理由

    字串

    開發人員提供的字串，詳細解釋了背景背景資訊的需求。使用者代理程式「可」會使用這個 ID 向使用者顯示。

  • 原因

    原因[]

    擴充功能建立畫面外文件的原因。

  • url

    字串

    要在文件中載入的 (相對) 網址。

Reason

列舉

"測試"
僅供測試的原因。

"AUDIO_PLAYBACK"
指定螢幕外文件負責播放音訊。

"IFRAME_ScriptING"
指定螢幕外文件必須嵌入 iframe 並編寫指令碼，才能修改 iframe 的內容。

"DOM_SCRAPING"
指定畫面外文件必須嵌入 iframe 並抓取其 DOM 以擷取資訊。

"BLOBS"
指定畫面外文件需要與 Blob 物件互動 (包括 URL.createObjectURL())。

"DOM_PARSER"
指定螢幕外文件必須使用 DOMParser API。

"USER_MEDIA"
指定螢幕外文件需要與來自使用者媒體 (例如 getUserMedia()) 的媒體串流互動。

"DISPLAY_MEDIA"
指定螢幕外文件需要與來自顯示媒體的媒體串流 (例如 getDisplayMedia()) 互動。

"WEB_RTC"
指定畫面外文件必須使用 WebRTC API。

"CLIPBOARD"
指定畫面外文件需要與 Clipboard API 互動。

"LOCAL_STORAGE"
指定螢幕外文件需要存取 localStorage。

"WORKERS"
指定螢幕外文件必須產生工人。

"BATTERY_STATUS"
指定螢幕外文件必須使用 navigator.getBattery。

"MATCH_MEDIA"
指定畫面外文件需要使用 window.matchMedia。

"GEOLOCATION"
指出畫面外文件需要使用 navigator.geolocation。

方法

closeDocument()

Promise 
chrome.offscreen.closeDocument(
  callback?: function,
)

關閉擴充功能目前開啟的螢幕外文件。

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

createDocument()

Promise 
chrome.offscreen.createDocument(
  parameters: CreateParameters,
  callback?: function,
)

為擴充功能建立新的畫面外文件。

參數

  • 用來描述要建立的畫面外文件的參數。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。