chrome.history

説明

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（省略可）

    ユーザーがこのページにアクセスした回数。

TransitionType

Chrome 44 以降

参照 URL からのこの訪問の移行タイプ。

列挙型

"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 以降

プロパティ

  • URL

    文字列

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

VisitItem

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

プロパティ

  • id

    文字列

    対応する history.HistoryItem の一意の識別子。

  • isLocal

    boolean

    Chrome 115 以降

    アクセスがこのデバイスから開始された場合は true。別のデバイスから同期された場合は false。

  • referringVisitId

    文字列

    参照 URL の訪問 ID。

  • transition

    TransitionType

    参照 URL からのこの訪問の移行タイプ。

  • visitId

    文字列

    この訪問の一意の識別子。

  • visitTime

    number（省略可）

    このアクセスが発生した時間（エポックからのミリ秒数）。

Methods

addUrl()

Promise 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

移行タイプを「link」にして、現在の時刻の履歴に URL を追加します。

パラメータ

  • 詳細

    UrlDetails

  • callback

    関数（省略可）

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

deleteAll()

Promise 
chrome.history.deleteAll(
  callback?: function,
)

履歴からすべての項目を削除します。

パラメータ

  • callback

    関数（省略可）

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

deleteRange()

Promise 
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

指定した期間内のすべてのアイテムを履歴から削除します。すべての訪問が範囲内に収まらない限り、ページは履歴から削除されません。

パラメータ

  • 範囲

    オブジェクト

    • endTime

      数値

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

    • startTime

      数値

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

  • callback

    関数（省略可）

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

deleteUrl()

Promise 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

指定された URL の出現回数を履歴から削除します。

パラメータ

  • 詳細

    UrlDetails

  • callback

    関数（省略可）

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

getVisits()

Promise 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

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

パラメータ

  • 詳細

    UrlDetails

  • callback

    関数（省略可）

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

    (results: VisitItem[])=>void

戻り値

  • Promise<VisitItem[]>

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

Promise 
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[] 省略可