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