此页面由 Cloud Translation API 翻译。

chrome.devtools.inspectedWindow

说明

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

有关使用 Developer Tools API 的一般性简介，请参阅 DevTools API 摘要。

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

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

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

清单

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

"devtools_page"

在检查的窗口中执行代码

借助 eval 方法，扩展程序能够在所检查的网页环境中执行 JavaScript 代码。在恰当的情境下使用时效果会非常强，如果使用不当，此方法会很危险。请使用 tabs.executeScript 方法，除非您需要 eval 方法提供的特定功能。

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

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

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

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

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

frameURL: 用于指定并非被检查页面的主框架的框架。
contextSecurityOrigin: 用于根据指定帧的来源选择指定帧内的上下文。
useContentScriptContext: 如果为 true，请在扩展程序内容脚本所在的同一上下文中执行脚本。（相当于将扩展程序自己的 Web 组织指定为上下文安全来源。）这可用于与内容脚本交换数据。

示例

以下代码会检查所检查页面使用的 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

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

属性

网址

string

资源的网址。
getContent

void

获取资源的内容。

getContent 函数如下所示：
```
(callback: function)=> {...}
```
- callback
  
  功能
  
  callback 参数如下所示：
```
(content: string,encoding: string)=>void
```
  - 内容
    
    string
    
    资源的内容（可能已经过编码）。
  - encoding
    
    string
    
    如果内容未编码，则为空；否则为编码名称。目前只支持 base64。
setContent

void

设置资源的内容。

setContent 函数如下所示：
```
(content: string,commit: boolean,callback?: function)=> {...}
```
- 内容
  
  string
  
  资源的新内容。目前仅支持包含文本类型的资源。
- 提交
  
  boolean
  
  如果用户已完成资源修改，则为 true，资源的新内容应予以保留；如果是在用户修改资源过程中发送的细微更改，则为 false。
- callback
  
  函数（可选）
  
  callback 参数如下所示：
```
(error?: object)=>void
```
  - error
    
    对象（可选）
    
    如果资源内容设置成功，则设为 undefined；否则将说明错误。

属性

tabId

要检查的标签页的 ID。此 ID 可与 chrome.tabs 结合使用。*API.

类型

number

方法

eval()

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

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

参数

表达式

string

要计算的表达式。
选项

对象（可选）

options 参数可以包含一个或多个选项。
- frameURL
  
  字符串（可选）
  
  如果已指定，则会在网址与指定网址匹配的 iframe 上计算表达式。默认情况下，系统会在所检查网页的顶层框架中计算表达式。
- scriptExecutionContext
  
  字符串（可选）
  
  Chrome 107 及更高版本
  
  在与指定源匹配的扩展程序的内容脚本的上下文中评估表达式。如果指定，scriptExecutionContext 会覆盖 useContentScriptContext 上的“true”设置。
- useContentScriptContext
  
  布尔值选填
  
  在调用扩展程序的内容脚本的上下文中评估表达式，前提是该内容脚本已注入到检查的网页中。否则，系统不会对表达式求值，并且会在调用回调函数时将异常参数设为 isError 字段设为 true 且 code 字段设为 E_NOTFOUND 的对象。
callback

函数（可选）

callback 参数如下所示：
```
(result: object,exceptionInfo: object)=>void
```
- 结果
  
  对象
  
  评估结果。
- exceptionInfo
  
  对象
  
  一个对象，用于在评估表达式时发生异常，并提供详细信息。
  - 验证码
    
    string
    
    设置是否在对表达式求值之前在开发者工具端发生错误。
  - 说明
    
    string
    
    设置是否在对表达式求值之前在开发者工具端发生错误。
  - 明细
    
    任意 []
    
    设置是否在对表达式求值之前在开发者工具端发生错误，包含可以替换到说明字符串中的值的数组，以提供有关错误原因的更多信息。
  - isError
    
    boolean
    
    设置是否在对表达式求值之前在开发者工具端发生错误。
  - isException
    
    boolean
    
    如果所评估的代码生成未处理的异常，请设置此参数。
  - 值
    
    string
    
    如果所评估的代码生成未处理的异常，请设置此参数。

getResources()

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

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

参数

callback

功能

callback 参数如下所示：
```
(resources: Resource[])=>void
```
- 资源
  
  资源[]
  
  网页中的资源。

reload()

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

重新加载已检查的页面。

参数

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
```
- 资源
  
  资源
- 内容
  
  string