說明
使用 chrome.history
API,與瀏覽器的瀏覽記錄互動。你可以在瀏覽器記錄中新增、移除及查詢網址。如要使用您的版本覆寫記錄頁面,請參閱覆寫頁面。
權限
history
如要與使用者的瀏覽器紀錄互動,請使用 history API。
如要使用 History API,請在擴充功能資訊清單中宣告 "history"
權限。例如:
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
概念和用法
轉場效果類型
History API 會使用轉換類型,說明瀏覽器如何前往特定網址 即可。舉例來說,如果使用者點按其他網頁上的連結前往網頁, 轉場類型為「連結」如需這份清單,請參閱參考內容的清單 轉場效果
範例
如要試用這個 API,請前往 chrome-extension-samples 安裝 history API 範例 Cloud Storage 也提供目錄同步處理功能
類型
HistoryItem
這個物件會封裝記錄查詢的其中一個結果。
屬性
-
id
字串
項目的專屬 ID。
-
lastVisitTime
編號 選填
此頁面上次載入時,以 Epoch 紀元時間起算的毫秒數表示。
-
title
string optional
網頁上次載入時的標題。
-
typedCount
編號 選填
使用者輸入網址前往這個網頁的次數。
-
網址
string optional
使用者前往的網址。
-
visitCount
編號 選填
使用者前往這個頁面的次數。
列舉
"link"
使用者透過其他網頁上的連結連到這個網頁。
"typed"
使用者在網址列中輸入網址而進入這個網頁。這個過程也適用於其他明確的導覽動作。
"auto_bookmark"
使用者透過使用者介面中的建議 (例如選單項目) 到達這個網頁。
"auto_subframe"
使用者未請求的子頁框瀏覽 (例如在前一個頁面的頁框中載入廣告) 而到達此頁面。這些元件不一定在返回和向前選單中產生新的導覽項目。
"manual_subframe"
使用者是在子頁框中選取內容而進入這個頁面。
"已產生"
使用者在網址列中輸入並選取的網址 (例如 Google 搜尋建議),因而連到這個網頁。舉例來說,如果相符項目的網址可能是 Google 搜尋結果網頁,但使用者可能會看到「透過 Google 搜尋...」。和輸入的導覽不同,因為使用者沒有輸入或看到到達網頁網址。也與關鍵字導覽功能有關。
"auto_toplevel"
已透過指令列指定頁面,或為起始網頁。
"form_submit"
使用者在表單中填寫值並提交表單,到達這個網頁。並非所有提交的表單都使用這種轉換類型。
"reload"
使用者透過點選「重新載入」按鈕,或按下網址列中的 Enter 鍵,重新載入頁面。「工作階段還原」和「重新開啟已關閉」分頁也會使用這個轉換類型。
"keyword"
這個網頁的網址來自預設搜尋引擎以外的可替換關鍵字。
"keyword_generated"
代表關鍵字產生的造訪。
UrlDetails
屬性
-
網址
字串
作業的網址。這個值必須採用呼叫
history.search()
所傳回的格式。
VisitItem
這個物件會封裝網址的一次造訪。
屬性
-
id
字串
對應
history.HistoryItem
的專屬 ID。 -
isLocal
布林值
Chrome 115 以上版本如果造訪源自這部裝置,則為「是」。如果是從其他裝置同步,則為 False。
-
referringVisitId
字串
參照網址的造訪 ID。
-
本次造訪的轉換類型,來自其參照網址。
-
visitId
字串
本次造訪的專屬 ID。
-
visitTime
編號 選填
此次造訪發生時,以 Epoch 紀元時間起算的毫秒數表示。
方法
addUrl()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
)
使用「連結」的轉換類型在目前記錄中新增網址。
參數
-
詳細資料
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Chrome 96 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
deleteAll()
chrome.history.deleteAll(
callback?: function,
)
刪除記錄中的所有項目。
參數
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Chrome 96 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
deleteRange()
chrome.history.deleteRange(
range: object,
callback?: function,
)
從記錄中移除指定日期範圍內的所有項目。網頁不會從歷史記錄中移除,除非所有造訪都落在指定範圍內。
參數
-
範圍
物件
-
endTime
數字
在此日期前新增到記錄的項目,以自 Epoch 紀元時間起算的毫秒數表示。
-
startTime
數字
在此日期之後新增至記錄的項目,以自 Epoch 紀元時間起算的毫秒數表示。
-
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Chrome 96 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
)
從記錄中移除發生的所有指定網址。
參數
-
詳細資料
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Chrome 96 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
參數
-
詳細資料
-
回呼
函式 選用
callback
參數如下所示:(results: VisitItem[]) => void
-
結果
-
傳回
-
Promise<VisitItem[]>
Chrome 96 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
search()
chrome.history.search(
query: object,
callback?: function,
)
搜尋每個符合查詢的網頁上次造訪時間的記錄。
參數
-
查詢
物件
-
endTime
編號 選填
只顯示此日期前造訪過的結果 (以 Epoch 紀元時間起算的毫秒數) 顯示的結果。
-
maxResults
編號 選填
要擷取的結果數量上限。預設值為 100。
-
startTime
編號 選填
只顯示此日期之後造訪過的結果 (以 Epoch 紀元時間起算的毫秒數表示)。如未指定屬性,系統會將其預設為 24 小時。
-
文字
字串
查詢記錄服務的任意文字查詢。如要擷取所有頁面,請將這個欄位留白。
-
-
回呼
函式 選用
callback
參數如下所示:(results: HistoryItem[]) => void
-
結果
-
傳回
-
Promise<HistoryItem[]>
Chrome 96 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
活動
onVisited
chrome.history.onVisited.addListener(
callback: function,
)
使用者造訪網址時觸發,並提供該網址的 HistoryItem
資料。這個事件會在網頁載入前觸發。
參數
-
回呼
函式
callback
參數如下所示:(result: HistoryItem) => void
-
結果
-
onVisitRemoved
chrome.history.onVisitRemoved.addListener(
callback: function,
)
一或多個網址從記錄中移除時觸發。移除所有造訪記錄之後,網址就會從記錄中清除。
參數
-
回呼
函式
callback
參數如下所示:(removed: object) => void
-
已移除
物件
-
allHistory
布林值
如果刪除所有記錄,則為「是」。如果設為 true,網址將不會留空。
-
網址
string[] 選填
-
-