1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
<div id="pageData-name" class="pageData">WebNavigation API</div>
<!-- BEGIN AUTHORED CONTENT -->
<p id="classSummary">
Use the <code>chrome.webNavigation</code> module to receive
notifications about the status of navigations requests in-flight.
</p>
<h2>Manifest</h2>
<p>
All <code>chrome.webNavigation</code> methods and events require you to declare
the "webNavigation" permission in the <a href="manifest.html">extension
manifest</a>.
For example:
</p>
<pre>{
"name": "My extension",
...
<b>"permissions": [
"webNavigation"
]</b>,
...
}</pre>
<h2>Examples</h2>
<p>
You can find simple examples of using the tabs module in the
<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/webNavigation/">examples/api/webNavigation</a>
directory.
For other examples and for help in viewing the source code, see
<a href="samples.html">Samples</a>.
</p>
<h2>Event order</h2>
<p>
For a navigation that is successfully completed, events are fired in the
following order:
<pre>
onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted
</pre>
</p>
<p>
Any error that occurs during the process results in an
<code>onErrorOccurred</code> event. For a specific navigation, there are no
further events fired after <code>onErrorOccurred</code>.
</p>
<p>
If a navigating frame contains subframes, its <code>onCommitted</code> is fired
before any of its children's <code>onBeforeNavigate</code>; while
<code>onCompleted</code> is fired after all of its children's
<code>onCompleted</code>.
</p>
<p>
If the reference fragment of a frame is changed, a
<code>onReferenceFragmentUpdated</code> event is fired. This event can fire any
time after <code>onDOMContentLoaded</code>, even after
<code>onCompleted</code>.
</p>
<h2>Relation to webRequest events</h2>
<p>
There is no defined ordering between events of the <a
href="experimental.webRequest.html">webRequest API</a> 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.
</p>
<p>
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.
</p>
<h2>A note about timestamps</h2>
<p>
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'
<code>timeStamp</code> property is only guaranteed to be <i>internally</i>
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 <code>(new Date()).getTime()</code>, for instance) might give
unexpected results.
</p>
<!-- END AUTHORED CONTENT -->
|
