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
包含历史记录的一个查询结果的对象。
-
url
(
optional
string
)
-
用户访问的 URL。
-
title
(
optional
string
)
-
上一次加载时该页面的标题。
-
lastVisitTime
(
optional
double
)
-
页面最后一次访问的时间，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。
-
visitCount
(
optional
integer
)
-
用户访问此页面的次数。
-
typedCount
(
optional
integer
)
-
用户通过在地址来中输入 URL 的方式访问此页面的次数。
VisitItem
包含对一个 URL 的某一次访问的对象。
-
visitId
(
string
)
-
本次访问的唯一标识符。
-
visitTime
(
optional
double
)
-
访问时间，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。
-
referringVisitId
(
string
)
-
引用者的访问所对应的标识符。
-
transition
(
enum of "link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "auto_toplevel", "form_submit", "reload", "keyword", or "keyword_generated"
)
-
这一次访问相对引用者的过渡类型。
方法
search
chrome.history.search(object query, function callback)
搜索历史记录，找出所有匹配页面的最后一次访问记录。
参数
-
query
(
object
)
-
-
属性
-
text
(
string
)
-
向历史记录服务发出的查询文本，如果为空则获取所有页面。
-
startTime
(
optional
double
)
-
将结果限制为此日期之后的访问，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。
-
endTime
(
optional
double
)
-
将结果限制为此日期之前的访问，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。
-
maxResults
(
optional
integer
)
-
要获得的最大结果数目，默认为 100。
callback 参数应该指定一个如下形式的函数：
function(array of HistoryItem results) {...};
getVisits
chrome.history.getVisits(object details, function callback)
获取有关某个 URL 的访问信息。
参数
-
details
(
object
)
-
-
属性
-
url
(
string
)
-
需要获取信息的 URL，必须与 search 调用的返回值具有相同的形式。
callback 参数应该指定一个如下形式的函数：
function(array of VisitItem results) {...};
addUrl
chrome.history.addUrl(object details, function callback)
向历史记录中以当前时间添加 URL，过渡类型为 "link"。
参数
-
callback
(
optional
function
)
-
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
deleteUrl
chrome.history.deleteUrl(object details, function callback)
从历史记录中删除出现给定 URL 的所有内容。
参数
-
callback
(
optional
function
)
-
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
deleteRange
chrome.history.deleteRange(object range, function callback)
删除指定日期范围内的所有历史记录，访问日期不在这一范围内的页面不会从历史记录中删除。
参数
-
range
(
object
)
-
-
属性
-
startTime
(
double
)
-
删除这一时间之后的添加历史记录，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。
-
endTime
(
double
)
-
删除这一时间之前的添加历史记录，表示为从 1970 年 1 月 1 日午夜开始所经过的毫秒数。
callback 参数应该指定一个如下形式的函数：
function() {...};
deleteAll
chrome.history.deleteAll(function callback)
删除历史记录中的所有项目。
参数
callback 参数应该指定一个如下形式的函数：
function() {...};
事件
onVisited
当访问某个 URL 时产生，并提供该 URL 的 HistoryItem 数据。这一事件在页面加载完成前产生。
addListener
chrome.history.onVisited.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(HistoryItem result) {...};
onVisitRemoved
当一个或多个 URL 从历史记录服务删除时产生，当所有访问都删除时 URL 将从历史记录中清除。
addListener
chrome.history.onVisitRemoved.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(object removed) {...};
-
removed
(
object
)
-
-
属性
-
allHistory
(
boolean
)
-
如果删除所有历史记录则为 true。如果为 true，urls 参数将为空。
-
urls
(
optional
array of string
)
-
chrome