chrome.devtools.inspectedWindow

说明

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

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

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

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

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

清单

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

"devtools_page"

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

借助 eval 方法，扩展程序可以在被检查页面的上下文中执行 JavaScript 代码。在正确的上下文中，此方法非常强大；如果使用不当，则非常危险。除非您需要 that the eval method provides.，否则请使用 tabs.executeScript method unless you need the specific functionality

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

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

注意：由于上述安全考虑，如果不需要访问被检查页面的 JavaScript 状态，则首选使用scripting.executeScript 方法，以便扩展程序访问被检查页面的 DOM 数据。

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

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

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

frameURL

用于指定被检查页面的主框架以外的框架。

contextSecurityOrigin

用于根据指定框架的网站源选择该框架中的上下文。

useContentScriptContext

如果为 true，则在与扩展程序的内容脚本相同的上下文中执行脚本。（相当于将扩展程序自己的网站源指定为上下文安全来源。）这可用于与内容脚本交换数据。

示例

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

chrome.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>

    待处理

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

• setContent

  void

  设置资源的内容。

  setContent 函数如下所示：

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

  • 内容

    字符串

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

  • 提交

    布尔值

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

  • 返回

    Promise<object>

    待处理

    请求完成时调用的函数。

属性

tabId

被检查标签页的 ID。此 ID 可与 chrome.tabs.* API 搭配使用。

类型

数值

方法

eval()

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

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

参数

• 表达式

  字符串

  要评估的表达式。

• 选项

  对象（可选）

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

  • frameURL

    字符串 （可选）

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

  • scriptExecutionContext

    字符串 （可选）

    Chrome 107 及更高版本

    在与指定来源匹配的扩展程序的内容脚本的上下文中评估表达式。如果给定，scriptExecutionContext 会替换 useContentScriptContext 上的“true”设置。

  • useContentScriptContext

    布尔值（可选）

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

返回

• Promise<object>

  待处理

  评估完成时调用的函数。

getResources()

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

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

返回

• Promise<Resource[]>

  待处理

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

reload()

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

重新加载被检查的页面。

参数

• reloadOptions

  对象（可选）

  • ignoreCache

    布尔值（可选）

    如果为 true，加载程序将绕过在触发 load 事件之前加载的所有被检查页面资源的缓存。效果类似于在被检查的窗口或开发者工具窗口中按 Ctrl+Shift+R。

  • injectedScript

    字符串 （可选）

    如果指定，脚本将在加载后立即注入到被检查页面的每个框架中，并且在任何框架的脚本之前注入。脚本不会在后续重新加载后注入，例如，如果用户按 Ctrl+R。

  • userAgent

    字符串 （可选）

    如果指定，该字符串将替换在加载被检查页面的资源时发送的 User-Agent HTTP 标头的值。该字符串还将替换返回给在被检查页面中运行的任何脚本的 navigator.userAgent 属性的值。

事件

onResourceAdded

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

当新资源添加到被检查的页面时触发。

参数

• callback

  函数

  callback 参数如下所示：

  (resource: Resource) => void

  • 资源

    资源

onResourceContentCommitted

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

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

参数

• callback

  函数

  callback 参数如下所示：

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

  • 资源

    资源

  • 内容

    字符串