webNavigation

ナビゲーションのいろいろな段階でイベントリスナーを追加します。ナビゲーションにはある URL から他に移動するブラウザーフレームにより成り立っていて、それは(いつもではなく)通常はリンクのクリックやロケーションバーへの URL 入力といったユーザー操作の応答として発生します。

webRequest API と比較して: ナビゲーションは通常、ブラウザーにウェブリクエストを発生させますが、webRequest API は HTTP 層からの低レベルな観点に関心を持っており、一方で webNavigation API はブラウザー UI 自身に対して、より関心を持っています。

それぞれのイベントはナビゲーションの特定のステージに対応しています。イベントシーケンスは次の通りです:

• 主なフローは次の通り:
  • onBeforeNavigate
  • onCommitted
  • onDOMContentLoaded
  • onCompleted.
• 追加のものは次の通り:
  • onCreatedNavigationTarget は、ブラウザーがナビゲーション用にタブやウィンドウを作成する必要がある場合 (例えば、ユーザーがリンクを新しいタブで開いたために)、 onBeforeNavigate の前に発火します。i
  • onHistoryStateUpdated はページが history API を使ってブラウザーのロケーションバーに表示された URL を更新する場合に発火します。
  • onReferenceFragmentUpdated はページの fragment identifier が変更された場合に発火します。
  • onErrorOccurred はあらゆる場所で発火します。

それぞれのナビゲーションは特定のブラウザーフレーム内の URL の遷移です。ブラウザーフレームはタブ ID とフレーム ID で識別されます。フレームはタブ内の再上位のブラウジングコンテキストである場合や、iframe として実装されたネストされたブラウジングコンテキストである場合があります。

それぞれのイベントの addListener() の呼び出しはオプションの filter パラメーターを受け入れます。filter は1つ以上の URL パターンを指定し、イベントはターゲット URL がパターンにマッチしたナビゲーションの時だけに発火します。

onCommitted イベントリスナーには2つの追加プロパティが渡されます: ナビゲーションの原因 (例えばユーザーがリンクをクリックしたり、ユーザーがブックマークを選んだり) を示すTransitionType と、ナビゲーションの詳細情報を提供するTransitionQualifier です。

この API を使うには"webNavigation" パーミッションが必要です。

型

webNavigation.TransitionType

Cause of the navigation: 例えば、 the user clicked a link, or typed an address, or clicked a bookmark.

webNavigation.TransitionQualifier

Extra information about a transition.

関数

webNavigation.getFrame()

Retrieves information about a particular frame. A frame may be the top-level frame in a tab or a nested iframe, and is uniquely identified by a tab ID and a frame ID.

webNavigation.getAllFrames()

Given a tab ID, retrieves information about all the frames it contains.

イベント

webNavigation.onBeforeNavigate

Fired when the browser is about to start a navigation event.

webNavigation.onCommitted

Fired when a navigation is committed. At least part of the new document has been received from the server and the browser has decided to switch to the new document.

webNavigation.onDOMContentLoaded

Fired when the DOMContentLoaded event is fired in the page.

webNavigation.onCompleted

Fired when a document, including the resources it refers to, is completely loaded and initialized. This is equivalent to the DOM load event.

webNavigation.onErrorOccurred

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.

webNavigation.onCreatedNavigationTarget

Fired when a new window, or a new tab in an existing window, is created to host a navigation: for example, if the user opens a link in a new tab.

webNavigation.onReferenceFragmentUpdated

Fired if the fragment identifier for a page is changed.

webNavigation.onTabReplaced

Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab.

webNavigation.onHistoryStateUpdated

Fired when the page used the history API to update the URL displayed in the browser's location bar.

ブラウザ実装状況

Example extensions

• navigation-stats

// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//    * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//    * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//    * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.