chrome.history

說明

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

權限

history

如要與使用者的瀏覽器記錄互動，請使用 history API。

如要使用 History API，請在擴充功能資訊清單中宣告 "history" 權限。舉例來說：

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

概念和用法

轉換類型

記錄 API 使用轉換類型，說明瀏覽器在特定造訪中如何前往特定網址。舉例來說，如果使用者透過點選其他網頁上的連結前往某個網頁，轉換類型就會是「連結」。如需轉換類型的清單，請參閱參考內容。

示例

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

類型

HistoryItem

這種物件會封裝歷史記錄查詢的一項結果。

屬性

  • id

    字串

    項目的專屬 ID。

  • lastVisitTime

    數字 選填

    上次載入這個網頁的時間，以 Epoch 紀元時間起算的毫秒為單位。

  • title

    字串 選用

    網頁上次載入時的標題。

  • typedCount

    數字 選填

    使用者透過輸入網址的方式造訪這個網頁的次數。

  • url

    字串 選用

    使用者前往的網址。

  • visitCount

    數字 選填

    使用者瀏覽至這個網頁的次數。

TransitionType

Chrome 44 以上版本

這次造訪的轉換類型，由其參照網址提供。

列舉

"link"
使用者藉由在其他網頁上點選連結而到達這個網頁。

"typed"
使用者在網址列中輸入網址，到達這個網頁。這個角色也能用於其他明確的導覽動作。

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

"auto_subframe"
使用者透過未要求的子頁框瀏覽 (例如，在上一頁的頁框中載入廣告) 才到達此頁面。不一定會在返回和前進選單中產生新的導覽項目。

"manual_subframe"
使用者藉由選取子頁框中的項目到達此頁面。

"已產生"
使用者在網址列中輸入網址，並選取與網址不符的項目 (例如 Google 搜尋建議)，系統便到達這個網頁。舉例來說，相符項目可能含有 Google 搜尋結果網頁的網址，但使用者看到的可能是「透過 Google 搜尋...」的內容。這類項目不同於使用者輸入或看到到達網頁網址的導覽。也與關鍵字導覽系統相關。

"auto_toplevel"
已透過指令列指定網頁，或該網頁為起始網頁。

"form_submit"
使用者在表單上填寫值並提交表單，進而到達此頁面。並非所有表單提交內容都會採用這種轉換類型。

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

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

"keyword_generated"
代表關鍵字產生的造訪。

UrlDetails

Chrome 88 以上版本

屬性

  • url

    字串

    作業的網址。必須符合呼叫 history.search() 後傳回的格式。

VisitItem

封裝對某個網址一次造訪的物件。

屬性

  • id

    字串

    對應 history.HistoryItem 的專屬 ID。

  • isLocal

    boolean

    Chrome 115 以上版本

    如果造訪源自這部裝置，則為「是」。如果原先是透過其他裝置同步處理，則為「False」。

  • referringVisitId

    字串

    參照網址的造訪 ID。

  • 這次造訪的轉換類型，由其參照網址提供。

  • visitId

    字串

    這次造訪的專屬 ID。

  • visitTime

    數字 選填

    造訪發生時，以 Epoch 紀元時間起算的毫秒為單位。

方法

addUrl()

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

以「連結」的轉場類型在記錄中加入目前的網址。

參數

  • 詳細資料

    UrlDetails

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

deleteAll()

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

從記錄中刪除所有項目。

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

deleteRange()

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

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

參數

  • 範圍

    物件

    • endTime

      號碼

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

    • startTime

      號碼

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

deleteUrl()

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

將指定網址的所有出現次數從記錄中移除。

參數

  • 詳細資料

    UrlDetails

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getVisits()

Promise 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

擷取網址造訪的相關資訊。

參數

傳回

  • Promise<VisitItem[]>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

Promise 
chrome.history.search(
  query: object,
  callback?: function,
)

搜尋符合查詢的每個網頁上次造訪時間的記錄。

參數

  • 項查詢

    物件

    • endTime

      數字 選填

      只顯示這個日期之前造訪過的使用者結果，以自指定週期以來的毫秒為單位顯示。

    • maxResults

      數字 選填

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

    • startTime

      數字 選填

      只顯示這個日期之後造訪的搜尋結果，以自指定週期以來的毫秒為單位顯示。如未指定屬性，則預設為 24 小時。

    • text

      字串

      向歷史紀錄服務的任意文字查詢。如要擷取所有網頁，請將這個欄位留空。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (results: HistoryItem[])=>void

傳回

  • Promise<HistoryItem[]>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

onVisited

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

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

參數

onVisitRemoved

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

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

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (removed: object)=>void

    • 已移除

      物件

      • allHistory

        boolean

        如果移除所有記錄，則為「是」。如果設為 true，網址將空白。

      • urls

        string[] 選填