chrome.history

說明

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

權限

history

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

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

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

概念與用途

轉場效果類型

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

範例

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

類型

HistoryItem

封裝歷來查詢結果的物件。

屬性

  • id

    字串

    項目的專屬 ID。

  • lastVisitTime

    號碼 選填

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

  • title

    字串 選填

    頁面上次載入時的標題。

  • typedCount

    號碼 選填

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

  • 網址

    字串 選填

    使用者前往的網址。

  • visitCount

    號碼 選填

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

TransitionType

Chrome 44 以上版本

這次造訪的轉換類型 (來自參照網址)。

列舉

「連結」
使用者點選其他網頁上的連結，來到這個網頁。

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

「auto_bookmark」
使用者是透過使用者介面中的建議 (例如選單項目) 來到這個頁面。

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

「manual_subframe」
使用者在子框架中選取項目，然後抵達這個頁面。

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

「auto_toplevel」
網頁是在命令列中指定，或是起始網頁。

「form_submit」
使用者填寫表單並提交後，抵達這個頁面。並非所有表單提交都會使用這種轉場效果。

「重新載入」
使用者重新載入網頁，方法是點選重新載入按鈕，或在網址列中按下 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()

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

在目前時間將網址新增至記錄，並將轉場效果類型設為「link」。

參數

傳回

  • Promise<void>

    Chrome 96 以上版本

deleteAll()

chrome.history.deleteAll(): Promise<void>

刪除記錄中的所有項目。

傳回

  • Promise<void>

    Chrome 96 以上版本

deleteRange()

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

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

參數

  • 範圍

    物件

    • endTime

      數字

      在此日期之前加入記錄的項目，以自 Epoch 紀元時間起算的毫秒數表示。

    • startTime

      數字

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

傳回

  • Promise<void>

    Chrome 96 以上版本

deleteUrl()

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

從記錄中移除指定網址的所有項目。

參數

傳回

  • Promise<void>

    Chrome 96 以上版本

getVisits()

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

擷取網址的造訪資訊。

參數

傳回

  • Promise<VisitItem[]>

    Chrome 96 以上版本 
chrome.history.search(
  query: object,
): Promise<HistoryItem[]>

搜尋符合查詢條件的每個網頁，找出上次造訪時間。

參數

  • 查詢

    物件

    • endTime

      號碼 選填

      只顯示在這個日期前造訪的結果，以 Epoch 紀元時間起算的毫秒數表示。

    • maxResults

      號碼 選填

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

    • startTime

      號碼 選填

      只顯示在此日期之後造訪的結果，以 Epoch 紀元時間起算的毫秒數表示。如未指定屬性，系統會預設為 24 小時。

    • 文字

      字串

      傳送給記錄服務的自由輸入查詢。如要擷取所有網頁，請將此欄位留空。

傳回

事件

onVisited

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

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

參數

onVisitRemoved

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

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

參數

  • callback

    函式

    callback 參數如下： 

    (removed: object) => void

    • 已移除

      物件

      • allHistory

        布林值

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

      • 網址

        字串陣列 選用