chrome.storage

説明

chrome.storage API を使用して、ユーザーデータの変更を保存、取得、追跡します。

権限

storage

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

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

コンセプトと使用方法

Storage API は、ユーザーデータと状態を保持するための拡張機能固有の方法を提供します。これはウェブ プラットフォームのストレージ API（IndexedDB、Storage）に似ていますが、拡張機能のストレージのニーズを満たすように設計されています。主な機能は次のとおりです。

  • 拡張機能のサービス ワーカーやコンテンツ スクリプトなど、すべての拡張機能コンテキストは Storage API にアクセスできます。
  • JSON シリアル化可能な値は、オブジェクト プロパティとして保存されます。
  • Storage API は、一括読み取りオペレーションと一括書き込みオペレーションで非同期です。
  • ユーザーがキャッシュと閲覧履歴を削除しても、データは保持されます。
  • 保存された設定は、分割シークレット モードを使用している場合でも保持されます。
  • エンタープライズ ポリシー専用の読み取り専用マネージド ストレージ領域が含まれます。

拡張機能は Web Storage API を使用できますか？

拡張機能は、一部のコンテキスト（ポップアップやその他の HTML ページ）で Storage インターフェース（window.localStorage からアクセス可能）を使用できますが、次の理由から使用はおすすめしません。

  • 拡張機能 Service Worker は Web Storage API を使用できません。
  • コンテンツ スクリプトはホストページとストレージを共有します。
  • Web Storage API を使用して保存されたデータは、ユーザーが閲覧履歴を消去すると失われます。

Service Worker からウェブ ストレージ API から拡張機能ストレージ API にデータを移動するには:

  1. 画面外ドキュメントの HTML ページとスクリプト ファイルを準備します。スクリプト ファイルには、変換ルーティンと onMessage ハンドラが含まれている必要があります。
  2. 拡張機能サービス ワーカーで、データの chrome.storage を確認します。
  3. データが見つからない場合は、createDocument() を呼び出します。
  4. 返された Promise が解決したら、sendMessage() を呼び出して変換ルーティンを開始します。
  5. 画面外ドキュメントの onMessage ハンドラ内で、コンバージョン ルーティンを呼び出します。

また、拡張機能での Web Storage API の動作には、いくつかの違いがあります。詳しくは、ストレージと Cookie の記事をご覧ください。

ストレージ領域

Storage API は、次のストレージ領域に分かれています。

storage.local
データはローカルに保存され、拡張機能が削除されると消去されます。ストレージの上限は 10 MB ですが（Chrome 113 以前は 5 MB）、"unlimitedStorage" 権限をリクエストすることで増やすことができます。大量のデータを保存する場合は、storage.local を使用することをおすすめします。
storage.managed
管理対象ストレージは、ポリシーによってインストールされた拡張機能用の読み取り専用ストレージであり、デベロッパー定義のスキーマとエンタープライズ ポリシーを使用してシステム管理者によって管理されます。ポリシーはオプションに似ていますが、ユーザーではなくシステム管理者が設定するため、組織内のすべてのユーザーに対して拡張機能を事前構成できます。ポリシーの詳細については、管理者向けのドキュメントをご覧ください。managed ストレージ領域の詳細については、ストレージ領域のマニフェストをご覧ください。
storage.session
ブラウザ セッションの期間中、データをメモリに保持します。デフォルトでは、コンテンツ スクリプトには公開されませんが、chrome.storage.session.setAccessLevel() を設定することでこの動作を変更できます。保存容量の上限は 10 MB です（Chrome 111 以前は 1 MB）。storage.session インターフェースは、サービス ワーカーに推奨されるインターフェースの 1 つです。
storage.sync
同期が有効になっている場合、データはユーザーがログインしているすべての Chrome ブラウザに同期されます。無効にすると、storage.local のように動作します。Chrome は、ブラウザがオフラインのときにデータをローカルに保存し、オンラインに戻ったときに同期を再開します。割り当ての上限は約 100 KB（商品アイテムあたり 8 KB）です。同期されたブラウザ間でユーザー設定を保持するには、storage.sync を使用することをおすすめします。機密性の高いユーザーデータを扱う場合は、代わりに storage.session を使用してください。

ストレージとスロットリングの上限

Storage API には次の使用制限があります。

  • データの保存には多くの場合パフォーマンス上のコストがかかり、API にはストレージ割り当てが含まれています。データの保存機能を失わないように、保存するデータに注意することをおすすめします。
  • ストレージの完了に時間がかかることがあります。コードを構造化して、その時間を考慮してください。

ストレージ領域の上限と上限を超えた場合の影響については、sync、local、session の割り当て情報を参照してください。

ユースケース

以降のセクションでは、Storage API の一般的なユースケースについて説明します。

ストレージの更新に対する同期レスポンス

ストレージに加えられた変更を追跡するには、onChanged イベントにリスナーを追加します。ストレージで何か変更があると、そのイベントが発生します。サンプルコードは、次の変更をリッスンします。

background.js:

chrome.storage.onChanged.addListener((changes, namespace) => {
  for (let [key, { oldValue, newValue }] of Object.entries(changes)) {
    console.log(
      `Storage key "${key}" in namespace "${namespace}" changed.`,
      `Old value was "${oldValue}", new value is "${newValue}".`
    );
  }
});

このアイデアをさらに一歩進めることができます。この例では、ユーザーが「デバッグモード」を切り替えることができるオプション ページがあります（実装はここには示していません）。オプション ページは、新しい設定をすぐに storage.sync に保存します。サービス ワーカーは storage.onChanged を使用して、できるだけ早く設定を適用します。

options.html:

<!-- type="module" allows you to use top level await -->
<script defer src="options.js" type="module"></script>
<form id="optionsForm">
  <label for="debug">
    <input type="checkbox" name="debug" id="debug">
    Enable debug mode
  </label>
</form>

options.js:

// In-page cache of the user's options
const options = {};
const optionsForm = document.getElementById("optionsForm");

// Immediately persist options changes
optionsForm.debug.addEventListener("change", (event) => {
  options.debug = event.target.checked;
  chrome.storage.sync.set({ options });
});

// Initialize the form with the user's option settings
const data = await chrome.storage.sync.get("options");
Object.assign(options, data.options);
optionsForm.debug.checked = Boolean(options.debug);

background.js:

function setDebugMode() { /* ... */ }

// Watch for changes to the user's options & apply them
chrome.storage.onChanged.addListener((changes, area) => {
  if (area === 'sync' && changes.options?.newValue) {
    const debugMode = Boolean(changes.options.newValue.debug);
    console.log('enable debug mode?', debugMode);
    setDebugMode(debugMode);
  }
});

ストレージからの非同期プリロード

サービス ワーカーは常に実行されるわけではないため、Manifest V3 拡張機能では、イベント ハンドラを実行する前にストレージからデータを非同期で読み込む必要がある場合があります。そのため、次のスニペットでは、storageCache グローバルにデータが入力されるまで待機してからロジックを実行する非同期 action.onClicked イベント ハンドラを使用しています。

background.js:

// Where we will expose all the data we retrieve from storage.sync.
const storageCache = { count: 0 };
// Asynchronously retrieve data from storage.sync, then cache it.
const initStorageCache = chrome.storage.sync.get().then((items) => {
  // Copy the data retrieved from storage into storageCache.
  Object.assign(storageCache, items);
});

chrome.action.onClicked.addListener(async (tab) => {
  try {
    await initStorageCache;
  } catch (e) {
    // Handle error that occurred during storage initialization.
  }

  // Normal action handler logic.
  storageCache.count++;
  storageCache.lastTabId = tab.id;
  chrome.storage.sync.set(storageCache);
});

例

次のサンプルは、local、sync、session のストレージ領域を示しています。

ローカル

chrome.storage.local.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.local.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

同期

chrome.storage.sync.set({ key: value }).then(() => {
  console.log("Value is set");
});

chrome.storage.sync.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

セッション

chrome.storage.session.set({ key: value }).then(() => {
  console.log("Value was set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

Storage API の他のデモについては、次のいずれかのサンプルをご覧ください。

型

AccessLevel

Chrome 102 以降

ストレージ領域のアクセスレベル。

列挙型

"TRUSTED_CONTEXTS"
拡張機能自体から発生したコンテキストを指定します。

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
拡張機能の外部から発生したコンテキストを指定します。

StorageArea

プロパティ

  • onChanged

    Event<functionvoidvoid>

    Chrome 73 以降

    1 つ以上のアイテムが変更されたときに発生します。

    onChanged.addListener 関数は次のようになります。 

    (callback: function) => {...}

    • callback

      関数

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

      (changes: object) => void

      • 変更

        オブジェクト

  • クリア

    void

    Promise

    ストレージからすべてのアイテムを削除します。

    clear 関数は次のようになります。 

    (callback?: function) => {...}

    • callback

      function 省略可

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

      () => void

    • 戻り値

      Promise<void>

      Chrome 88 以降

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

  • get

    void

    Promise

    ストレージから 1 つ以上のアイテムを取得します。

    get 関数は次のようになります。 

    (keys?: string | string[] | object, callback?: function) => {...}

    • 鍵

      string | string[] | object 省略可

      取得する 1 つのキー、取得するキーのリスト、またはデフォルト値を指定する辞書（オブジェクトの説明を参照）。空のリストまたはオブジェクトを指定すると、空の結果オブジェクトが返されます。null を渡して、ストレージの内容全体を取得します。

    • callback

      function 省略可

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

      (items: object) => void

      • アイテム

        オブジェクト

        Key-Value マッピングにアイテムを含むオブジェクト。

    • 戻り値

      Promise<object>

      Chrome 88 以降

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

  • getBytesInUse

    void

    Promise

    1 つ以上のアイテムによって使用されているスペースの量（バイト単位）を取得します。

    getBytesInUse 関数は次のようになります。 

    (keys?: string | string[], callback?: function) => {...}

    • 鍵

      文字列 | 文字列の配列（省略可）

      合計使用量を取得する単一のキーまたはキーのリスト。空のリストの場合は 0 が返されます。null を渡して、すべてのストレージの合計使用量を取得します。

    • callback

      function 省略可

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

      (bytesInUse: number) => void

      • bytesInUse

        数値

        ストレージで使用されている容量（バイト単位）。

    • 戻り値

      Promise<number>

      Chrome 88 以降

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

  • getKeys

    void

    Promise Chrome 130 以降

    ストレージからすべてのキーを取得します。

    getKeys 関数は次のようになります。 

    (callback?: function) => {...}

    • callback

      function 省略可

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

      (keys: string[]) => void

      • 鍵

        string[]

        ストレージから読み取ったキーを含む配列。

    • 戻り値

      Promise<string[]>

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

  • 削除

    void

    Promise

    ストレージから 1 つ以上のアイテムを削除します。

    remove 関数は次のようになります。 

    (keys: string | string[], callback?: function) => {...}

    • 鍵

      string | string[]

      削除する項目のキー（単一またはリスト）。

    • callback

      function 省略可

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

      () => void

    • 戻り値

      Promise<void>

      Chrome 88 以降

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

  • set

    void

    Promise

    複数のアイテムを設定します。

    set 関数は次のようになります。 

    (items: object, callback?: function) => {...}

    • アイテム

      オブジェクト

      ストレージの更新に使用する各 Key-Value ペアを指定するオブジェクト。ストレージ内の他の Key-Value ペアには影響しません。

      数値などのプリミティブ値は、想定どおりにシリアル化されます。typeof、"object"、"function" を含む値は通常、{} にシリアル化されます。ただし、Array（想定どおりにシリアル化）、Date、Regex（String 表現を使用してシリアル化）は例外です。

    • callback

      function 省略可

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

      () => void

    • 戻り値

      Promise<void>

      Chrome 88 以降

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

  • setAccessLevel

    void

    Promise Chrome 102 以降

    ストレージ領域に必要なアクセスレベルを設定します。デフォルトでは、信頼できるコンテキストのみが対象になります。

    setAccessLevel 関数は次のようになります。 

    (accessOptions: object, callback?: function) => {...}

    • accessOptions

      オブジェクト

      • accessLevel

        AccessLevel

        ストレージ領域のアクセスレベル。

    • callback

      function 省略可

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

      () => void

    • 戻り値

      Promise<void>

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

StorageChange

プロパティ

  • newValue

    任意（省略可）

    アイテムの新しい値（新しい値がある場合）。

  • oldValue

    任意（省略可）

    アイテムの古い値（古い値が存在する場合）。

プロパティ

local

local ストレージ領域内のアイテムは、各マシンにローカルです。

タイプ

StorageArea とオブジェクト

プロパティ

  • QUOTA_BYTES

    10485760

    ローカル ストレージに保存できるデータの最大量（バイト単位）。すべての値の JSON 文字列化とすべてのキーの長さの合計で測定されます。拡張機能に unlimitedStorage 権限が付与されている場合、この値は無視されます。この上限を超える更新は直ちに失敗し、コールバックを使用している場合は runtime.lastError が設定され、async/await を使用している場合は拒否された Promise が設定されます。

managed

managed ストレージ領域内のアイテムは、ドメイン管理者が構成したエンタープライズ ポリシーによって設定され、拡張機能に対して読み取り専用です。この Namespace を変更しようとすると、エラーが発生します。ポリシーの構成については、ストレージ領域のマニフェストをご覧ください。

タイプ

StorageArea

session

Chrome 102 以降 MV3 以降

session ストレージ領域内のアイテムはメモリに保存され、ディスクには保持されません。

タイプ

StorageArea とオブジェクト

プロパティ

  • QUOTA_BYTES

    10485760

    メモリに保存できるデータの最大量（バイト単位）。すべての値とキーの動的に割り当てられたメモリ使用量を推定することで測定されます。この上限を超える更新は直ちに失敗し、コールバックを使用している場合や Promise が拒否された場合は runtime.lastError が設定されます。

sync

sync ストレージ領域内のアイテムは、Chrome 同期を使用して同期されます。

タイプ

StorageArea とオブジェクト

プロパティ

  • MAX_ITEMS

    512

    同期ストレージに保存できるアイテムの最大数。この上限を超える更新は直ちに失敗し、コールバックを使用している場合や Promise が拒否された場合は runtime.lastError が設定されます。

  • MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

    1000000

    非推奨

    storage.sync API の持続的な書き込みオペレーションの割り当てが削除されました。

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1800

    1 時間あたりに実行できる set、remove、clear オペレーションの最大数。これは 2 秒ごとに 1 回で、1 分あたりの書き込み数の短期的な上限よりも低い上限です。

    この上限を超える更新は直ちに失敗し、コールバックを使用している場合や Promise が拒否された場合は runtime.lastError が設定されます。

  • MAX_WRITE_OPERATIONS_PER_MINUTE

    120

    1 分あたり実行できる set、remove、clear オペレーションの最大数。これは 1 秒あたり 2 回で、短い時間で書き込み 1 時間あたりよりも高いスループットを提供します。

    この上限を超える更新は直ちに失敗し、コールバックを使用している場合や Promise が拒否された場合は runtime.lastError が設定されます。

  • QUOTA_BYTES

    102400

    同期ストレージに保存できるデータの最大合計量（バイト単位）。すべての値の JSON 文字列化とすべてのキーの長さの合計で測定されます。この上限を超える更新は直ちに失敗し、コールバックを使用している場合や Promise が拒否された場合は runtime.lastError が設定されます。

  • QUOTA_BYTES_PER_ITEM

    8,192

    同期ストレージ内の各アイテムの最大サイズ（バイト単位）。値の JSON 文字列化とキーの長さで測定されます。この上限を超えるアイテムを含む更新はすぐに失敗し、コールバックを使用している場合や Promise が拒否された場合は runtime.lastError が設定されます。

イベント

onChanged

chrome.storage.onChanged.addListener(
  callback: function,
)

1 つ以上のアイテムが変更されたときに発生します。

パラメータ

  • callback

    関数

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

    (changes: object, areaName: string) => void

    • 変更

      オブジェクト

    • areaName

      文字列