說明
使用 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
數字 選填
使用者瀏覽至這個網頁的次數。
列舉
"link"
使用者藉由在其他網頁上點選連結而到達這個網頁。
"typed"
使用者在網址列中輸入網址,到達這個網頁。這個角色也能用於其他明確的導覽動作。
"auto_bookmark"
使用者透過 UI 中的建議 (例如透過選單項目) 到達這個網頁。
"auto_subframe"
使用者透過未要求的子頁框瀏覽 (例如,在上一頁的頁框中載入廣告) 才到達此頁面。不一定會在返回和前進選單中產生新的導覽項目。
"manual_subframe"
使用者藉由選取子頁框中的項目到達此頁面。
"已產生"
使用者在網址列中輸入網址,並選取與網址不符的項目 (例如 Google 搜尋建議),系統便到達這個網頁。舉例來說,相符項目可能含有 Google 搜尋結果網頁的網址,但使用者看到的可能是「透過 Google 搜尋...」的內容。這類項目不同於使用者輸入或看到到達網頁網址的導覽。也與關鍵字導覽系統相關。
"auto_toplevel"
已透過指令列指定網頁,或該網頁為起始網頁。
"form_submit"
使用者在表單上填寫值並提交表單,進而到達此頁面。並非所有表單提交內容都會採用這種轉換類型。
"重新載入"
使用者透過按一下重新載入按鈕或在網址列按下 Enter 鍵,重新載入網頁。「工作���段還原」和「重新開啟已關閉」的分頁也會使用這個轉換類型。
"keyword"
這個網頁的網址是由可替換的關鍵字產生,而非預設搜尋引擎。
"keyword_generated"
代表關鍵字產生的造訪。
UrlDetails
屬性
-
url
字串
作業的網址。必須符合呼叫
history.search()
後傳回的格式。
VisitItem
封裝對某個網址一次造訪的物件。
屬性
-
id
字串
對應
history.HistoryItem
的專屬 ID。 -
isLocal
boolean
Chrome 115 以上版本如果造訪源自這部裝置,則為「是」。如果原先是透過其他裝置同步處理,則為「False」。
-
referringVisitId
字串
參照網址的造訪 ID。
-
這次造訪的轉換類型,由其參照網址提供。
-
visitId
字串
這次造訪的專屬 ID。
-
visitTime
數字 選填
造訪發生時,以 Epoch 紀元時間起算的毫秒為單位。
方法
addUrl()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
)
以「連結」的轉場類型在記錄中加入目前的網址。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
deleteAll()
chrome.history.deleteAll(
callback?: function,
)
從記錄中刪除所有項目。
參數
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
deleteRange()
chrome.history.deleteRange(
range: object,
callback?: function,
)
從記錄中移除指定日期範圍內的所有項目。除非所有造訪皆在範圍內,否則網頁不會從記錄中移除。
參數
-
範圍
物件
-
endTime
號碼
在這個日期之前新增至記錄的項目,以自 Epoch 紀元時間起算的毫秒為單位表示。
-
startTime
號碼
在這個日期之後新增至記錄的項目,以自 Epoch 紀元時間起算的毫秒為單位表示。
-
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
)
將指定網址的所有出現次數從記錄中移除。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
)
擷取網址造訪的相關資訊。
參數
-
詳細資料
-
回呼
函式選用
callback
參數如下所示:(results: VisitItem[]) => void
-
結果
-
傳回
-
Promise<VisitItem[]>
Chrome 96 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
search()
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
資料。這個事件會在網頁載入前觸發。
參數
-
回呼
功能
callback
參數如下所示:(result: HistoryItem) => void
-
結果
-
onVisitRemoved
chrome.history.onVisitRemoved.addListener(
callback: function,
)
一或多個網址從記錄中移除時觸發。當你移除所有造訪記錄後,網址就會從記錄中清除。
參數
-
回呼
功能
callback
參數如下所示:(removed: object) => void
-
已移除
物件
-
allHistory
boolean
如果移除所有記錄,則為「是」。如果設為 true,網址將空白。
-
urls
string[]��選填
-
-