chrome.history

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

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 reference: chrome.history

Methods

addUrl

void chrome.history.addUrl(, object details)

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

Parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
要添加的URL。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

deleteAll

void chrome.history.deleteAll(, function callback)

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

Parameters

callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

回调函数的参数应当如下定义：

If you specify the callback parameter, it should specify a function that looks like this: 

function() {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

deleteRange

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

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

Parameters

range
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
startTime
( Type array of number )
条目添加起始时间， 以纪元开始的毫秒数表示。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
endTime
( Type array of number )
条目添加终止时间， 以纪元开始的毫秒数表示。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

回调函数的参数应当如下定义：

If you specify the callback parameter, it should specify a function that looks like this: 

function() {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

deleteUrl

void chrome.history.deleteUrl(, object details)

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

Parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
要删除的URL。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

getVisits

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

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

Parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
需要获取访问信息的URL。URL 必须与历史记录搜索的返回值格式一致。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

回调函数的参数应当如下定义：

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of VisitItem results) {...};
results
( Type array of VisitItem array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

search

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

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

Parameters

query
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
text
( Type array of string )
历史服务的文字查询。若想获取所有页面的信息，把此参数设置为空。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
startTime
( optional Type array of number )
限制结果访问日期至此日期之后, 以纪元开始的毫秒数表示。.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
endTime
( optional Type array of number )
限制结果访问日期至此日期以前, 以纪元开始的毫秒数表示。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
maxResults
( optional Type array of integer )
所获取结果的最大数目。 默认值为100。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

回调函数的参数应当如下定义：

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of HistoryItem results) {...};
results
( Type array of HistoryItem array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Events

onVisitRemoved

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

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

Parameters

removed
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
allHistory
( Type array of boolean )
如需删除所有历史记录，则设置成 True。如果设置成true, 所有url 为空。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
urls
( optional Type array of Type array of string paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

onVisited

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

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

Parameters

result
( HistoryItem array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Types

HistoryItem

paramName
( Type array of object )
封装历史查询结果的对象。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
id
( Type array of string )
条目的唯一标识符。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( optional Type array of string )
用户所访问的URL。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
title
( optional Type array of string )
历史页面的标题。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
lastVisitTime
( optional Type array of number )
页面被载入的最后时间, 以纪元开始的毫秒数表示。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
visitCount
( optional Type array of integer )
用户访问此页面的次数。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
typedCount
( optional Type array of integer )
用户通过地址栏输入访问目的页面的次数。

VisitItem

paramName
( Type array of object )
封装URL访问的对象。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
id
( Type array of string )
条目的唯一标识符。
visitId
( Type array of string )
访问的唯一标识符。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
visitTime
( optional Type array of number )
访问的时间， 以纪元开始的毫秒数表示。
referringVisitId
( Type array of string )
访问来源的 visit_id 。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
transition
( enumerated Type array of string ["link", "typed", "auto_bookmark", "auto_subframe", "manual_subframe", "generated", "start_page", "form_submit", "reload", "keyword", "keyword_generated"] )
访问来源的过渡类型。