chrome.history

説明

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

権限

history

マニフェスト

「履歴」を申告する必要がある拡張機能のマニフェストで History API の使用を許可する必要があります。次に例を示します。

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

切り替え効果の種類

History API は遷移タイプを使用して、ブラウザが特定の URL にどのように移動したかを示します。 確認できますたとえば、ユーザーが別のページのリンクをクリックしてページにアクセスした場合、 切り替え効果の種類が「link」です。

次の表に、各遷移タイプを示します。

切り替え効果の種類説明
"typed"このページは、ユーザーがアドレスバーに URL を入力して表示されました。その他の明示的なナビゲーション アクションにも使用されます。生成済みもご覧ください。これは、ユーザーが選択した選択内容が URL とまったく異なっている場合に使用します。
「auto_bookmark」ユーザーが UI の候補（メニュー項目など）からこのページにアクセスした。
「auto_subframe」サブフレーム ナビゲーション。非トップレベル フレームで自動的に読み込まれるコンテンツです。たとえば、複数のフレームに広告を含むページが構成されている場合、広告の URL にはこの切り替え効果が表示されます。ユーザーは、これらのページのコンテンツが別のフレームであることに気付いていないため、URL を気にしない可能性があります（manual_subframe もご覧ください）。
「manual_subframe」ユーザーが明示的にリクエストしたサブフレーム ナビゲーションの場合、バックフォワード リストに新しいナビゲーション エントリを生成します。多くの場合、ユーザーはリクエストされたフレームが読み込まれたことを気にかけているため、自動的に読み込まれたフレームよりも明示的にリクエストされたフレームの方が重要です。
"生成済み"ユーザーは、アドレスバーに入力し、URL のように見えないエントリを選択して、このページにアクセスしています。たとえば、Google 検索結果ページの URL が含まれていても、「Google で...を検索」と表示される場合があります。これは、ユーザーがリンク先 URL を入力しない、または表示しないため、タイプによるナビゲーションとはまったく異なります。キーワードもご覧ください。
「auto_toplevel」コマンドラインまたはスタートページで指定されているページ。
「form_submit」ユーザーがフォームに値を入力して送信しました。なお、フォームがスクリプトを使用してコンテンツを送信する場合など、フォームを送信してもこのような移行タイプにはならない場合があります。
「再読み込み」ユーザーが再読み込みボタンをクリックするか、アドレスバーで Enter キーを押して、ページを再読み込みしました。セッションの復元と閉じたタブを再開する場合も、この移行タイプが使用されます。
"キーワード"URL が、デフォルトの検索プロバイダ以外の置換可能なキーワードから生成されました。keyword_generated もご覧ください。
"keyword_generated"キーワードに対して生成された訪問に対応します。キーワードもご覧ください。

例

この API を試すには、chrome-extension-samples から History API の例をインストールしてください。 できます。

型

HistoryItem

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

プロパティ

  • id

    文字列

    商品アイテムの一意の識別子。

  • lastVisitTime

    数値（省略可）

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

  • title

    文字列（省略可）

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

  • typedCount

    数値（省略可）

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

  • URL

    文字列（省略可）

    ユーザーが移動した URL。

  • visitCount

    数値（省略可）

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

TransitionType

Chrome 44 以降

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

列挙型

"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

    ブール値

    Chrome 115 以降

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

  • referringVisitId

    文字列

    参照 URL の訪問 ID。

  • transition

    TransitionType

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

  • visitId

    文字列

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

  • visitTime

    数値（省略可）

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

メソッド

addUrl()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

現在の時刻の履歴に「リンク」の移行タイプの URL を追加します。

パラメータ

  • 詳細

    UrlDetails

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

deleteAll()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.history.deleteAll(
  callback?: function,
)

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

パラメータ

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

deleteRange()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

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

パラメータ

  • 範囲

    オブジェクト

    • endTime

      数値

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

    • startTime

      数値

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

deleteUrl()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

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

パラメータ

  • 詳細

    UrlDetails

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getVisits()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

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

パラメータ

  • 詳細

    UrlDetails

  • callback

    関数（省略可）

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

    (results: VisitItem[]) => void

戻り値

  • Promise&lt;VisitItem[]&gt;

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.history.search(
  query: object,
  callback?: function,
)

クエリに一致する各ページの最終訪問時間の履歴を検索します。

パラメータ

  • クエリ

    オブジェクト

    • endTime

      数値（省略可）

      結果をこの日付以前に訪問したデータに限定します。エポックからのミリ秒数で示されます。

    • maxResults

      数値（省略可）

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

    • startTime

      数値（省略可）

      この日付以降に訪問した検索結果のみを表示します。エポックからのミリ秒単位で表示されます。プロパティが指定されていない場合、デフォルトは 24 時間です。

    • テキスト

      文字列

      履歴サービスへの自由テキスト クエリ。すべてのページを取得するには、空のままにします。

  • callback

    関数（省略可）

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

    (results: HistoryItem[]) => void

戻り値

  • Promise&lt;HistoryItem[]&gt;

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

イベント

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

        文字列 [] 省略可