说明
使用 chrome.devtools.inspectedWindow
API 与检查的窗口进行交互:获取所检查页面的标签页 ID、在所检查窗口的上下文中评估代码、重新加载页面,或获取页面中的资源列表。
清单
使用 chrome.devtools.inspectedWindow
与被检查的窗口进行交互:获取所检查页面的标签页 ID、在所检查窗口的上下文中评估代码、重新加载页面,或获取页面中的资源列表。
有关使用 Developer Tools API 的一般性简介,请参阅 DevTools API 摘要。
概览
tabId
属性提供了可与 chrome.tabs.*
API 调用搭配使用的标签页标识符。但请注意,出于安全考虑,chrome.tabs.*
API 不会向开发者工具扩展程序页面公开 - 您需要将标签页 ID 传递到后台页面,并从该页面调用 chrome.tabs.*
API 函数。
reload
方法可用于重新加载所检查的页面。此外,调用方还可以指定以下两种方式:替换用户代理字符串、在网页加载时提前注入的脚本或强制重新加载已缓存资源的选项。
使用 getResources
调用和 onResourceContent
事件获取所检查页面中的资源(文档、样式表、脚本、图片等)列表。Resource
类的 getContent
和 setContent
方法以及 onResourceContentCommitted
事件可用于支持资源内容修改,例如通过外部编辑器修改。
在“Inspected”(已检查)窗口中执行代码
借助 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,
)
从检查的页面中检索资源列表。
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,
)
在将新资源添加到检查的网页时触发。
onResourceContentCommitted
chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
callback: function,
)
在提交资源的新修订版本时触发(例如,用户在开发者工具中保存资源的修改版本)。