OLD | NEW |
1 <p id="classSummary"> | 1 <p id="classSummary"> |
2 Use the <code>chrome.webNavigation</code> module to receive | 2 Use the <code>chrome.webNavigation</code> module to receive |
3 notifications about the status of navigations requests in-flight. | 3 notifications about the status of navigations requests in-flight. |
4 </p> | 4 </p> |
5 | 5 |
6 <h2>Manifest</h2> | 6 <h2 id="manifest">Manifest</h2> |
7 <p> | 7 <p> |
8 All <code>chrome.webNavigation</code> methods and events require you to declare | 8 All <code>chrome.webNavigation</code> methods and events require you to declare |
9 the "webNavigation" permission in the <a href="manifest.html">extension | 9 the "webNavigation" permission in the <a href="manifest.html">extension |
10 manifest</a>. | 10 manifest</a>. |
11 For example: | 11 For example: |
12 </p> | 12 </p> |
13 | 13 |
14 <pre>{ | 14 <pre>{ |
15 "name": "My extension", | 15 "name": "My extension", |
16 ... | 16 ... |
17 <b>"permissions": [ | 17 <b>"permissions": [ |
18 "webNavigation" | 18 "webNavigation" |
19 ]</b>, | 19 ]</b>, |
20 ... | 20 ... |
21 }</pre> | 21 }</pre> |
22 | 22 |
23 | 23 |
24 <h2>Examples</h2> | 24 <h2 id="examples">Examples</h2> |
25 | 25 |
26 <p> | 26 <p> |
27 You can find simple examples of using the tabs module in the | 27 You can find simple examples of using the tabs module in the |
28 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension
s/docs/examples/api/webNavigation/">examples/api/webNavigation</a> | 28 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extension
s/docs/examples/api/webNavigation/">examples/api/webNavigation</a> |
29 directory. | 29 directory. |
30 For other examples and for help in viewing the source code, see | 30 For other examples and for help in viewing the source code, see |
31 <a href="samples.html">Samples</a>. | 31 <a href="samples.html">Samples</a>. |
32 </p> | 32 </p> |
33 | 33 |
34 <h2>Event order</h2> | 34 <h2 id="event_order">Event order</h2> |
35 <p> | 35 <p> |
36 For a navigation that is successfully completed, events are fired in the | 36 For a navigation that is successfully completed, events are fired in the |
37 following order: | 37 following order: |
38 <pre> | 38 <pre> |
39 onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted | 39 onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted |
40 </pre> | 40 </pre> |
41 </p> | 41 </p> |
42 <p> | 42 <p> |
43 Any error that occurs during the process results in an | 43 Any error that occurs during the process results in an |
44 <code>onErrorOccurred</code> event. For a specific navigation, there are no | 44 <code>onErrorOccurred</code> event. For a specific navigation, there are no |
(...skipping 18 matching lines...) Expand all Loading... |
63 </p> | 63 </p> |
64 <p> | 64 <p> |
65 If a navigation was triggered via <a | 65 If a navigation was triggered via <a |
66 href="https://support.google.com/chrome/bin/answer.py?answer=177873">Chrome | 66 href="https://support.google.com/chrome/bin/answer.py?answer=177873">Chrome |
67 Instant</a> or <a | 67 Instant</a> or <a |
68 href="https://support.google.com/chrome/bin/answer.py?answer=1385029">Instant | 68 href="https://support.google.com/chrome/bin/answer.py?answer=1385029">Instant |
69 Pages</a>, a completely loaded page is swapped into the current tab. In that | 69 Pages</a>, a completely loaded page is swapped into the current tab. In that |
70 case, an <code>onTabReplaced</code> event is fired. | 70 case, an <code>onTabReplaced</code> event is fired. |
71 </p> | 71 </p> |
72 | 72 |
73 <h2>Relation to webRequest events</h2> | 73 <h2 id="relation_to_webRequest">Relation to webRequest events</h2> |
74 <p> | 74 <p> |
75 There is no defined ordering between events of the <a | 75 There is no defined ordering between events of the <a |
76 href="webRequest.html">webRequest API</a> and the events of the | 76 href="webRequest.html">webRequest API</a> and the events of the |
77 webNavigation API. It is possible that webRequest events are still received for | 77 webNavigation API. It is possible that webRequest events are still received for |
78 frames that already started a new navigation, or that a navigation only | 78 frames that already started a new navigation, or that a navigation only |
79 proceeds after the network resources are already fully loaded. | 79 proceeds after the network resources are already fully loaded. |
80 </p> | 80 </p> |
81 <p> | 81 <p> |
82 In general, the webNavigation events are closely related to the navigation | 82 In general, the webNavigation events are closely related to the navigation |
83 state that is displayed in the UI, while the webRequest events correspond to | 83 state that is displayed in the UI, while the webRequest events correspond to |
84 the state of the network stack which is generally opaque to the user. | 84 the state of the network stack which is generally opaque to the user. |
85 </p> | 85 </p> |
86 | 86 |
87 <h2>A note about tab IDs</h2> | 87 <h2 id="tab_ids">A note about tab IDs</h2> |
88 <p> | 88 <p> |
89 Not all navigating tabs correspond to actual tabs in Chrome's UI, e.g., a tab | 89 Not all navigating tabs correspond to actual tabs in Chrome's UI, e.g., a tab |
90 that is being pre-rendered. Such tabs are not accessible via the | 90 that is being pre-rendered. Such tabs are not accessible via the |
91 <a href="tabs.html">tabs API</a> nor can you request information about them via | 91 <a href="tabs.html">tabs API</a> nor can you request information about them via |
92 <code>webNavigation.getFrame</code> or <code>webNavigation.getAllFrames</code>. | 92 <code>webNavigation.getFrame</code> or <code>webNavigation.getAllFrames</code>. |
93 Once such a tab is swapped in, an <code>onTabReplaced</code> event is fired and | 93 Once such a tab is swapped in, an <code>onTabReplaced</code> event is fired and |
94 they become accessible via these APIs. | 94 they become accessible via these APIs. |
95 </p> | 95 </p> |
96 | 96 |
97 <h2>A note about timestamps</h2> | 97 <h2 id="timestamps">A note about timestamps</h2> |
98 <p> | 98 <p> |
99 It's important to note that some technical oddities in the OS's handling | 99 It's important to note that some technical oddities in the OS's handling |
100 of distinct Chrome processes can cause the clock to be skewed between the | 100 of distinct Chrome processes can cause the clock to be skewed between the |
101 browser itself and extension processes. That means that WebNavigation's events' | 101 browser itself and extension processes. That means that WebNavigation's events' |
102 <code>timeStamp</code> property is only guaranteed to be <i>internally</i> | 102 <code>timeStamp</code> property is only guaranteed to be <i>internally</i> |
103 consistent. Comparing one event to another event will give you the correct | 103 consistent. Comparing one event to another event will give you the correct |
104 offset between them, but comparing them to the current time inside the | 104 offset between them, but comparing them to the current time inside the |
105 extension (via <code>(new Date()).getTime()</code>, for instance) might give | 105 extension (via <code>(new Date()).getTime()</code>, for instance) might give |
106 unexpected results. | 106 unexpected results. |
107 </p> | 107 </p> |
108 | 108 |
109 <h2>A note about frame and process IDs</h2> | 109 <h2 id="frame_ids">A note about frame and process IDs</h2> |
110 <p> | 110 <p> |
111 Due to the multi-process nature of Chrome, a tab might use different processes | 111 Due to the multi-process nature of Chrome, a tab might use different processes |
112 to render the source and destination of a web page. Therefore, if a navigation | 112 to render the source and destination of a web page. Therefore, if a navigation |
113 takes place in a new process, you might receive events both from the new and | 113 takes place in a new process, you might receive events both from the new and |
114 the old page until the new navigation is committed (i.e. the | 114 the old page until the new navigation is committed (i.e. the |
115 <code>onCommitted</code> event is send for the new main frame). Because frame | 115 <code>onCommitted</code> event is send for the new main frame). Because frame |
116 IDs are only unique for a given process, the webNavigation events include a | 116 IDs are only unique for a given process, the webNavigation events include a |
117 process ID, so you can still determine which frame a navigation came from. | 117 process ID, so you can still determine which frame a navigation came from. |
118 </p> | 118 </p> |
119 <p> | 119 <p> |
120 Also note that during a provisional load the process might be switched several | 120 Also note that during a provisional load the process might be switched several |
121 times. This happens when the load is redirected to a different site. In this | 121 times. This happens when the load is redirected to a different site. In this |
122 case, you will receive repeated <code>onBeforeNavigate</code> and | 122 case, you will receive repeated <code>onBeforeNavigate</code> and |
123 <code>onErrorOccurred</code> events, until you receive the final | 123 <code>onErrorOccurred</code> events, until you receive the final |
124 <code>onCommitted</code> event. | 124 <code>onCommitted</code> event. |
125 </p> | 125 </p> |
126 | 126 |
127 <h2>Transition types and qualifiers</h2> | 127 <h2 id="transition_types">Transition types and qualifiers</h2> |
128 <p> | 128 <p> |
129 The webNavigation API's <code>onCommitted</code> event has a | 129 The webNavigation API's <code>onCommitted</code> event has a |
130 <code>transitionType</code> and a <code>transitionQualifiers</code> property. | 130 <code>transitionType</code> and a <code>transitionQualifiers</code> property. |
131 The <em>transition type</em> is the same as used in the <a | 131 The <em>transition type</em> is the same as used in the <a |
132 href="history.html#transition_types">history API</a> describing how the browser | 132 href="history.html#transition_types">history API</a> describing how the browser |
133 navigated to this particular URL. In addition, several <em>transition | 133 navigated to this particular URL. In addition, several <em>transition |
134 qualifiers</em> can be returned that further define the navigation. | 134 qualifiers</em> can be returned that further define the navigation. |
135 </p> | 135 </p> |
136 <p> | 136 <p> |
137 The following transition qualifiers exist: | 137 The following transition qualifiers exist: |
(...skipping 21 matching lines...) Expand all Loading... |
159 <td> | 159 <td> |
160 The user used the Forward or Back button to initiate the navigation. | 160 The user used the Forward or Back button to initiate the navigation. |
161 </td> | 161 </td> |
162 </tr> | 162 </tr> |
163 <tr> | 163 <tr> |
164 <td>"from_address_bar"</td> | 164 <td>"from_address_bar"</td> |
165 <td> | 165 <td> |
166 The user initiated the navigation from the address bar (aka Omnibox). | 166 The user initiated the navigation from the address bar (aka Omnibox). |
167 </td> | 167 </td> |
168 </tr> | 168 </tr> |
169 </table> | 169 </table> |
OLD | NEW |