chrome.offscreen

說明

使用 offscreen API 建立及管理螢幕外文件。

權限

offscreen

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

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

可用性

Chrome 109 以上版本 MV3 以上版本

概念與用途

服務工作人員無法存取 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 matchedClients.some(client => {       return client.url.includes(chrome.runtime.id);     });   } }

類型

CreateParameters

屬性

  • 理由

    字串

    開發人員提供的字串，詳細說明需要背景脈絡的原因。使用者代理程式「可能」會在向使用者顯示內容時使用這項資訊。

  • 原因

    原因[]

    擴充功能建立螢幕外文件的原因。

  • 網址

    字串

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

Reason

列舉

「TESTING」(測試)
「A reason used for testing purposes only」(僅供測試之用)。

「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()

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

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

傳回

  • Promise<void>

createDocument()

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

為擴充功能建立新的螢幕外文件。

參數

傳回

  • Promise<void>