說明
使用 offscreen
API 建立及管理畫面外文件。
權限
offscreen
如要使用 Offscreen API,請在擴充功能資訊清單中宣告 "offscreen"
權限。例如:
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}
適用國家/地區
概念和用法
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()
chrome.offscreen.closeDocument(
callback?: function,
)
關閉擴充功能目前開啟的螢幕外文件。
參數
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
callback?: function,
)
為擴充功能建立新的畫面外文件。
參數
-
用來描述要建立的畫面外文件的參數。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。