说明
使用 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
事件可以
可用于支持资源内容的修改,例如由外部编辑者修改。
清单
在检查的窗口中执行代码
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,
)
在被检查页面的主框架上下文中评估 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,
)
从检查过的页面中检索资源列表。
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,
)
在提交资源的新修订版本时触发(例如,用户在开发者工具中保存了某个已修改的资源版本)。