说明
使用 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 是唯一
屏幕外文档支持的 Extensions 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 原因设置
关闭文档。所有其他原因无需设置有效期限制。
示例
维护屏幕外文档的生命周期
以下示例展示了如何确保存在屏幕外文档。通过
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-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 await matchedClients.some(client => {
client.url.includes(chrome.runtime.id);
});
}
}
类型
CreateParameters
属性
-
两端对齐
字符串
开发者提供的字符串，用于更详细地说明对后台上下文的需求。用户代理_可以_向用户显示这些信息。
-
个原因
原因[]
扩展程序创建屏幕外文档的原因。
-
网址
字符串
要在文档中加载的（相对）网址。
Reason
枚举
"TESTING"
仅用于测试目的的原因。
"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
函数（可选）
callback参数如下所示：() => void
返回
-
承诺<void>
Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
createDocument()
chrome.offscreen.createDocument(
parameters: CreateParameters,
callback?: function,
)
为扩展程序创建新的屏幕外文档。
参数
-
描述要创建的屏幕外文档的参数。
-
callback
函数（可选）
callback参数如下所示：() => void
返回
-
承诺<void>
Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
