chrome.devtools.inspectedWindow

描述： 使用 chrome.devtools.inspectedWindow API 与审查的窗口交互：获得审查网页的标签页标识符，在审查窗口的上下文中执行代码，重新加载网页，或者获取网页中所有资源的列表。
可用版本： 从 Chrome 18 开始支持。

使用 chrome.devtools.inspectedWindow 与审查的窗口交互：获得审查页面的标签页标识符，在审查窗口的上下文中执行代码，重新加载页面，或者获取页面中所有资源的列表。

有关使用开发者工具 API 的一般信息请参见开发者工具 API 概述。

概述

tabId 属性提供标签页标识符，您可以在调用 chrome.tabs.* API 时使用。然而，值得注意的是，出于安全考虑，chrome.tabs.* API 对开发者工具扩展程序网页不可用，您需要向后台网页传递标签页标识符，并在那儿调用 chrome.tabs.* API 函数。

reload 方法可以用来重新加载审查的网页，此外，调用者还能指定替代的用户代理字符串、网页载入早期插入的脚本以及强制重新加载缓存资源的选项。

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

在审查的窗口中执行代码

eval 方法使扩展程序能够在审查页面的上下文中执行 JavaScript 代码。该方法在正确的环境下是非常有用的，但是不恰当的使用会很危险。除非您需要 eval 方法才能提供的特定功能，请使用 tabs.executeScript 方法。

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

  • eval 方法不为执行的代码使用隔离环境，所以代码可以访问审查窗口的 JavaScript 状态。当您确实需要访问审查页面的 JavaScript 状态时请使用这一方法。
  • 代码执行的上下文包括开发者工具的控制台 API。例如，代码可以使用 inspect 和 $0。
  • 执行的代码可以返回一个值，传递给扩展程序的回调函数。返回值必须为一个有效的 JSON 对象（它只能包含原始的 JavaScript 类型以及对其他 JSON 对象的非循环引用）。在处理从审查页面接收的数据时请格外小心，执行上下文本质上由审查的页面控制，恶意页面可能会影响返回给扩展程序的数据。

重要提示：出于以上解释的安全性考虑，建议扩展程序在不需要访问审查页面的 JavaScript 状态的情况下首选 tabs.executeScript 方法访问审查页面的 DOM 数据。

注意，网页可以包含几个不同的 JavaScript 执行上下文。每一个框架都有单独的上下文，在一个框架中运行的每一个具有内容脚本的扩展程序还有单独的上下文。

默认情况下，eval 方法在审查网页主框架的上下文中执行。

eval 方法的第二个参数是可选的，您可以使用它指定代码在哪个上下文中求值。该 options 对象可以包含如下属性：

frameURL
用来指定审查网页主框架以外的其他框架。
contextSecurityOrigin
用来在指定框架中根据网络来源选择上下文。
useContentScriptContext
如果为 true，在当前扩展程序内容脚本的上下文中执行脚本。（等价于指定上下文安全来源为扩展程序自己的网络来源。）这种方式可以用来与内容脚本交换数据。

例子

      chrome.devtools.inspectedWindow.eval(
          "jQuery.fn.jquery",
           function(result, isException) {
             if (isException)
               console.log("该页面未使用 jQuery");
             else
               console.log("该页面使用 jQuery v" + result);
           }
      );

您可以在示例中找到使用开发者工具 API 的更多例子。

摘要

类型
Resource
属性
tabId
方法
eval − chrome.devtools.inspectedWindow.eval(string expression, object options, function callback)
reload − chrome.devtools.inspectedWindow.reload(object reloadOptions)
getResources − chrome.devtools.inspectedWindow.getResources(function callback)
事件
onResourceAdded
onResourceContentCommitted

类型

Resource

审查的页面中的资源，例如文档、脚本或图片。
属性
string url

资源的 URL。

方法

getContent

Resource.getContent(function callback)

获取资源内容。

参数
function callback

当请求完成时接收资源内容的函数。

callback 参数应该是一个如下形式的函数：

function(string content, string encoding) {...};
string content

资源内容（可能经过编码）。

string encoding

如果内容没有经过编码则为空，否则为编码名称。当前只支持 base64 编码。

setContent

Resource.setContent(string content, boolean commit, function callback)

设置资源内容。

参数
string content

资源的新内容，当前只支持文本类型的资源。

boolean commit

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

function （可选）
callback

当请求完成时调用的函数。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function(object error) {...};
object （可选）
error

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

属性

integer chrome.devtools.inspectedWindow.tabId 正在审查的标签页的标识符，这一标识符可以在 chrome.tabs.* API 中使用。

方法

eval

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

在审查页面主框架的上下文中对 JavaScript 表达式求值，表达式的结果必须是一个可转换为 JSON 的对象，否则将会引发异常。eval 函数可能会报告开发者工具中的错误，也可能是求值过程中产生的 JavaScript 异常。无论是哪种情况，回调函数的 result 参数均为 undefined。如果是开发者工具中的错误，isException 参数就不为 null，并包含 isError 属性，设置为 true，还有 code 属性，设置为错误码。如果是 JavaScript 错误，isException 设置为 true，value 设置为抛出的异常对象的字符串值。

参数
string expression

需要求值的表达式。

object （可选）
options

从 Chrome 38 开始支持。警告：目前为 Dev 分支。了解更多内容

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

string （可选）
frameURL

如果指定了该参数，表达式将在匹配指定 URL 的内嵌框架中运行。默认情况下表达式在审查网页的顶层框架中运行。

boolean （可选）
useContentScriptContext

在当前扩展程序内容脚本的上下文中运行表达式，要求内容脚本已经插入审查的网页。如果还没有，表达式就不会运行，调用回调函数时异常参数设置为一个对象，其中 isError 字段设为 true，code 字段设为 E_NOTFOUND。

string （可选）
contextSecurityOrigin

在匹配指定来源的扩展程序对应的内容脚本上下文中运行表达式。如果指定了该属性，contextSecurityOrigin 覆盖设置为 true 的 userContentScriptContext 属性。

function （可选）
callback

求值完成时调用的函数。

如果您指定了 callback 参数，它应该是一个如下形式的函数：

function(object result, object exceptionInfo) {...};
object result

求值结果。

object exceptionInfo

如果执行表达式的过程中发生异常，该对象提供详细信息。

boolean isError

如果表达式运行之前开发者工具中发生错误则设置为 true。

string code

如果运行表达式前开发者工具中产生错误则设置该属性。

string description

如果运行表达式前开发者工具中产生错误则设置该属性。

array of any details

如果运行表达式前开发者工具中产生错误则设置该属性，包含在描述字符串中需要替换的值数组，以便提供有关错误的更多信息。

boolean isException

如果运行的代码产生未处理的异常则设置该属性。

string value

如果运行的代码产生未处理的异常则设置该属性。

reload

chrome.devtools.inspectedWindow.reload(object reloadOptions)

重新载入审查的页面。

参数
object （可选）
reloadOptions
boolean （可选）
ignoreCache

当设置为 true 时，载入器将忽略所有在 load 事件产生前载入的审查页面资源的缓存，效果类似于在审查的窗口或开发者工具窗口中按下 Ctrl+Shift+R。

string （可选）
userAgent

如果指定的话，这一字符串会替代载入审查页面的资源时发送的 HTTP 头信息中的 User-Agent 值，这一字符串也会替代返回给审查的页面中运行的所有脚本的 naviagtor.userAgent 属性。

string （可选）
injectedScript

如果指定的话，这一脚本将会在刚开始载入时，在任何框架的脚本之前插入至审查页面的每一个框架。这一脚本在以后的重新载入中不会插入——例如，如果用户按下 Ctrl+R。

string （可选）
preprocessorScript

从 Chrome 38 开始支持。警告：目前为 Dev 分支。了解更多内容

如果指定了该属性，运行该脚本时会传递三个参数：要预处理的源代码、源代码 URL 以及函数名称（如果源代码为 DOM 事件处理程序）。preprocessorerScript 函数应该返回字符串，Chrome 浏览器使用它代替输入的源代码。如果源代码为 DOM 事件处理程序，返回的源代码必须编译为单个 JS 函数。

getResources

chrome.devtools.inspectedWindow.getResources(function callback)

从审查的页面中获取所有资源的列表。

参数
function callback

请求完成时接收资源列表的函数。

callback 参数应该是一个如下形式的函数：

function(array of Resource resources) {...};
array of Resource resources

页面中的资源。

事件

onResourceAdded

当新资源添加到审查的页面中时产生。

addListener

chrome.devtools.inspectedWindow.onResourceAdded.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function( Resource resource) {...};
Resource resource

onResourceContentCommitted

当新版本的资源提交（例如用户在开发者工具中保存了某一资源编辑之后的版本）时产生。

addListener

chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function( Resource resource, string content) {...};
Resource resource
string content

资源的新内容。

示例扩展程序