chrome.devtools.inspectedWindow

说明

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

有关使用开发者工具 API 的一般说明，请参阅 DevTools API 摘要。

tabId 属性提供可与 chrome.tabs.* 一起使用的标签页标识符 API 调用。但请注意，chrome.tabs.* API 不会提供给开发者工具 扩展程序网页 - 您需要将标签页 ID 传递到后台 页面并从中调用 chrome.tabs.* API 函数。

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

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

清单

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

"devtools_page"

在检查的窗口中执行代码

eval 方法可让扩展程序在 所检查的网页。此方法在合适的上下文中使用时功能强大，使用时则有危险 不当。请使用 tabs.executeScript 方法，除非您需要特定功能 由 eval 方法提供的函数定义。

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

  • eval 方法不会为要评估的代码使用隔离世界，因此 JavaScript 代码可访问所检查窗口的状态。在访问 必须指定所检查网页的 JavaScript 状态。
  • 所评估代码的执行上下文包括 Developer Tools Console API。 例如，代码可以使用 inspect 和 $0。
  • 已评估的代码可能会返回传递给扩展回调的值。返回的值 必须是有效的 JSON 对象（可以只包含原始 JavaScript 类型和无环 对其他 JSON 对象的引用）。在处理所收到的数据时，请格外小心 从检查过的网页 - 执行上下文实质上由所检查的网页控制；一 可能会影响返回到扩展程序的数据。
。

请注意，一个页面可以包含多个不同的 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 中的 chrome-extension-samples 存储库

类型

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 配合使用。*Compute Engine API 来创建虚拟机实例。

类型

number

方法

eval()

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

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

参数

  • 表达式

    字符串

    要计算的表达式。

  • 选项

    对象（可选）

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

    • frameURL

      字符串（可选）

      如果指定，则系统会在网址与指定网址匹配的 iframe 上计算表达式。默认情况下，表达式将在所检查页面的顶部帧进行求值。

    • scriptExecutionContext

      字符串（可选）

      Chrome 107 及更高版本

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

    • useContentScriptContext

      布尔值（可选）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

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

    • 结果

      对象

      评估结果。

    • exceptionInfo

      对象

      在计算表达式时出现异常时提供详细信息的对象。

      • 代码

        字符串

        如果错误发生在对表达式求值之前，DevTools 端是否发生。

      • 说明

        字符串

        如果错误发生在对表达式求值之前，DevTools 端是否发生。

      • 详细信息

        任何 []

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

      • isError

        布尔值

        如果错误发生在对表达式求值之前，DevTools 端是否发生。

      • 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

    • 资源

      资源

    • 内容

      字符串