chrome.storage

説明

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

権限

storage

Storage API を使用するには、拡張機能で "storage" 権限を宣言します。 （manifest を参照）。例:

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

コンセプトと使用方法

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

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

拡張機能はウェブ ストレージ API を使用できますか？

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

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

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

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

また、拡張機能におけるウェブ ストレージ 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 インターフェースは、Service Worker に推奨されるインターフェースの一つです。
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 に保存され、Service Worker は 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);
  }
});

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

Service Worker は常に動作するわけではないため、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"
拡張機能自体からのコンテキストを指定します。

&quot;TRUSTED_AND_UNTRUSTED_CONTEXTS&quot;
拡張機能の外部からのコンテキストを指定します。

StorageArea

プロパティ

  • onChanged

    Event<functionvoidvoid>

    Chrome 73 以降

    1 つ以上のアイテムが変更されたときに呼び出されます。

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

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

    • callback

      関数

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

      (changes: object) => void

      • 変更

        オブジェクト

  • クリア

    void

    <ph type="x-smartling-placeholder"></ph> 約束

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

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

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

    • callback

      関数（省略可）

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

      () => void

    • 戻り値

      約束 <void>

      Chrome 88 以降

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

  • get

    void

    <ph type="x-smartling-placeholder"></ph> 約束

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

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

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

    • 鍵

      string |string[] |オブジェクト（省略可）

      取得する単一のキー、取得するキーのリスト、またはデフォルト値を指定する辞書（オブジェクトの説明を参照）。空のリストまたはオブジェクトは、空の結果オブジェクトを返します。ストレージの全コンテンツを取得するには null を渡します。

    • callback

      関数（省略可）

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

      (items: object) => void

      • アイテム

        オブジェクト

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

    • 戻り値

      Promise&lt;object&gt;

      Chrome 88 以降

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

  • getBytesInUse

    void

    <ph type="x-smartling-placeholder"></ph> 約束

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

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

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

    • 鍵

      string |文字列 [] 省略可

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

    • callback

      関数（省略可）

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

      (bytesInUse: number) => void

      • bytesInUse

        数値

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

    • 戻り値

      Promise&lt;number&gt;

      Chrome 88 以降

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

  • getKey

    void

    <ph type="x-smartling-placeholder"></ph> 約束 保留中

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

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

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

    • callback

      関数（省略可）

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

      (keys: string[]) => void

      • 鍵

        string[]

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

    • 戻り値

      Promise&lt;string[]&gt;

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

  • 削除

    void

    <ph type="x-smartling-placeholder"></ph> 約束

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

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

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

    • 鍵

      string |文字列 []

      削除するアイテムの 1 つのキーまたはキーのリスト。

    • callback

      関数（省略可）

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

      () => void

    • 戻り値

      約束 <void>

      Chrome 88 以降

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

  • set

    void

    <ph type="x-smartling-placeholder"></ph> 約束

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

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

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

    • アイテム

      オブジェクト

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

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

    • callback

      関数（省略可）

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

      () => void

    • 戻り値

      約束 <void>

      Chrome 88 以降

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

  • setAccessLevel

    void

    <ph type="x-smartling-placeholder"></ph> 約束 Chrome 102 以降 をご覧ください。

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

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

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

    • accessOptions

      オブジェクト

      • accessLevel

        AccessLevel

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

    • callback

      関数（省略可）

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

      () => void

    • 戻り値

      約束 <void>

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

StorageChange

プロパティ

  • newValue

    任意

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

  • oldValue

    任意

    商品アイテムの古い値（古い値があった場合）。

プロパティ

local

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

タイプ

StorageArea とオブジェクト

プロパティ

  • QUOTA_BYTES

    10485760

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

managed

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

タイプ

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

    <ph type="x-smartling-placeholder"></ph> 非推奨

    storage.sync API に継続書き込みオペレーションの割り当てがなくなりました。

  • MAX_WRITE_OPERATIONS_PER_HOUR

    1,800

    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

    8192

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

イベント

onChanged

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

1 つ以上のアイテムが変更されたときに呼び出されます。

パラメータ

  • callback

    関数

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

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

    • 変更

      オブジェクト

    • areaName

      文字列