chrome.history

描述：	使用 `chrome.history` API 与浏览器的历史记录交互，您可以添加、删除、通过 URL 查询浏览器的历史记录。如果您想要使用您自己的版本替换默认的历史记录页面，请参见替代页面。
可用版本：	从 Chrome 5 开始支持。
权限：	"history"

清单文件

您必须在扩展程序的清单文件中声明 "history" 权限才能使用历史记录 API。例如：

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

过渡类型

历史记录 API 使用过渡类型来描述浏览器在某次访问中如何进入某个特定的 URL。例如，如果用户通过单击另一个页面上的链接访问一个页面，则过渡类型为 "link"（链接）。

下表描述每一种过渡类型。

过渡类型	描述
"link"	用户通过单击另一个页面上的链接进入此页面。
"typed"	用户通过在地址栏中输入 URL 进入此页面，也用于其他显式的导航操作。请注意与 generated 比较，它在用户选择了非 URL 选项的情况下使用。
"auto_bookmark"	用户通过用户界面中的建议（例如通过菜单项）进入了此页面。
"auto_subframe"	子框架导航，用于任何自动在非顶层框架中加载的内容。例如，如果一个页面包含几个含有广告的框架，这些广告的 URL 具有这种过渡类型。用户不一定知道这些页面中的内容在单独的框架中，也不一定会关心它们的 URL（请注意与 manual_subframe比较）。
"manual_subframe"	用于用户明确请求的子框架导航，在前进/后退列表中会产生新的导航项。明确的框架请求可能比自动加载的框架更重要，因为用户可能关心请求的框架加载的情况。
"generated"	用户通过在地址栏中输入并选择非 URL 项进入了该页面。例如，匹配项可能具有 Google 搜索结果页面的 URL，但是用户看到的可能是“在 Google 中搜索…”。这和 typed 导航不同，因为用户没有输入也没有看到目标 URL。另外请与 keyword 比较。
"auto_toplevel"	该页面在命令行中指定或者为主页。
"form_submit"	用户填写了表单中的内容并提交。注意，在某些情况下（例如表单使用脚本来提交内容），提交表单不一定产生这种过渡类型。
"reload"	用户重新加载了此页面，无论是单击重新加载按钮还是在地址栏中按下回车。会话恢复以及重新打开已关闭的标签页也使用这一种过渡类型。
"keyword"	URL 从除了默认搜索引擎以外的可替换关键字生成。同时参见 keyword_generated。
"keyword_generated"	对应于为某一关键字产生的访问。同时参见 keyword。

例子

有关使用这一 API 的例子，请参见历史记录示例目录和历史记录API测试目录。有关其他例子以及查看源代码的帮助，请参见示例。

摘要

类型
HistoryItem
VisitItem
方法
search − `chrome.history.search(object query, function callback)`
getVisits − `chrome.history.getVisits(object details, function callback)`
addUrl − `chrome.history.addUrl(object details, function callback)`
deleteUrl − `chrome.history.deleteUrl(object details, function callback)`
deleteRange − `chrome.history.deleteRange(object range, function callback)`
deleteAll − `chrome.history.deleteAll(function callback)`
事件
onVisited
onVisitRemoved

类型

HistoryItem

包含历史记录的一个查询结果的对象。

属性
string	id	该项目的唯一标识符。
string	（可选） url	用户访问的 URL。
string	（可选） title	上一次加载时该页面的标题。
double	（可选） lastVisitTime	页面最后一次访问的时间，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。
integer	（可选） visitCount	用户访问此页面的次数。
integer	（可选） typedCount	用户通过在地址来中输入 URL 的方式访问此页面的次数。

VisitItem

包含对一个 URL 的某一次访问的对象。

属性
string	id	该项目的唯一标识符。
string	visitId	本次访问的唯一标识符。
double	（可选） visitTime	访问时间，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。
string	referringVisitId	引用者的访问所对应的标识符。
enum of `"link"`, `"typed"`, `"auto_bookmark"`, `"auto_subframe"`, `"manual_subframe"`, `"generated"`, `"auto_toplevel"`, `"form_submit"`, `"reload"`, `"keyword"`, or `"keyword_generated"`	transition	这一次访问相对引用者的过渡类型。

方法

search


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

搜索历史记录，找出所有匹配页面的最后一次访问记录。

参数

object

query

string	text	向历史记录服务发出的查询文本，如果为空则获取所有页面。
double	（可选） startTime	将结果限制为此日期之后的访问，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。
double	（可选） endTime	将结果限制为此日期之前的访问，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。
integer	（可选） maxResults	要获得的最大结果数目，默认为 100。

function

callback

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

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

array of HistoryItem

results

getVisits


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

获取有关某个 URL 的访问信息。

参数

object

details

string

url

需要获取信息的 URL，必须与 history.search 调用的返回值具有相同的形式。

function

callback

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

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

array of VisitItem

results

addUrl


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

向历史记录中以当前时间添加 URL，过渡类型为 "link"。

参数

object

details

string

url

要添加的 URL。

function

（可选）
callback

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

function() {...};

deleteUrl


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

从历史记录中删除出现给定 URL 的所有内容。

参数

object

details

string

url

要删除的 URL。

function

（可选）
callback

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

function() {...};

deleteRange


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

删除指定日期范围内的所有历史记录，访问日期不在这一范围内的页面不会从历史记录中删除。

参数

object

range

double	startTime	删除这一时间之后的添加历史记录，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。
double	endTime	删除这一时间之前的添加历史记录，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。

function

callback

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

function() {...};

deleteAll


              chrome.history.deleteAll(function callback)

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

参数
function	callback	callback 参数应该是一个如下形式的函数： `function() {...};`

事件

onVisited

当访问某个 URL 时产生，并提供该 URL 的 HistoryItem 数据。这一事件在页面加载完成前产生。

addListener


                    chrome.history.onVisited.addListener(function callback)

参数

function

callback

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

function( HistoryItem result) {...};

HistoryItem

result

onVisitRemoved

当一个或多个 URL 从历史记录服务删除时产生，当所有访问都删除时 URL 将从历史记录中清除。

addListener


                    chrome.history.onVisitRemoved.addListener(function callback)

参数

function

callback

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

function(object removed) {...};

object

removed

boolean	allHistory	如果删除所有历史记录则为 true。如果为 true，urls 参数将为空。
array of string	（可选） urls

示例扩展程序

Typed URL History – Reads your history, and shows the top ten pages you go to by typing the URL.