chrome.devtools.inspectedWindow

说明

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

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

tabId 属性提供可用于 chrome.tabs.* API 调用的标签页标识符。不过，请注意，出于安全考虑，chrome.tabs.* API 不会向开发者工具扩展程序页面公开，您需要将标签页 ID 传递给后台页面，并从该页面调用 chrome.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 方法接受一个可选的第二个实参，您可以使用该实参指定代码的评估上下文。此选项对象可以包含以下一个或多个键：

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 函数如下所示： 

    (callback: function) => {...}

    • callback

      函数

      callback 参数如下所示： 

      (content: string, encoding: string) => void

      • 内容

        字符串

        资源的内容（可能已编码）。

      • encoding

        字符串

        如果内容未编码，则为空；否则为编码名称。目前只支持 base64。

  • setContent

    void

    设置资源的内容。

    setContent 函数如下所示： 

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

    • 内容

      字符串

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

    • 提交

      布尔值

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

    • callback

      函数 可选

      callback 参数如下所示： 

      (error?: object) => void

      • 错误

        对象（可选）

        如果资源内容设置成功，则设为 undefined；否则描述错误。

属性

tabId

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

类型

数值

方法

eval()

chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
): void

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

参数

  • 表达式

    字符串

    要评估的表达式。

  • 选项

    对象（可选）

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

    • frameURL

      字符串 可选

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

    • scriptExecutionContext

      字符串 可选

      Chrome 107 及更高版本

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

    • useContentScriptContext

      布尔值 （可选）

      在调用扩展程序的内容脚本的上下文中评估表达式，前提是内容脚本已注入到检查的网页中。如果不是，则不评估表达式，并调用回调，且异常形参设置为一个对象，该对象的 isError 字段设置为 true，code 字段设置为 E_NOTFOUND。

  • callback

    函数 可选

    callback 参数如下所示： 

    (result: object, exceptionInfo: object) => void

    • 结果

      对象

      评估结果。

    • exceptionInfo

      对象

      一个对象，用于在评估表达式时发生异常时提供详细信息。

      • 代码

        字符串

        如果错误发生在开发者工具端，且在表达式求值之前，则进行设置。

      • 说明

        字符串

        如果错误发生在开发者工具端，且在表达式求值之前，则进行设置。

      • 详细信息

        任何 []

        如果错误发生在表达式求值之前，则在 DevTools 端设置，包含可能替换到说明字符串中的值数组，以提供有关错误原因的更多信息。

      • isError

        布尔值

        如果错误发生在开发者工具端，且在表达式求值之前，则进行设置。

      • isException

        布尔值

        如果评估的代码产生未处理的异常，则设置此值。

      • 值

        字符串

        如果评估的代码产生未处理的异常，则设置此值。

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
): void

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (resources: Resource[]) => void

    • 资源

      资源[]

      网页中的资源。

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

    • 资源

      资源

    • 内容

      字符串