chrome.history

refresh date: 2026-09-25 robots: noindex

說明

使用 chrome.history API 與瀏覽器的造訪網頁記錄互動。您可以在瀏覽器的記錄中新增、移除及查詢網址。如要使用自己的版本覆寫記錄頁面，請參閱「覆寫頁面」。

權限

history

資訊清單

您必須在擴充功能資訊清單中宣告「history」權限，才能使用 History API。例如：

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

轉場類型

History API 會使用轉場類型，說明瀏覽器在特定造訪中如何前往特定網址。舉例來說，如果使用者點選其他網頁上的連結來造訪網頁，轉場類型就是「link」。

下表說明各個轉場類型。

轉場類型說明
"typed"使用者在網址列輸入網址，前往這個網頁。也可用於其他明確的導覽動作。另請參閱 generated，這適用於使用者選取的選項完全不像網址的情況。
"auto_bookmark"使用者透過 UI 中的建議 (例如選單項目) 進入這個頁面。
"auto_subframe"子頁框導覽。這類內容會自動載入非頂層頁框。舉例來說，如果網頁包含多個含有廣告的頁框，這些廣告網址就會有這種轉場類型。使用者甚至可能不會注意到這些網頁中的內容是獨立框架，因此可能不會在意網址 (另請參閱 manual_subframe)。
"manual_subframe"使用者明確要求子頁框導覽，並在返回/前進清單中產生新的導覽項目。明確要求的頁框可能比自動載入的頁框更重要，因為使用者可能更在意要求的頁框是否載入。
「generated」使用者在網址列中輸入內容，並選取不像是網址的項目，因而進入這個網頁。舉例來說，相符項目可能包含 Google 搜尋結果網頁的網址，但使用者看到的是「在 Google 上搜尋...」。這與輸入導覽不完全相同，因為使用者並未輸入或看到到達網頁網址。另請參閱「關鍵字」。
"auto_toplevel"在指令列中指定或做為起始頁面的網頁。
「form_submit」使用者在表單中填寫值並提交。請注意，在某些情況下 (例如表單使用指令碼提交內容)，提交表單不會產生這類轉場類型。
「reload」使用者點選重新載入按鈕，或在網址列按下 Enter 鍵，重新載入網頁。還原工作階段和重新開啟已關閉的分頁，也會使用這個轉場類型。
"關鍵字"網址是由預設搜尋引擎以外的可替換關鍵字產生。另請參閱 keyword_generated。
「keyword_generated」對應至關鍵字產生的造訪。另請參閱「關鍵字」。

範例

如要試用這個 API，請從 chrome-extension-samples 存放區安裝 History API 範例。

類型

HistoryItem

封裝一項記錄查詢結果的物件。

屬性

  • id

    字串

    項目的專屬 ID。

  • lastVisitTime

    數字 選填

    上次載入這個頁面的時間，以從 Epoch 紀元時間算起的毫秒數表示。

  • title

    字串 選填

    上次載入時的網頁標題。

  • typedCount

    數字 選填

    使用者輸入網址前往這個網頁的次數。

  • 網址

    字串 選填

    使用者前往的網址。

  • visitCount

    數字 選填

    使用者前往這個頁面的次數。

TransitionType

Chrome 44 以上版本

這次造訪從參照網址轉換的轉換類型。

列舉

"link"
使用者點選其他網頁上的連結後，到達這個網頁。

「typed」
使用者在網址列輸入網址，到達這個網頁。這也適用於其他明確的導覽動作。

"auto_bookmark"
使用者透過使用者介面中的建議 (例如選單項目) 抵達這個頁面。

"auto_subframe"
使用者透過非要求的子頁框導覽到達這個網頁，例如透過前一頁頁框中載入的廣告。這些動作不一定會在返回和前進選單中產生新的導覽項目。

"manual_subframe"
使用者選取子頁框中的內容後，到達這個網頁。

"generated"
使用者在網址列中輸入內容，並選取看起來不像網址的項目 (例如 Google 搜尋建議)，因而到達這個網頁。舉例來說，比對結果可能包含 Google 搜尋結果網頁的網址，但使用者看到的是「在 Google 上搜尋...」。這與輸入網址瀏覽不同，因為使用者並未輸入或看到到達網頁網址。也與關鍵字導覽有關。

"auto_toplevel"
在指令列中指定或為起始頁面的網頁。

「form_submit」
使用者填寫並提交表單後，到達這個網頁。並非所有表單提交都會使用這種轉換類型。

「reload」
使用者重新載入網頁，可能是點選重新載入按鈕，或在網址列中按下 Enter 鍵。「還原工作階段」和「重新開啟已關閉的分頁」也會使用這個轉換類型。

"keyword"
這個網頁的網址是由預設搜尋引擎以外的可替換關鍵字產生。

"keyword_generated"
對應至關鍵字產生的造訪。

UrlDetails

Chrome 88 以上版本

屬性

  • 網址

    字串

    作業的網址。格式必須與呼叫 history.search() 傳回的格式相同。

VisitItem

封裝單次網址造訪的物件。

屬性

  • id

    字串

    對應 history.HistoryItem 的專屬 ID。

  • isLocal

    布林值

    Chrome 115 以上版本

    如果造訪記錄源自這部裝置，則為 True。如果從其他裝置同步，則為 False。

  • referringVisitId

    字串

    參照網址的造訪 ID。

  • 這次造訪從參照網址轉換的轉換類型。

  • visitId

    字串

    這筆造訪的專屬 ID。

  • visitTime

    數字 選填

    這次造訪發生的時間，以 Epoch 紀元時間起算的毫秒數表示。

方法

addUrl()

Promise 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

在目前時間將網址新增至歷史記錄，轉換類型為「link」。

參數

  • 詳細資料

    UrlDetails

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

deleteAll()

Promise 
chrome.history.deleteAll(
  callback?: function,
): Promise<void>

刪除記錄中的所有項目。

參數

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

deleteRange()

Promise 
chrome.history.deleteRange(
  range: object,
  callback?: function,
): Promise<void>

從記錄中移除指定日期範圍內的所有項目。除非所有造訪記錄都在指定範圍內，否則系統不會從歷史記錄中移除網頁。

參數

  • 範圍

    物件

    • endTime

      數字

      在這個日期之前新增至記錄的項目，以 Epoch 紀元時間起算的毫秒數表示。

    • startTime

      數字

      在這個日期之後新增至記錄的項目，以從 Epoch 紀元時間算起的毫秒數表示。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

deleteUrl()

Promise 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

從歷史記錄中移除指定網址的所有記錄。

參數

  • 詳細資料

    UrlDetails

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getVisits()

Promise 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

擷取網址造訪資訊。

參數

傳回

  • Promise<VisitItem[]>

    Chrome 96 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

Promise 
chrome.history.search(
  query: object,
  callback?: function,
): Promise<HistoryItem[]>

在歷史記錄中搜尋與查詢相符的每個網頁，並找出上次造訪時間。

參數

  • 查詢

    物件

    • endTime

      數字 選填

      僅限在這個日期之前造訪的結果，以自紀元起算的毫秒數表示。

    • maxResults

      數字 選填

      要擷取的結果數量上限。預設值為 100。

    • startTime

      數字 選填

      僅限於這個日期之後造訪的結果，以從 Epoch 紀元時間算起的毫秒數表示。如未指定屬性，則預設為 24 小時。

    • 文字

      字串

      向記錄服務提出的自由格式文字查詢。如要擷取所有頁面，請將這個欄位留空。

  • callback

    函式 選填

    callback 參數如下： 

    (results: HistoryItem[]) => void

傳回

  • Promise<HistoryItem[]>

    Chrome 96 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

事件

onVisited

chrome.history.onVisited.addListener(
  callback: function,
)

使用者造訪網址時觸發，提供該網址的 HistoryItem 資料。這個事件會在網頁載入前觸發。

參數

onVisitRemoved

chrome.history.onVisitRemoved.addListener(
  callback: function,
)

從歷史記錄中移除一或多個網址時觸發。移除所有造訪記錄後，網址就會從歷史記錄中清除。

參數

  • callback

    函式

    callback 參數如下： 

    (removed: object) => void

    • 已移除

      物件

      • allHistory

        布林值

        如果所有記錄都已移除，則為 True。如果為 true，網址會留空。

      • 網址

        string[] 選填