chrome.webNavigation

描述： 使用 chrome.webNavigation API 实时地接收有关导航请求状态的通知。
可用版本： 从 Chrome 16 开始支持。
权限： "webNavigation"

清单文件

所有 chrome.webNavigation 方法和事件要求您在扩展程序的清单文件中声明 "webNavigation" 权限。例如： 

      {
        "name": "我的扩展程序",
        ...
        "permissions": [
          "webNavigation"
        ],
        ...
      }

例子

您可以在 examples/api/webNavigation 目录中找到使用网页导航模块的简单例子。有关其他例子以及查看源代码的帮助，请参见示例。

事件顺序

对于一次成功完成的导航，事件按照如下顺序产生： 

      onBeforeNavigate -> onCommitted -> onDOMContentLoaded -> onCompleted

在这一过程中如果发生任何错误都将产生 onErrorOccurred 事件。对于一次导航，在 onErrorOccurred 之后不会再产生进一步的事件。

如果导航中的框架包含子框架，它的 onCommitted 事件将在所有子框架的 onBeforeNavigate 事件之前产生，而 onCompleted 事件将在所有子框架的 onCompleted 事件之后产生。

如果使用了 history API 修改框架的状态（例如使用 history.pushState()），将产生 onHistoryStateUpdated 事件。这一事件可以在 onDOMContentLoaded 之后的任何时候产生。

如果导航通过 Chrome 即搜即得功能或网页即时看功能触发，已完全加载的页面将与当前标签页中的页面交换，这种情况下将产生 onTabReplaced 事件。

与网络请求事件间的关系

在网络请求 API 与网页导航 API 产生的事件之间没有确定的顺序。已经开始新导航的框架可能还会收到网络请求事件，或者也可能导航仅在网络资源完全加载后才继续进行。

大体上说，网页导航事件与用户界面中显示的导航状态密切相关，而网络请求事件对应于通常对用户来说不可见的网络栈状态。

有关标签页标识符的说明

并不是所有正在导航的标签页都对应于 Chrome 浏览器用户界面中的真实标签页，例如预呈现标签页。这样的标签页不能通过标签页 API 访问，您也不能通过 webRequest.getFrame 或 webRequest.getAllFrames 请求有关信息。一旦这样的标签页交换进来，将产生 onTabReplced 事件，并且它们也可以通过这些 API 访问了。

有关时间戳的说明

值得重视的是，操作系统对不同的 Chrome 浏览器进程在某些技术上的反常可能会导致时钟在浏览器自身以及扩展程序进程间不一致。这意味着网络请求事件的 timeStamp 属性仅保证内部的一致性，将两个事件的时间相比较会得到它们之间正确的时间差，但是与扩展程序内的当前时间（例如通过( new Date()).getTime()）比较可能会导致不可预料的结果。

有关框架和进程标识符的说明

由于 Chrome 浏览器使用多进程的基本架构，标签页可能会使用不同的进程来渲染网页的源和目标。因此，如果导航在新的进程中进行，您可能会同时接收到来自新旧页面的事件，直到新的导航已提交（即为新的主框架发送了 onCommitted 事件）。因为框架标识符对于给定进程是唯一的，网页导航事件包含进程标识符，所以您仍然可以确定导航来自哪个标签页。

同时也请注意，在临时加载的过程中，进程可能会多次切换。当加载过程需要重定向至另一个站点时就会发生这种情况。在这种情况下，您会多次收到 onBeforeNavigate 和 onErrorOccurred 事件，直到您接收到最终的 onCommitted 事件。

过渡类型和限定符

网页导航 API 的 onCommitted 事件包含 transitionType 与 transitionQualifiers 属性。过渡类型与历史记录 API 中所使用的相同，描述浏览器如何导航至这一特定的 URL。此外，还会返回几种过渡限定符，进一步定义本次导航。

存在如下几种过渡限定符：

过渡限定符 描述
"client_redirect" 导航过程中由页面上的 JavaScript 或 meta 刷新标记产生的一次或多次重定向。
"server_redirect" 导航过程中由服务器发送的 HTTP 头产生的一次或多次重定向。
"forward_back" 用户使用“前进”、“后退”按钮开始导航。
"from_address_bar" 用户从地址栏（即多功能框）开始导航。

摘要

方法
getFrame − chrome.webNavigation.getFrame(object details, function callback)
getAllFrames − chrome.webNavigation.getAllFrames(object details, function callback)
事件
onBeforeNavigate
onCommitted
onDOMContentLoaded
onCompleted
onErrorOccurred
onCreatedNavigationTarget
onReferenceFragmentUpdated
onTabReplaced
onHistoryStateUpdated

方法

getFrame

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

获取指定框架的有关信息。框架指网页中的 <iframe> 或者 <frame> 元素，通过标签页标识符以及框架标识符指定。

参数
object details

要获取信息的框架的有关信息。

integer tabId

框架所在的标签页标识符。

integer processId

从 Chrome 22 开始支持。

该标签页的渲染器进程标识符。

integer frameId

指定标签页中的框架标识符。

function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object （可选）
details

请求框架的有关信息，如果框架标识符和/或标签页标识符无效则为 null。

boolean errorOccurred

如果该框架中的上一次导航由于错误（即产生了 onErrorOccurred 事件）而中断则为 true。

string url

如果在指定标签页中 frameId 指定的框架标识符在某一时刻曾经存在的话，则为当前与该框架相关联的 URL。URL 与给定的框架标识符相关联并不意味着相应的框架仍然存在。

integer parentFrameId

包含当前框架的父框架，如果不存在父框架则设为 -1。

getAllFrames

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

获取给定标签页中所有框架的有关信息。

参数
object details

要获取所有框架的标签页信息。

integer tabId

标签页的标识符。

function callback

callback 参数应该是一个如下形式的函数：

function(array of object details) {...};
array of object （可选）
details

指定标签页中的所有框架，若标签页标识符无效则为 null。

每一个对象的属性

boolean errorOccurred

如果该框架中的上一次导航由于错误（即产生了 onErrorOccurred 事件）而中断则为 true。

integer processId

该标签页的渲染器进程标识符。

integer frameId

框架标识符，0 表示主框架，正整数表示子框架标识符。

integer parentFrameId

包含当前框架的父框架，如果不存在父框架则设为 -1。

string url

当前与该框架相关联的URL。

事件

onBeforeNavigate

当导航即将发生时产生。

过滤器

array of events.UrlFilter url

正在导航的 URL 所需满足的条件。对于该事件，UrlFilter 的 schemes 和 ports 字段将忽略。

addListener

chrome.webNavigation.onBeforeNavigate.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details
integer tabId

将要发生的导航所在的标签页标识符。

string url
integer processId

从 Chrome 22 开始支持。

渲染当前标签页的进程标识符。

integer frameId

0 表示导航发生在标签页内容窗口中，正数表示导航发生在子框架中。框架标识符在给定标签页与进程中唯一。

integer parentFrameId

从 Chrome 24 开始支持。

包含当前框架的父框架，如果不存在父框架则设为 -1。

double timeStamp

浏览器将要开始导航的时间，表示为自 1970 年 1 月 1 日午夜开始所经过的毫秒数。

onCommitted

当一次导航提交时产生。文档（以及它引用的资源，例如图片与子框架）可能还在下载，但是至少文档的一部分已经从服务器接收到，并且浏览器已经决定切换到新文档。

过滤器

array of events.UrlFilter url

正在导航的 URL 所需满足的条件。对于该事件，UrlFilter 的 schemes 和 ports 字段将忽略。

addListener

chrome.webNavigation.onCommitted.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details
integer tabId

导航所在的标签页标识符。

string url
integer processId

从 Chrome 22 开始支持。

渲染当前标签页的进程标识符。

integer frameId

0 表示导航发生在标签页内容窗口中，正数表示导航发生在子框架中。框架标识符在标签页中唯一。

enum of "link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "start_page", "form_submit", "reload", "keyword", or "keyword_generated" transitionType

导航发生的原因，这些过渡类型与历史记录API中所定义的相同，除了用 "start_page" 代替 "auto_toplevel"（为了保持向后兼容）。

array of enum of "client_redirect", "server_redirect", "forward_back", or "from_address_bar" transitionQualifiers

过渡限定符列表。

double timeStamp

导航提交的时间，表示为自 1970 年 1 月 1 日午夜开始所经过的毫秒数。

onDOMContentLoaded

当页面的 DOM 已完全构造时产生，但是此时引用的资源可能还未完成加载。

过滤器

array of events.UrlFilter url

正在导航的 URL 所需满足的条件。对于该事件，UrlFilter 的 schemes 和 ports 字段将忽略。

addListener

chrome.webNavigation.onDOMContentLoaded.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details
integer tabId

导航所在的标签页标识符。

string url
integer processId

从 Chrome 22 开始支持。

渲染当前标签页的进程标识符。

integer frameId

0 表示导航发生在标签页内容窗口中，正数表示导航发生在子框架中。框架标识符在标签页中唯一。

double timeStamp

页面 DOM 完全构造的时间，表示为自 1970 年 1 月 1 日午夜开始所经过的毫秒数。

onCompleted

当文档（包括它所引用的资源）已经完全加载并初始化完成时产生。

过滤器

array of events.UrlFilter url

正在导航的 URL 所需满足的条件。对于该事件，UrlFilter 的 schemes 和 ports 字段将忽略。

addListener

chrome.webNavigation.onCompleted.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details
integer tabId

导航所在的标签页标识符。

string url
integer processId

从 Chrome 22 开始支持。

渲染当前标签页的进程标识符。

integer frameId

0 表示导航发生在标签页内容窗口中，正数表示导航发生在子框架中。框架标识符在标签页中唯一。

double timeStamp

文档加载完成的时间，表示为自 1970 年 1 月 1 日午夜开始所经过的毫秒数。

onErrorOccurred

当错误发生，导航终止时产生。无论网络错误还是用户终止导航都会产生这一事件。

过滤器

array of events.UrlFilter url

正在导航的 URL 所需满足的条件。对于该事件，UrlFilter 的 schemes 和 ports 字段将忽略。

addListener

chrome.webNavigation.onErrorOccurred.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details
integer tabId

导航所在的标签页标识符。

string url
integer processId

从 Chrome 22 开始支持。

渲染当前标签页的进程标识符。

integer frameId

0 表示导航发生在标签页内容窗口中，正数表示导航发生在子框架中。框架标识符在标签页中唯一。

string error

错误描述。

double timeStamp

发生错误的时间，表示为自 1970 年 1 月 1 日午夜开始所经过的毫秒数。

onCreatedNavigationTarget

当用来进行导航的新窗口或现有窗口中的新标签页创建时产生。

过滤器

array of events.UrlFilter url

正在导航的 URL 所需满足的条件。对于该事件，UrlFilter 的 schemes 和 ports 字段将忽略。

addListener

chrome.webNavigation.onCreatedNavigationTarget.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details
integer sourceTabId

触发这一导航的标签页标识符。

integer sourceProcessId

从 Chrome 22 开始支持。

渲染来源标签页的进程标识符。

integer sourceFrameId

触发这一导航的框架标识符。0 表示主框架。

string url

要在新窗口中打开的 URL。

integer tabId

打开这一 URL 的标签页标识符。

double timeStamp

浏览器将要创建新视图的时间，表示为自 1970 年 1 月 1 日午夜开始所经过的毫秒数。

onReferenceFragmentUpdated

当框架的引用片段更新时产生，该框架以后所有的事件都会使用更新的 URL。

过滤器

array of events.UrlFilter url

正在导航的 URL 所需满足的条件。对于该事件，UrlFilter 的 schemes 和 ports 字段将忽略。

addListener

chrome.webNavigation.onReferenceFragmentUpdated.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details
integer tabId

导航所在的标签页标识符。

string url
integer processId

从 Chrome 22 开始支持。

渲染当前标签页的进程标识符。

integer frameId

0 表示导航发生在标签页内容窗口中，正数表示导航发生在子框架中。框架标识符在标签页中唯一。

enum of "link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "start_page", "form_submit", "reload", "keyword", or "keyword_generated" transitionType

导航发生的原因，这些过渡类型与历史记录API中所定义的相同，除了用 "start_page" 代替 "auto_toplevel"（为了保持向后兼容）。

array of enum of "client_redirect", "server_redirect", "forward_back", or "from_address_bar" transitionQualifiers

过渡限定符列表。

double timeStamp

导航提交的时间，表示为自 1970 年 1 月 1 日午夜开始所经过的毫秒数。

onTabReplaced

从 Chrome 22 开始支持。

当标签页内容由另一个（通常时之前预呈现的）标签页替换时产生。

addListener

chrome.webNavigation.onTabReplaced.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details
integer replacedTabId

被替换的标签页标识符。

integer tabId

替换旧标签页的标签页标识符。

double timeStamp

替换发生的时间，表示为自 1970 年 1 月 1 日午夜开始所经过的毫秒数。

onHistoryStateUpdated

从 Chrome 22 开始支持。

当框架的历史记录更新为新的 URL 时产生，对应框架之后产生的所有事件都会使用已更新的 URL。

过滤器

array of events.UrlFilter url

正在导航的 URL 所需满足的条件。对于该事件，UrlFilter 的 schemes 和 ports 字段将忽略。

addListener

chrome.webNavigation.onHistoryStateUpdated.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function(object details) {...};
object details
integer tabId

导航所在的标签页标识符。

string url
integer processId

渲染当前标签页的进程标识符。

integer frameId

0 表示导航发生在标签页内容窗口中，正数表示导航发生在子框架中。框架标识符在标签页中唯一。

enum of "link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "start_page", "form_submit", "reload", "keyword", or "keyword_generated" transitionType

导航发生的原因，这些过渡类型与历史记录API中所定义的相同，除了用 "start_page" 代替 "auto_toplevel"（为了保持向后兼容）。

array of enum of "client_redirect", "server_redirect", "forward_back", or "from_address_bar" transitionQualifiers

过渡限定符列表。

double timeStamp

导航提交的时间，表示为自 1970 年 1 月 1 日午夜开始所经过的毫秒数。

示例扩展程序