You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
WARNING: This is the BETA documentation. It may not work with the stable release of Chrome.
WARNING: This is unofficial documentation. It may not work with the current release of Chrome.

Google Chrome Extensions (Labs)

chrome.devtools.inspectedWindow.* APIs

chrome.devtools.inspectedWindow.* APIs

Use chrome.devtools.inspectedWindow to interact with the inspected window: obtain the tab ID for the inspected page, evaluate the code in the context of inspected window, reload the page, or obtain the list of resources within the page.

See DevTools APIs summary for general introduction to using Developer Tools APIs.

Overview

The tabId property provides the tab identifier that you can use with the chrome.tabs.* API calls. However, please note that chrome.tabs.* API is not exposed to the Developer Tools extension pages due to security considerations — you will need to pass the tab ID to the background page and invoke the chrome.tabs.* API functions from there.

The eval() method provides the ability for extensions to execute JavaScript code in the context of the main frame of the inspected page. This method is powerful when used in the right context and dangerous when used inappropriately. Use the chrome.tabs.executeScript() method unless you need the specific functionality that the eval() method provides.

Here are the main differences between the eval() and chrome.tabs.executeScript() methods:

  • The eval() method does not use an isolated world for the code being evaluated, so the JavaScript state of the inspected window is accessible to the code. Use this method when access to the JavaScript state of the inspected page is required.
  • The execution context of the code being evaluated includes the Developer Tools console API. For example, the code can use inspect() and $0.
  • The evaluated code may return a value that is passed to the extension callback. The returned value has to be a valid JSON object (it may contain only primitive JavaScript types and acyclic references to other JSON objects). Please observe extra care while processing the data received from the inspected page — the execution context is essentially controlled by the inspected page; a malicious page may affect the data being returned to the extension.

Important: Due to the security considerations explained above, the chrome.tabs.executeScript() method is the preferred way for an extension to access DOM data of the inspected page in cases where the access to JavaScript state of the inspected page is not required.

The reload() method may be used to reload the inspected page. Additionally, the caller can specify an override for the user agent string, a script that will be injected early upon page load, and an option to force reload of cached resources.

Use the getResources() call and the onResourceContent event to obtain the list of resources (documents, stylesheets, scripts, images etc) within the inspected page. The getContent() and setContent() methods of the Resource class along with the onResourceContentCommitted event may be used to support modification of the resource content, for example, by an external editor.

Examples

The following code checks for the version of jQuery used by the inspected page: 

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);
     }
);

You can find more examples that use Developer Tools APIs in Samples.

API reference: chrome.devtools.inspectedWindow

Properties

tabId

chrome.devtools.inspectedWindow.tabId
tabId
( integer )
The ID of the tab being inspected. This ID may be used with chrome.tabs.* API.

Methods

eval

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

Evaluates a JavaScript expression in the context of the main frame of the inspected page. The expression must evaluate to a JSON-compliant object, otherwise an exception is thrown.

Parameters

expression
( string )
An expression to evaluate.
callback
( optional function )
A function called when evaluation completes.

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function(object result, boolean isException) {...};
result
( object )
The result of evaluation.
isException
( boolean )
Set if an exception was caught while evaluating the expression.

getResources

chrome.devtools.inspectedWindow.getResources(function callback)

Retrieves the list of resources from the inspected page.

Parameters

callback
( function )
A function that receives the list of resources when the request completes.

Callback function

The callback parameter should specify a function that looks like this: 

function(array of Resource resources) {...};
resources
( array of Resource )
The resources within the page.

reload

chrome.devtools.inspectedWindow.reload(object reloadOptions)

Reloads the inspected page.

Parameters

reloadOptions
( optional object )
Undocumented.
ignoreCache
( optional boolean )
When true, the loader will ignore the cache for all inspected page resources loaded before the load event is fired. The effect is similar to pressing Ctrl+Shift+R in the inspected window or within the Developer Tools window.
userAgent
( optional string )
If specified, the string will override the value of the User-Agent HTTP header that's sent while loading the resources of the inspected page. The string will also override the value of the navigator.userAgent property that's returned to any scripts that are running within the inspected page.
injectedScript
( optional string )
If specified, the script will be injected into every frame of the inspected page immediately upon load, before any of the frame's scripts. The script will not be injected after subsequent reloads—for example, if the user presses Ctrl+R.

Events

onResourceAdded

chrome.devtools.inspectedWindow.onResourceAdded.addListener(function(Resource resource) {...});

Fired when a new resource is added to the inspected page.

Listener parameters

resource
( Resource )
Undocumented.

onResourceContentCommitted

chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(function(Resource resource, string content) {...});

Fired when a new revision of the resource is committed (e.g. user saves an edited version of the resource in the Developer Tools).

Listener parameters

resource
( Resource )
Undocumented.
content
( string )
New content of the resource.

Types

Resource

( object )
A resource within the inspected page, such as a document, a script, or an image.
url
( string )
The URL of the resource.

Methods of Resource

getContent

resource.getContent(function callback)

Gets the content of the resource.

Parameters

callback
( function )
A function that receives resource content when the request completes.

Callback function

The callback parameter should specify a function that looks like this: 

function(string content, string encoding) {...};
content
( string )
Content of the resource (potentially encoded).
encoding
( string )
Empty if content is not encoded, encoding name otherwise. Currently, only base64 is supported.

setContent

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

Sets the content of the resource.

Parameters

content
( string )
New content of the resource. Only resources with the text type are currently supported.
commit
( boolean )
True if the user has finished editing the resource, and the new content of the resource should be persisted; false if this is a minor change sent in progress of the user editing the resource.
callback
( optional function )
A function called upon request completion.

Callback function

If you specify the callback parameter, it should specify a function that looks like this: 

function(object error) {...};
error
( optional object )
Set to undefined if the resource content was set successfully; describes error otherwise.