此页面由 Cloud Translation API 翻译。

chrome.offscreen

说明

使用 offscreen API 创建和管理屏幕外文档。

权限

offscreen

如需使用 Offscreen API，请在扩展程序清单中声明 "offscreen" 权限。例如：

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

可用性

Chrome 109 及更高版本 MV3+

概念和用法

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

<ph type="x-smartling-placeholder"></ph> 承诺

chrome.offscreen.closeDocument(
  callback?: function,
)

关闭扩展程序当前打开的屏幕外文档。

参数

callback

函数（可选）

callback 参数如下所示：
```
() => void
```

承诺<void>

Manifest V3 及更高版本支持 Promise，但为以下项目提供回调：向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

createDocument()