---
title: history
slug: Mozilla/Add-ons/WebExtensions/API/history
tags:
  - API
  - Add-ons
  - Extensions
  - History
  - Interface
  - NeedsTranslation
  - Non-standard
  - Reference
  - TopicStub
  - WebExtensions
translation_of: Mozilla/Add-ons/WebExtensions/API/history
---
<div>{{AddonSidebar}}</div>

<p>使用 <code>history</code> API与浏览器历史记录进行交互。</p>

<div class="note">
<p>注意：下载也被当做一个 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/history/HistoryItem" title="A HistoryItem object provides information about a page in the browser history."><code>HistoryItem</code></a> 对象。因此，<code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/history/onVisited" title="Fired each time the user visits a page. A history.HistoryItem object is passed to the listener. This event fires before the page has loaded.">history.onVisited</a></code>等事件也会被下载所触发。</p>
</div>

<p>浏览器历史记录是对用户所访问的页面按时间顺序进行的记录和保存。history API 可以帮你实现以下功能：</p>

<ul>
 <li><a href="/en-US/Add-ons/WebExtensions/API/history/search">查找浏览器历史记录中出现过的页面</a></li>
 <li><a href="/en-US/Add-ons/WebExtensions/API/history/deleteUrl">移除浏览器历史记录中的单个页面</a></li>
 <li><a href="/en-US/Add-ons/WebExtensions/API/history/addUrl">向浏览器历史记录中添加页面</a></li>
 <li><a href="/en-US/Add-ons/WebExtensions/API/history/deleteAll">移除所有浏览器历史记录中的页面</a></li>
</ul>

<p>然而，用户可能多次访问单个页面，因此API中有访问集合“visits”的概念。所以，该API还可以做如下使用：</p>

<ul>
 <li><a href="/en-US/Add-ons/WebExtensions/API/history/getVisits">获取用户对单个页面的所有访问记录的集合</a></li>
 <li><a href="/en-US/Add-ons/WebExtensions/API/history/deleteRange">移除给定期间内任意页面的访问记录的集合</a></li>
</ul>

<p>使用该API之前，扩展程序必须在其 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a></code> 文件中获取history的<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">许可</a>。</p>

<h2 id="类型">类型</h2>

<dl>
 <dt>{{WebExtAPIRef("history.TransitionType")}}</dt>
 <dd>描述浏览器如何转到特定页面。</dd>
 <dt>{{WebExtAPIRef("history.HistoryItem")}}</dt>
 <dd>
 <p>提供浏览器历史记录中单个特定页面的详细信息。</p>
 </dd>
 <dt>{{WebExtAPIRef("history.VisitItem")}}</dt>
 <dd>
 <p>描述对一个页面的单次访问。</p>
 </dd>
</dl>

<h2 id="方法">方法</h2>

<dl>
 <dt>{{WebExtAPIRef("history.search()")}}</dt>
 <dd>在浏览器历史记录中查找符合给定条件的<code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/History/HistoryItem" title="A HistoryItem object provides information about one result from a history query.">history.HistoryItem</a></code></dd>
 <dt>{{WebExtAPIRef("history.getVisits()")}}</dt>
 <dd>获取指定页面的访问集信息。</dd>
 <dt>{{WebExtAPIRef("history.addUrl()")}}</dt>
 <dd>为浏览器历史记录添加一个指定页面的访问。</dd>
 <dt>{{WebExtAPIRef("history.deleteUrl()")}}</dt>
 <dd>移除浏览器历史记录中所有对指定URL的访问。</dd>
 <dt>{{WebExtAPIRef("history.deleteRange()")}}</dt>
 <dd>移除指定时间段内对用户指定页面的访问。</dd>
 <dt>{{WebExtAPIRef("history.deleteAll()")}}</dt>
 <dd>移除浏览器历史记录中的所有访问。</dd>
</dl>

<h2 id="事件">事件</h2>

<dl>
 <dt>{{WebExtAPIRef("history.onTitleChanged")}}</dt>
 <dd>
 <div>当用户访问的页面标题被记录时触发。</div>
 </dd>
 <dt>{{WebExtAPIRef("history.onVisited")}}</dt>
 <dd>每次用户访问页面时会触发，并提供该页面的 {{WebExtAPIRef("history.HistoryItem")}} 数据。</dd>
 <dt>{{WebExtAPIRef("history.onVisitRemoved")}}</dt>
 <dd>
 <p>当一个URL被彻底从浏览器历史记录中移除时触发。</p>
 </dd>
</dl>

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p>

<p>{{Compat("webextensions.api.history")}}</p>

<p>{{WebExtExamples("h2")}}</p>

<div class="note"><strong>致谢</strong>

<p>该 API 基于Chromium的<a href="https://developer.chrome.com/extensions/history"><code>chrome.history</code></a> API。该文档由Chromium代码中的<a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/history.json"><code>history.json</code></a>衍生而来。</p>

<p>微软 Edge 兼容性数据由微软公司提供并包含在如下证书中—— Creative Commons Attribution 3.0 United States License.</p>
</div>

<div class="hidden">
<pre>// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//    * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//    * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//    * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>
</div>