このページは大阪弁化フィルタによって翻訳生成されたんですわ。

翻訳前ページへ
WebNavigation API - Google Chrome Extensions - Google Code
The Wayback Machine - http://web.archive.org/web/20120827041759/http://developer.chrome.com:80/extensions/webNavigation.html
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

WebNavigation API

WebNavigation API

Use the chrome.webNavigation module to receive notifications about the status of navigations requests in-flight.

Manifest

All chrome.webNavigation methods and events require you to declare the "webNavigation" permission in the extension manifest. For example: 

{
  "name": "My extension",
  ...
  "permissions": [
    "webNavigation"
  ],
  ...
}

Examples

You can find simple examples of using the tabs module in the examples/api/webNavigation directory. For other examples and for help in viewing the source code, see Samples.

Event order

For a navigation that is successfully completed, events are fired in the following order: 

onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted

Any error that occurs during the process results in an onErrorOccurred event. For a specific navigation, there are no further events fired after onErrorOccurred.

If a navigating frame contains subframes, its onCommitted is fired before any of its children's onBeforeNavigate; while onCompleted is fired after all of its children's onCompleted.

If the reference fragment of a frame is changed, a onReferenceFragmentUpdated event is fired. This event can fire any time after onDOMContentLoaded, even after onCompleted.

Relation to webRequest events

There is no defined ordering between events of the webRequest API and the events of the webNavigation API. It is possible that webRequest events are still received for frames that already started a new navigation, or that a navigation only proceeds after the network resources are already fully loaded.

In general, the webNavigation events are closely related to the navigation state that is displayed in the UI, while the webRequest events correspond to the state of the network stack which is generally opaque to the user.

A note about timestamps

It's important to note that some technical oddities in the OS's handling of distinct Chrome processes can cause the clock to be skewed between the browser itself and extension processes. That means that WebNavigation's events' timeStamp property is only guaranteed to be internally consistent. Comparing one event to another event will give you the correct offset between them, but comparing them to the current time inside the extension (via (new Date()).getTime(), for instance) might give unexpected results.

Transition types and qualifiers

The webNavigation API's onCommitted event has a transitionType and a transitionQualifiers property. The transition type is the same as used in the history API describing how the browser navigated to this particular URL. In addition, several transition qualifiers can be returned that further define the navigation.

The following transition qualifiers exist:

Transition qualifier Description
"client_redirect" One or more redirects caused by JavaScript or meta refresh tags on the page happened during the navigation.
"server_redirect" One or more redirects caused by HTTP headers sent from the server happened during the navigation.
"forward_back" The user used the Forward or Back button to initiate the navigation.
"from_address_bar" The user initiated the navigation from the address bar (aka Omnibox).

API reference: chrome.webNavigation

Methods

getAllFrames

chrome.webNavigation.getAllFrames(object details, function callback)

Retrieves information about all frames of a given tab.

Parameters

details
( object )
Information about the tab to retrieve all frames from.
tabId
( integer )
The ID of the tab.
callback
( function )
Undocumented.

getFrame

chrome.webNavigation.getFrame(object details, function callback)

Retrieves information about the given frame. A frame refers to an <iframe> or a <frame> of a web page and is identified by a tab ID and a frame ID.

Parameters

details
( object )
Information about the frame to retrieve information about.
tabId
( integer )
The ID of the tab in which the frame is.
frameId
( integer )
The ID of the frame in the given tab.
callback
( function )
Undocumented.

Events

onBeforeNavigate

chrome.webNavigation.onBeforeNavigate.addListener(function(object details) {...});

Fired when a navigation is about to occur.

Listener parameters

details
( object )
Undocumented.
tabId
( integer )
The ID of the tab in which the navigation is about to occur.
url
( string )
Undocumented.
frameId
( integer )
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
timeStamp
( number )
The time when the browser was about to start the navigation, in milliseconds since the epoch.

onCommitted

chrome.webNavigation.onCommitted.addListener(function(object details) {...});

Fired when a navigation is committed. The document (and the resources it refers to, such as images and subframes) might still be downloading, but at least part of the document has been received from the server and the browser has decided to switch to the new document.

Listener parameters

details
( object )
Undocumented.
tabId
( integer )
The ID of the tab in which the navigation occurs.
url
( string )
Undocumented.
frameId
( integer )
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
transitionType
( enumerated string ["link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "start_page", "form_submit", "reload", "keyword", "keyword_generated"] )
Cause of the navigation. The same transition types as defined in the history API are used.
transitionQualifiers
( array of string ["client_redirect", "server_redirect", "forward_back", "from_address_bar"] )
A list of transition qualifiers.
timeStamp
( number )
The time when the navigation was committed, in milliseconds since the epoch.

onCompleted

chrome.webNavigation.onCompleted.addListener(function(object details) {...});

Fired when a document, including the resources it refers to, is completely loaded and initialized.

Listener parameters

details
( object )
Undocumented.
tabId
( integer )
The ID of the tab in which the navigation occurs.
url
( string )
Undocumented.
frameId
( integer )
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
timeStamp
( number )
The time when the document finished loading, in milliseconds since the epoch.

onCreatedNavigationTarget

chrome.webNavigation.onCreatedNavigationTarget.addListener(function(object details) {...});

Fired when a new window, or a new tab in an existing window, is created to host a navigation.

Listener parameters

details
( object )
Undocumented.
sourceTabId
( integer )
The ID of the tab in which the navigation is triggered.
sourceFrameId
( integer )
The ID of the frame with sourceTabId in which the navigation is triggered. 0 indicates the main frame.
url
( string )
The URL to be opened in the new window.
tabId
( integer )
The ID of the tab in which the url is opened
timeStamp
( number )
The time when the browser was about to create a new view, in milliseconds since the epoch.

onDOMContentLoaded

chrome.webNavigation.onDOMContentLoaded.addListener(function(object details) {...});

Fired when the page's DOM is fully constructed, but the referenced resources may not finish loading.

Listener parameters

details
( object )
Undocumented.
tabId
( integer )
The ID of the tab in which the navigation occurs.
url
( string )
Undocumented.
frameId
( integer )
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
timeStamp
( number )
The time when the page's DOM was fully constructed, in milliseconds since the epoch.

onErrorOccurred

chrome.webNavigation.onErrorOccurred.addListener(function(object details) {...});

Fired when an error occurs and the navigation is aborted. This can happen if either a network error occurred, or the user aborted the navigation.

Listener parameters

details
( object )
Undocumented.
tabId
( integer )
The ID of the tab in which the navigation occurs.
url
( string )
Undocumented.
frameId
( integer )
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
error
( string )
The error description.
timeStamp
( number )
The time when the error occurred, in milliseconds since the epoch.

onReferenceFragmentUpdated

chrome.webNavigation.onReferenceFragmentUpdated.addListener(function(object details) {...});

Fired when the reference fragment of a frame was updated. All future events for that frame will use the updated URL.

Listener parameters

details
( object )
Undocumented.
tabId
( integer )
The ID of the tab in which the navigation occurs.
url
( string )
Undocumented.
frameId
( integer )
0 indicates the navigation happens in the tab content window; a positive value indicates navigation in a subframe. Frame IDs are unique within a tab.
transitionType
( enumerated string ["link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "start_page", "form_submit", "reload", "keyword", "keyword_generated"] )
Cause of the navigation. The same transition types as defined in the history API are used.
transitionQualifiers
( array of string ["client_redirect", "server_redirect", "forward_back", "from_address_bar"] )
A list of transition qualifiers.
timeStamp
( number )
The time when the navigation was committed, in milliseconds since the epoch.