説明
chrome.history API を使用して、ブラウザのアクセス済みページの記録を操作します。ブラウザの履歴で URL の追加、削除、クエリを行うことができます。履歴ページを独自のバージョンでオーバーライドするには、ページのオーバーライドをご覧ください。
権限
historyユーザーのブラウザの履歴を操作するには、履歴 API を使用します。
履歴 API を使用するには、拡張機能のマニフェストで "history" 権限を宣言します。次に例を示します。
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
コンセプトと使用方法
切り替え効果の種類
履歴 API は、特定のアクセスでブラウザが特定の URL に移動した方法を記述するために、遷移タイプを使用します。たとえば、ユーザーが別のページのリンクをクリックしてページにアクセスした場合、遷移タイプは「リンク」になります。移行タイプのリストについては、リファレンス コンテンツをご覧ください。
例
この API を試すには、chrome-extension-samples リポジトリから履歴 API のサンプルをインストールします。
型
HistoryItem
履歴クエリの結果を 1 つカプセル化するオブジェクト。
プロパティ
-
id
文字列
アイテムの一意の識別子。
-
lastVisitTime
number 省略可
このページが最後に読み込まれた日時（エポックからのミリ秒単位）。
-
title
文字列 省略可
最後に読み込まれたときのページのタイトル。
-
typedCount
number 省略可
ユーザーがアドレスを入力してこのページに移動した回数。
-
URL
文字列 省略可
ユーザーがアクセスした URL。
-
visitCount
number 省略可
ユーザーがこのページに移動した回数。
列挙型
「link」
ユーザーが別のページのリンクをクリックしてこのページにアクセスしました。
「typed」
ユーザーがアドレスバーに URL を入力してこのページにアクセスしました。これは、他の明示的なナビゲーション アクションにも使用されます。
「auto_bookmark」
ユーザーが UI の候補（メニュー項目など）からこのページにアクセスしました。
「auto_subframe」
ユーザーが、前のページのフレームに読み込まれた広告など、リクエストしていないサブフレーム ナビゲーションによってこのページに到達しました。これらの操作では、必ずしも [戻る] メニューと [進む] メニューに新しいナビゲーション エントリが生成されるとは限りません。
「manual_subframe」
ユーザーがサブフレームで何かを選択してこのページにアクセスした。
「generated」
ユーザーがアドレスバーに入力し、Google 検索の候補など、URL ではないエントリを選択してこのページにアクセスしました。たとえば、一致する URL が Google 検索結果ページの URL であっても、ユーザーには「Google で ... を検索」と表示されることがあります。ユーザーが宛先 URL を入力したり、目にしたりしていないため、これは入力によるナビゲーションとは異なります。キーワード ナビゲーションにも関連しています。
「auto_toplevel」
コマンドラインでページが指定されたか、スタートページです。
「form_submit」
ユーザーがフォームに値を入力して送信し、このページに到達しました。すべてのフォーム送信でこの遷移タイプが使用されるわけではありません。
「reload」
ユーザーが再読み込みボタンをクリックするか、アドレスバーで Enter キーを押して、ページを再読み込みしました。セッションの復元と [閉じたタブを開く] でも、このトランジション タイプが使用されます。
「キーワード」
このページの URL は、デフォルトの検索プロバイダ以外の置換可能なキーワードから生成されました。
「keyword_generated」
キーワード用に生成されたアクセスに対応します。
UrlDetails
プロパティ
-
URL
文字列
オペレーションの URL。
history.search()の呼び出しから返される形式にする必要があります。
VisitItem
URL への 1 回のアクセスをカプセル化するオブジェクト。
プロパティ
-
id
文字列
対応する
history.HistoryItemの一意の識別子。 -
isLocal
ブール値
Chrome 115 以降このデバイスでセッションが開始された場合は true。別のデバイスから同期された場合は false。
-
referringVisitId
文字列
リファラーの訪問 ID。
-
transition
このサイトへの訪問のトランジション タイプ（リファラーから）。
-
visitId
文字列
この訪問の一意の識別子。
-
visitTime
number 省略可
このアクセスが発生した日時（エポックからのミリ秒数）。
メソッド
addUrl()
chrome.history.addUrl(
details: UrlDetails,
): Promise<void>
現在の時刻の履歴に、遷移タイプが「link」の URL を追加します。
パラメータ
-
詳細
戻り値
-
Promise<void>
Chrome 96 以降
deleteAll()
chrome.history.deleteAll(): Promise<void>
履歴からすべてのアイテムを削除します。
戻り値
-
Promise<void>
Chrome 96 以降
deleteRange()
chrome.history.deleteRange(
range: object,
): Promise<void>
指定した期間内のすべてのアイテムを履歴から削除します。すべてのアクセスが範囲内に収まらない限り、ページは履歴から削除されません。
パラメータ
-
範囲
オブジェクト
-
endTime
数値
この日付より前に履歴に追加されたアイテム。エポックからのミリ秒で表されます。
-
startTime
数値
この日付以降に履歴に追加されたアイテム（エポックからのミリ秒単位）。
-
戻り値
-
Promise<void>
Chrome 96 以降
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
): Promise<void>
指定された URL のすべての出現を履歴から削除します。
パラメータ
-
詳細
戻り値
-
Promise<void>
Chrome 96 以降
getVisits()
chrome.history.getVisits(
details: UrlDetails,
): Promise<VisitItem[]>
URL へのアクセスに関する情報を取得します。
パラメータ
-
詳細
戻り値
-
Promise<VisitItem[]>
Chrome 96 以降
search()
chrome.history.search(
query: object,
): Promise<HistoryItem[]>
クエリに一致する各ページの最終アクセス時刻を履歴から検索します。
パラメータ
-
クエリ
オブジェクト
-
endTime
number 省略可
この日付より前にアクセスした結果に限定します。日付はエポックからのミリ秒で表します。
-
maxResults
number 省略可
取得する結果の最大数。デフォルトは 100 です。
-
startTime
number 省略可
この日付以降にアクセスした結果に限定します。エポックからのミリ秒で表されます。プロパティが指定されていない場合、デフォルトは 24 時間になります。
-
テキスト
文字列
履歴サービスに対するフリーテキスト クエリ。すべてのページを取得するには、この値を空白のままにします。
-
戻り値
-
Promise<HistoryItem[]>
Chrome 96 以降
イベント
onVisited
chrome.history.onVisited.addListener(
callback: function,
)
URL にアクセスしたときに呼び出され、その URL の HistoryItem データが提供されます。このイベントは、ページが読み込まれる前に発生します。
パラメータ
-
callback
関数
callbackパラメータは次のようになります。(result: HistoryItem) => void
-
件の結果
-
onVisitRemoved
chrome.history.onVisitRemoved.addListener(
callback: function,
)
1 つ以上の URL が履歴から削除されたときに発生します。すべてのアクセス履歴が削除されると、URL が履歴から削除されます。
パラメータ
-
callback
関数
callbackパラメータは次のようになります。(removed: object) => void
-
削除済み
オブジェクト
-
allHistory
ブール値
すべての履歴が削除された場合は true。true の場合、URL は空になります。
-
URL
string[] 省略可
-
-