说明
使用 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 之前：检查屏幕外文档是否已打开
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 matchedClients.some(client => {
return 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”
指定了离屏文档需要衍生工作器。
“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>