browser.devtools.inspectedWindow

说明

使用 chrome.devtools.inspectedWindow API 与被检查的窗口进行交互：获取被检查页面的标签页 ID、在被检查窗口的上下文中评估代码、重新加载页面或获取页面中的资源列表。

如需简要了解如何使用开发者工具 API，请参阅开发者工具 API 摘要。

tabId 属性提供可与 browser.tabs.* API 调用搭配使用的标签页标识符。不过，出于安全考虑，browser.tabs.* API 不会向开发者工具扩展程序页面公开，您需要将标签页 ID 传递给后台页面，并从该页面调用 browser.tabs.* API 函数。

reload 方法可用于重新加载被检查的页面。此外，调用方还可以指定用户代理字符串的替换值、在网页加载时尽早注入的脚本，或强制重新加载缓存资源的选项。

使用 getResources 调用和 onResourceContent 事件可获取所检查页面中的资源（文档、样式表、脚本、图片等）列表。Resource 类的 getContent 和 setContent 方法以及 onResourceContentCommitted 事件可用于支持修改资源内容，例如通过外部编辑器进行修改。

清单

必须在清单中声明以下键，才能使用此 API。

"devtools_page"

在被检查的窗口中执行代码

eval 方法使扩展程序能够在被检查页面的上下文中执行 JavaScript 代码。此方法在适当的环境中使用时功能强大，但在不当使用时会很危险。除非您需要 eval 方法提供的特定功能，否则请使用 tabs.executeScript 方法。

以下是 eval 和 tabs.executeScript 方法之间的主要区别：

  • eval 方法不会为要评估的代码使用隔离的世界，因此代码可以访问所检查窗口的 JavaScript 状态。当需要访问被检查页面的 JavaScript 状态时，请使用此方法。
  • 所评估代码的执行上下文包含 开发者工具控制台 API。例如，代码可以使用 inspect 和 $0。
  • 评估的代码可能会返回一个值，该值会传递给扩展程序回调。返回的值必须是有效的 JSON 对象（只能包含原始 JavaScript 类型和对其他 JSON 对象的非循环引用）。处理从被检查页面接收的数据时，请格外小心，因为执行上下文基本上由被检查页面控制；恶意页面可能会影响返回给扩展程序的数据。

请注意，一个网页可以包含多个不同的 JavaScript 执行上下文。每个框架都有自己的上下文，此外，每个在该框架中运行内容脚本的扩展程序都有一个额外的上下文。

默认情况下，eval 方法在被检查网页的主框架上下文中执行。

eval 方法接受一个可选的第二个参数，您可以使用该参数指定代码的求值上下文。此 options 对象可以包含以下一个或多个键：

frameURL
用于指定所检查网页的主框架以外的框架。
contextSecurityOrigin
用于根据网站源在指定框架内选择上下文。
useContentScriptContext
如果为 true，则在与扩展程序的内容脚本相同的上下文中执行脚本。（相当于将扩展程序自己的网站源指定为上下文安全源。）这可用于与内容脚本交换数据。

示例

以下代码会检查被检查页面使用的 jQuery 版本：

browser.devtools.inspectedWindow.eval(
  "jQuery.fn.jquery",
  function(result, isException) {
    if (isException) {
      console.log("the page is not using jQuery");
    } else {
      console.log("The page is using jQuery v" + result);
    }
  }
);

如需试用此 API，请从 chrome-extension-samples 代码库中安装 devtools API 示例。

类型

Resource

所检查网页中的资源，例如文档、脚本或图片。

属性

  • 网址

    字符串

    资源的网址。

  • getContent

    void

    获取资源的内容。

    getContent 函数如下所示： 

    () => {...}

    • 返回

      Promise<object>

      Chrome 151 及更高版本 browser.*（自 Chrome 152 起）

      在请求完成时接收资源内容的函数。

  • setContent

    void

    设置资源的内容。

    setContent 函数如下所示： 

    (content: string, commit: boolean) => {...}

    • 内容

      字符串

      资源的新内容。目前仅支持文本类型的资源。

    • 提交

      布尔值

      如果用户已完成对资源的修改，并且应保留资源的新内容，则为 true；如果这是在用户修改资源的过程中发送的细微更改，则为 false。

    • 返回

      Promise<object>

      Chrome 151 及更高版本 browser.*（自 Chrome 152 起）

      请求完成时调用的函数。

属性

tabId

正在检查的标签页的 ID。此 ID 可与 chrome.tabs.* 请求类型

类型

数值

方法

eval()

browser.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
): Promise<object>

在所检查网页的主框架上下文中评估 JavaScript 表达式。表达式的求值结果必须是符合 JSON 规范的对象，否则会抛出异常。eval 函数可以报告 DevTools 端错误或求值期间发生的 JavaScript 异常。在任何一种情况下，回调的 result 参数均为 undefined。如果发生开发者工具端错误，isException 参数不为 null，且 isError 设置为 true，code 设置为错误代码。如果发生 JavaScript 错误，isException 会设置为 true，value 会设置为所抛出对象的字符串值。

参数

  • 表达式

    字符串

    要计算的表达式。

  • 选项

    对象（可选）

    options 参数可以包含一个或多个选项。

    • frameURL

      字符串 可选

      如果指定，则系统会在网址与指定网址匹配的 iframe 上评估表达式。默认情况下，系统会在被检查页面的顶层框架中对表达式求值。

    • scriptExecutionContext

      字符串 可选

      Chrome 107 及更高版本 browser.*（自 Chrome 152 起）

      在与指定来源匹配的扩展程序的内容脚本上下文中对表达式求值。如果指定了 scriptExecutionContext，则会覆盖 useContentScriptContext 上的“true”设置。

    • useContentScriptContext

      布尔值 （可选）

      在调用扩展程序的内容脚本的上下文中评估表达式，前提是内容脚本已注入到被检查的页面中。否则，系统不会对表达式求值，并且会调用回调函数，其中异常参数设置为一个对象，该对象的 isError 字段设置为 true，code 字段设置为 E_NOTFOUND。

返回

  • Promise<object>

    Chrome 151 及更高版本 browser.*（自 Chrome 152 起）

    评估完成时调用的函数。

getResources()

browser.devtools.inspectedWindow.getResources(): Promise<Resource[]>

从被检查的页面中检索资源列表。

返回

  • Promise<Resource[]>

    Chrome 151 及更高版本 browser.*（自 Chrome 152 起）

    在请求完成时接收资源列表的函数。

reload()

browser.devtools.inspectedWindow.reload(
  reloadOptions?: object,
): void

重新加载被检查的页面。

参数

  • reloadOptions

    对象（可选）

    • ignoreCache

      布尔值 （可选）

      如果为 true，则加载器会绕过缓存，加载在 load 事件触发之前加载的所有受检网页资源。其效果类似于在被检查的窗口或“开发者工具”窗口中按 Ctrl+Shift+R。

    • injectedScript

      字符串 可选

      如果指定了此参数，脚本将在加载时立即注入到被检查页面的每个框架中，并且在框架的任何脚本之前执行。在后续重新加载（例如，用户按 Ctrl+R）后，系统不会注入该脚本。

    • userAgent

      字符串 可选

      如果指定了此字符串，它将覆盖在加载所检查网页的资源时发送的 User-Agent HTTP 标头的值。该字符串还会覆盖返回给所检查页面内运行的任何脚本的 navigator.userAgent 属性值。

事件

onResourceAdded

browser.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

在向被检查页面添加新资源时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (resource: Resource) => void

onResourceContentCommitted

browser.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

在提交资源的新修订版本时触发（例如，用户在开发者工具中保存资源的修改版本）。

参数

  • callback

    函数

    callback 参数如下所示： 

    (resource: Resource, content: string) => void

    • 资源

      资源

    • 内容

      字符串