browser.history

説明

chrome.history API を使用して、ブラウザのアクセスしたページの記録を操作します。ブラウザの履歴に URL を追加したり、履歴から URL を削除したり、履歴内の URL をクエリしたりできます。履歴ページを独自のバージョンでオーバーライドするには、ページのオーバーライドをご覧ください。

権限

history

ユーザーの閲覧履歴を操作するには、History API を使用します。

History API を使用するには、拡張機能マニフェストで "history" 権限を宣言します。次に例を示します。

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

コンセプトと使用方法

切り替え方法

履歴 API は、遷移タイプを使用して、ブラウザが特定の訪問で特定の URL に移動した方法を記述します。たとえば、ユーザーが別のページのリンクをクリックしてページにアクセスした場合、遷移タイプは「link」になります。遷移タイプの一覧については、リファレンス コンテンツをご覧ください。

例

この API を試すには、chrome-extension-samples リポジトリから history API の例をインストールします。

型

HistoryItem

履歴クエリの 1 つの結果をカプセル化するオブジェクト。

プロパティ

  • id

    文字列

    アイテムの固有識別子。

  • lastVisitTime

    number 省略可

    このページが最後に読み込まれた時刻（エポックからのミリ秒単位）。

  • title

    文字列 省略可

    最後に読み込まれたときのページのタイトル。

  • typedCount

    number 省略可

    ユーザーがアドレスを入力してこのページに移動した回数。

  • URL

    文字列 省略可

    ユーザーがアクセスした URL。

  • visitCount

    number 省略可

    ユーザーがこのページに移動した回数。

TransitionType

Chrome 44 以降 Chrome 148 以降の browser.*

この訪問の参照元からの遷移タイプ。

列挙型

"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

Chrome 88 以降 Chrome 148 以降の browser.*

プロパティ

  • URL

    文字列

    オペレーションの URL。history.search() の呼び出しから返される形式にする必要があります。

VisitItem

URL への 1 回のアクセスをカプセル化するオブジェクト。

プロパティ

  • id

    文字列

    対応する history.HistoryItem の固有識別子。

  • isLocal

    ブール値

    Chrome 115 以降 Chrome 148 以降の browser.*

    このデバイスで訪問が開始された場合は true。別のデバイスから同期された場合は false。

  • referringVisitId

    文字列

    参照元の訪問 ID。

  • transition

    TransitionType

    この訪問の参照元からの遷移タイプ。

  • visitId

    文字列

    この訪問の固有識別子。

  • visitTime

    number 省略可

    この訪問が発生した日時（エポックからのミリ秒数）。

メソッド

addUrl()

browser.history.addUrl(
  details: UrlDetails,
): Promise<void>

遷移タイプが「link」の URL を現在の時刻で履歴に追加します。

パラメータ

戻り値

  • Promise<void>

    Chrome 96 以降 Chrome 148 以降の browser.*

deleteAll()

browser.history.deleteAll(): Promise<void>

履歴からすべてのアイテムを削除します。

戻り値

  • Promise<void>

    Chrome 96 以降 Chrome 148 以降の browser.*

deleteRange()

browser.history.deleteRange(
  range: object,
): Promise<void>

指定した期間内のすべての項目を履歴から削除します。すべてのアクセスが期間内に収まらない限り、ページは履歴から削除されません。

パラメータ

  • 範囲

    オブジェクト

    • endTime

      数値

      この日付より前に履歴に追加されたアイテム（エポックからのミリ秒数で表されます）。

    • startTime

      数値

      この日付以降に履歴に追加されたアイテム。エポックからのミリ秒で表されます。

戻り値

  • Promise<void>

    Chrome 96 以降 Chrome 148 以降の browser.*

deleteUrl()

browser.history.deleteUrl(
  details: UrlDetails,
): Promise<void>

指定された URL のすべての出現箇所を履歴から削除します。

パラメータ

戻り値

  • Promise<void>

    Chrome 96 以降 Chrome 148 以降の browser.*

getVisits()

browser.history.getVisits(
  details: UrlDetails,
): Promise<VisitItem[]>

URL へのアクセスに関する情報を取得します。

パラメータ

戻り値

  • Promise<VisitItem[]>

    Chrome 96 以降 Chrome 148 以降の browser.* 
browser.history.search(
  query: object,
): Promise<HistoryItem[]>

クエリに一致する各ページの最終アクセス時刻を履歴から検索します。

パラメータ

  • クエリ

    オブジェクト

    • endTime

      number 省略可

      この日付より前にアクセスされた結果に限定します。エポックからのミリ秒単位で表されます。

    • maxResults

      number 省略可

      取得する結果の最大数。デフォルトは 100 です。

    • startTime

      number 省略可

      この日付以降にアクセスされた結果に限定します。エポックからのミリ秒数で表されます。プロパティが指定されていない場合、デフォルトは 24 時間になります。

    • テキスト

      文字列

      履歴サービスに対するフリーテキスト クエリ。すべてのページを取得するには、このフィールドを空のままにします。

戻り値

  • Promise<HistoryItem[]>

    Chrome 96 以降 Chrome 148 以降の browser.*

イベント

onVisited

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

URL にアクセスしたときに呼び出され、その URL の HistoryItem データを提供します。このイベントは、ページが読み込まれる前に発生します。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (result: HistoryItem) => void

onVisitRemoved

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

1 つ以上の URL が履歴から削除されたときに呼び出されます。すべての訪問履歴が削除されると、URL は履歴から消去されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (removed: object) => void

    • 削除済み

      オブジェクト

      • allHistory

        ブール値

        すべての履歴が削除された場合は true。true の場合、URL は空になります。

      • URL

        string[] 省略可