chrome.storage

説明

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

権限

storage

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

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

コンセプトと使用方法

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

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

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

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

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

データを Web Storage API から Service Worker から拡張機能ストレージ 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 のように動作します。ブラウザがオフラインのときはデータをローカルに保存し、オンラインに戻ると同期が再開されます。割り当て上限は約 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 拡張機能では、イベント ハンドラを実行する前にストレージから非同期でデータを読み込むことが必要になる場合があります。そのために、次のスニペットでは非同期の action.onClicked イベント ハンドラを使用しています。このハンドラは、storageCache グローバルにデータが入力されるのを待ってからロジックを実行します。

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

  イベント<functionvoidvoid>

  Chrome 73 以降

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

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

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

  • callback

    機能

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

    (changes: object)=>void

    • 変更点

      オブジェクト

• 消去

  void

  Promise

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

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

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

  • callback

    関数（省略可）

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

    ()=>void

  • 戻り値

    Promise<void>

    Chrome 88 以降

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

• get

  void

  Promise

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

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

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

  • 鍵

    string|string[]|object optional

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

  • callback

    関数（省略可）

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

    (items: object)=>void

    • items

      オブジェクト

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

  • 戻り値

    Promise<object>

    Chrome 88 以降

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

• getBytesInUse

  void

  Promise

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

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

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

  • 鍵

    string|string[] optional

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

  • callback

    関数（省略可）

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

    (bytesInUse: number)=>void

    • bytesInUse

      数値

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

  • 戻り値

    Promise<数値>

    Chrome 88 以降

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

• remove

  void

  Promise

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

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

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

  • 鍵

    文字列|文字列 []

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

  • callback

    関数（省略可）

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

    ()=>void

  • 戻り値

    Promise<void>

    Chrome 88 以降

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

• set

  void

  Promise

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

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

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

  • items

    オブジェクト

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

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

  • callback

    関数（省略可）

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

    ()=>void

  • 戻り値

    Promise<void>

    Chrome 88 以降

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

• setAccessLevel

  void

  Promise Chrome 102 以降

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

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

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

  • accessOptions

    オブジェクト

    • accessLevel

      AccessLevel

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

  • callback

    関数（省略可）

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

    ()=>void

  • 戻り値

    Promise<void>

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

StorageChange

プロパティ

• newValue

  省略可

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

• oldValue

  省略可

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

プロパティ

local

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

タイプ

StorageArea オブジェクト(&O)

プロパティ

• QUOTA_BYTES

  10485760
  

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

managed

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

タイプ

StorageArea

session

Chrome 102 以降 MV3 以降

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

タイプ

StorageArea オブジェクト(&O)

プロパティ

• QUOTA_BYTES

  10485760
  

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

sync

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

タイプ

StorageArea オブジェクト(&O)

プロパティ

• MAX_ITEMS

  512
  

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

• MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE

  1000000
  

  非推奨

  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

    文字列