chrome.storage

説明

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

権限

storage

概要

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

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

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

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

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

  1. 変換ルーティンと [onMessage][on-message] ハンドラを使用して、画面外のドキュメントを作成します。
  2. 画面外のドキュメントに変換ルーチンを追加します。
  3. 拡張機能の Service Worker で、chrome.storage でデータを確認します。
  4. データが見つからない場合は、画面外ドキュメントを [作成][create-offscreen] し、[sendMessage()][send-message] を呼び出して、変換ルーティンを開始します。
  5. オフスクリーン ドキュメントの onMessage ハンドラ内で、変換ルーチンを呼び出します。

また、拡張機能におけるウェブ ストレージ API の動作には細かな点があります。詳しくは、 [ストレージと Cookie][storage-and-cookies] の記事をご覧ください。

ストレージ領域

Storage API は、次の 4 つのバケット（ストレージ領域）に分かれています。

storage.local
データはローカルに保存され、拡張機能が削除されるとクリアされます。割り当ての上限は約 10 MB ですが、"unlimitedStorage" 権限をリクエストして増やすことができます。これを使用して大量のデータを保存することを検討してください。
で確認できます。
storage.sync
同期が有効になっている場合、データはユーザーがログインしているすべての Chrome ブラウザと同期されます。無効にすると、storage.local のように動作します。Chrome では、ブラウザがオフラインのときはデータがローカルに保存され、オンラインに復帰したときに同期が再開されます。割り当て上限は約 100 KB、アイテムごとに 8 KB です。同期されたブラウザでユーザー設定を保持する場合は、このオプションの使用を検討してください。
で確認できます。
storage.session
ブラウザ セッションの間、データをメモリに保持します。デフォルトでは、コンテンツ スクリプトには公開されませんが、この動作は chrome.storage.session.setAccessLevel() を設定することで変更できます。割り当て上限は約 10 MB です。Service Worker の実行全体でグローバル変数を保存するために、これを使用することを検討してください。
で確認できます。
storage.managed
管理者は、スキーマとエンタープライズ ポリシーを使用して、サポートする拡張機能の設定をマネージド環境で構成できます。このストレージ領域は読み取り専用です。

マニフェスト

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

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

用途

次のサンプルは、local、sync、 session 個のストレージ エリア:

storage.local

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

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

storage.sync

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

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

storage.session

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

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

managed ストレージ領域の詳細については、ストレージ領域のマニフェストをご覧ください。

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

Storage 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);
});

拡張機能の例

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 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

  • 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 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

  • 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 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

  • getKey

    void

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

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

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

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

    • callback

      関数（省略可）

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

      (keys: string[]) => void

      • 鍵

        string[]

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

    • 戻り値

      Promise&lt;string[]&gt;

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

  • 削除

    void

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

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

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

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

    • 鍵

      string |文字列 []

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

    • callback

      関数（省略可）

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

      () => void

    • 戻り値

      約束 <void>

      Chrome 88 以降

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

  • 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 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

  • 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 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

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

      文字列