chrome.history

chorme.history 模块被用于和浏览器所访问的页面记录交互。你可以添加、删除、查询浏览器的历史记录。如果您想覆写历史页面，请查看覆写特定页。

Manifest

您必须在扩展Manifest文件中声明“history”权限，以便使用history API。如下所示：

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

过渡类型

History API用一种过渡类型来描述浏览器是如何访问的特定的URL。例如：如果URL是在用户访问页面时，点击链接跳转访问的，此时的过渡类型为“link”。

如下的列表详细定义了各种过渡类型。

过渡类型 描述
“typed” 用户通过地址栏输入网址，来访问本URL。这种类型也适用于显式的导航动作。与之相反，你可以参阅generated，它适用于用户没看到（不知道）网址URL的情况。
“auto_bookmark” 用户通过界面的推荐到达本URL。例如，通过点击菜单项打开的页面。
“auto_subframe” 子框架导航。这种类型是指那些非顶层框架自动加载的内容。例如，如果一个页面由许多包含广告的子框架构成，那些广告链就拥有这种过渡类型。用户可能没有意识到页面中的这些内容是个单独的框架，所以他们也可能根本没有在意这些URL（请查阅 manual_subframe)。
“manual_subframe” 此种类型是为用户显式请求的子框架导航以及在前进/后退列表中的生成导航入口的子框架导航所设置。由于用户更关心所请求框架被加载的效果，因此显式请求的框架可能会比自动载入的框架更为重要。
“generated” 用户通过在地址栏输入，而选择一个不像网址的入口到达的URL页面。例如，匹配结果中可能包含Google搜索结果页的URL, 但是它可能以“用Google搜索……”的形式展现。这类导航和 typed 导航是有差异的，因为用户没有输入或者看到最终的URL。请参阅 keyword。
“start_page” 页面是在命令行中被指定（打开），或者其本身就是起始页。
“form_submit”

用户提交的表单。请注意，某些情况，诸如表单运用脚本来提交，不属于此种类型。
“reload” 用户通过点击刷新按钮或者在地址栏输入回车键来刷新页面属于此种类型。会话重置，重开标签页都属于此种类型。
“keyword” URL通过可替代的关键字，而不是默认的搜索引擎产生。请查阅keyword_generated。
“keyword_generated” 相应由关键字生成的访问。请查阅keyword。

示例

请查看 history 样例目录 和 history API 测试目录 中如何使用此API的例子。如果想获取更多开发范例及源代码，请查看代码范例。

API说明：chrome.history

类型

HistoryItem

封装历史查询结果的对象。

HistoryItem 的属性：

id ( string )
条目的唯一标识符。
url ( optional string )
用户所访问的URL。
title ( optional string )
历史页面的标题。
lastVisitTime ( optional double )
页面最后一次被载入的时间，以纪元开始的毫秒数表示。
visitCount ( optional integer )
用户访问此页面的次数。
typedCount ( optional integer )
用户通过地址栏输入访问此页面的次数。

VisitItem

封装URL访问的对象。

Properties of VisitItem

id ( string )
条目的唯一标识符。
visitId ( string )
访问的唯一标识符。
visitTime ( optional double )
访问的时间，以纪元开始的毫秒数表示。
referringVisitId ( string )
访问来源（referrer）的 visitId。
transition ( enumerated string ["link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "auto_toplevel", "form_submit", "reload", "keyword", "keyword_generated"] )
访问来源的过渡类型。

方法

chrome.history.search(object query, function callback)

搜索访问历史中，匹配条件的页面最后一次访问的数据。

Parameters

query ( object )
text ( string )
在访问历史中查询的文本。若想获取所有页面的信息，把此参数设置为空。
startTime ( optional double )
限制结果访问日期至此日期之后，以纪元开始的毫秒数表示。
endTime ( optional double )
限制结果访问日期至此日期以前，以纪元开始的毫秒数表示。
maxResults ( optional integer )
所获取结果的最大数目。默认值为100。
callback ( function )

Callback

回调函数 callback 应当如下定义： 

function(array of HistoryItem results) {...};
results ( array of HistoryItem )

getVisits

chrome.history.getVisits(object details, function callback)

获取访问特定URL的所有信息。

Parameters

details ( object )
url ( string )
需要获取访问信息的URL。URL必须与调用 history.search 返回值的格式一致。
callback ( function )

Callback

回调函数 callback 应当如下定义： 

function(array of VisitItem results) {...};
results ( array of VisitItem )

addUrl

chrome.history.addUrl(object details, function callback)

在当前历史记录中添加一条过渡类型为“link”的URL。

Parameters

details ( object )
url ( string )
要添加的URL。
callback ( optional function )

Callback

如果您指定了 callback 参数，它的形式应该如下： 

function() {...};

deleteUrl

chrome.history.deleteUrl(object details, function callback)

删除指定URL的所有历史记录。

Parameters

details ( object )
url ( string )
要删除的URL。
callback ( optional function )

Callback

如果您指定了 callback 参数，它的形式应该如下所示： 

function() {...};

deleteRange

chrome.history.deleteRange(object range, function callback)

删除特定日期范围内的所有历史记录条目。页面本身只会在所有访问均在所设定日期的范围内才会被删除。

Parameters

range ( object )
startTime ( double )
删除范围的开始时间，以纪元开始的毫秒数表示。
endTime ( double )
删除范围的结束时间，以纪元开始的毫秒数表示。
callback ( function )

Callback

回调函数 callback 应当如下定义： 

function() {...};

deleteAll

chrome.history.deleteAll(function callback)

删除历史记录中的所有条目。

Parameters

callback ( function )

Callback

回调函数 callback 应当如下定义： 

function() {...};

事件

onVisited

chrome.history.onVisited.addListener(function(HistoryItem result) {...});

当URL被访问时，此事件被触发。并提供相应URL的 HistoryItem 数据。

Listener Parameters

result ( HistoryItem )

onVisitRemoved

chrome.history.onVisitRemoved.addListener(function(object removed) {...});

当一条或多条URL从历史服务中删除，此事件触发。当所有访问被移除后，此条URL从历史记录中被移除。

Listener Parameters

removed ( object )
allHistory ( boolean )
如删除了所有历史记录，则此参数值为 True。如果此参数值为 True，则 urls 参数为空。
urls ( optional array of string )

使用 chrome.history 的代码范例