chrome.history

說明

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

權限

history

資訊清單

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

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

轉場效果類型

History API 會使用「轉換類型」說明瀏覽器前往特定網址的方式 即可。舉例來說，如果使用者點按其他網頁上的連結前往網頁， 轉場類型為「連結」

下表說明各種轉換類型。

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

範例

如要試用這個 API，請前往 chrome-extension-samples 安裝 history API 範例 Cloud Storage 也提供目錄同步處理功能

類型

HistoryItem

這個物件會封裝記錄查詢的其中一個結果。

屬性

  • id

    字串

    項目的專屬 ID。

  • lastVisitTime

    編號 選填

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

  • title

    string optional

    網頁上次載入時的標題。

  • typedCount

    編號 選填

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

  • 網址

    string optional

    使用者前往的網址。

  • visitCount

    編號 選填

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

TransitionType

Chrome 44 以上版本

本次造訪的轉換類型，來自其參照網址。

列舉

"link"
使用者透過其他網頁上的連結連到這個網頁。

&quot;typed&quot;
使用者在網址列中輸入網址而進入這個網頁。這個過程也適用於其他明確的導覽動作。

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

"auto_subframe"
使用者未請求的子頁框瀏覽 (例如在前一個頁面的頁框中載入廣告) 而到達此頁面。這些元件不一定在返回和向前選單中產生新的導覽項目。

"manual_subframe"
使用者是在子頁框中選取內容而進入這個頁面。

"已產生"
使用者在網址列中輸入並選取的網址 (例如 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 以上版本

    如果造訪源自這部裝置，則為「是」。如果是從其他裝置同步，則為 False。

  • referringVisitId

    字串

    參照網址的造訪 ID。

  • 本次造訪的轉換類型，來自其參照網址。

  • visitId

    字串

    本次造訪的專屬 ID。

  • visitTime

    編號 選填

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

方法

addUrl()

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

使用「連結」的轉換類型在目前記錄中新增網址。

參數

  • 詳細資料

    UrlDetails

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

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

deleteAll()

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

刪除記錄中的所有項目。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

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

deleteRange()

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

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

參數

  • 範圍

    物件

    • endTime

      數字

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

    • startTime

      數字

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

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

deleteUrl()

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

從記錄中移除發生的所有指定網址。

參數

  • 詳細資料

    UrlDetails

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

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

getVisits()

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

擷取網址造訪資訊。

參數

傳回

  • Promise&lt;VisitItem[]&gt;

    Chrome 96 以上版本

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

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

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

參數

  • 查詢

    物件

    • endTime

      編號 選填

      只顯示此日期前造訪過的結果 (以 Epoch 紀元時間起算的毫秒數) 顯示的結果。

    • maxResults

      編號 選填

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

    • startTime

      編號 選填

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

    • 文字

      字串

      查詢記錄服務的任意文字查詢。如要擷取所有頁面，請將這個欄位留白。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (results: HistoryItem[]) => void

傳回

  • Promise&lt;HistoryItem[]&gt;

    Chrome 96 以上版本

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

活動

onVisited

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

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

參數

onVisitRemoved

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (removed: object) => void

    • 已移除

      物件

      • allHistory

        布林值

        如果刪除所有記錄，則為「是」。如果設為 true，網址將不會留空。

      • 網址

        string[] 選填