說明
使用 offscreen API 建立及管理螢幕外文件。
權限
offscreen如要使用 Offscreen API，請在擴充功能資訊清單中宣告 "offscreen" 權限。例如：
{
"name": "My extension",
...
"permissions": [
"offscreen"
],
...
}
可用性
概念和用法
服務工作人員沒有 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 的「螢幕外」示範。
Chrome 116 以下版本：檢查螢幕外的文件是否已開啟
已將 runtime.getContexts() 新增至 Chrome 116。舊版
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
屬性
-
理由
字串
開發人員提供的字串，詳細說明對背景內容的需求。使用者代理程式「可能」_會向使用者顯示這個元素。
-
原因
原因[]
擴充功能製作畫面外文件的原因。
-
網址
字串
要在文件中載入的 (相對) 網址。
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"
指定螢幕外文件需生成 worker。
"BATTERY_STATUS"
指定螢幕外文件需要使用 navigator.getBattery。
"MATCH_MEDIA"
指定畫面外文件必須使用 window.matchMedia。
"GEOLOCATION"
指定螢幕外文件必須使用 navigator.geolocation。
方法
closeDocument()
chrome.offscreen.closeDocument(
callback?: function,
)
關閉擴充功能目前在畫面外開啟的文件。
參數
-
回呼
函式 選用
callback參數如下所示：() => void
傳回
-
承諾<void>
Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
callback?: function,
)
建立新的擴充功能畫面外文件。
參數
-
parameters
說明要建立的螢幕外文件的參數。
-
回呼
函式 選用
callback參數如下所示：() => void
傳回
-
承諾<void>
Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。