chrome.storage

説明

権限

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

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

例

次のサンプルは、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 is set");
});

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

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

• グローバル検索拡張機能。
• 水漏れアラームの延長。

コンセプトと使用方法

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

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

拡張機能でウェブ ストレージ 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 ハンドラ内で、変換ルーチンを呼び出します。

拡張機能でのウェブ ストレージ API の動作には、いくつかのニュアンスもあります。詳しくは、ストレージと Cookie の記事をご覧ください。

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

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

• データの保存にはパフォーマンス コストがかかり、API にはストレージ割り当てが含まれます。保存するデータを計画して、ストレージ容量を維持します。
• ストレージの完了には時間がかかることがあります。その時間を考慮してコードを構成します。

ストレージ領域の制限と、制限を超えた場合に発生する事象の詳細については、sync、local、session の割り当て情報をご覧ください。

ストレージ領域

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

ローカル

データはローカルに保存され、拡張機能が削除されるとクリアされます。ストレージの上限は 10 MB（Chrome 113 以前では 5 MB）ですが、"unlimitedStorage" 権限をリクエストすることで増やすことができます。大量のデータを保存するには、storage.local を使用することをおすすめします。デフォルトではコンテンツ スクリプトに公開されますが、chrome.storage.local.setAccessLevel() を呼び出すことでこの動作を変更できます。

マネージド

管理対象ストレージは、ポリシーでインストールされた拡張機能に対して読み取り専用です。システム管理者が、デベロッパー定義のスキーマとエンタープライズ ポリシーを使用して管理します。ポリシーはオプションと似ていますが、ユーザーではなくシステム管理者によって構成されます。これにより、組織のすべてのユーザーに対して拡張機能を事前に設定できます。

デフォルトでは、storage.managed はコンテンツ スクリプトに公開されますが、chrome.storage.managed.setAccessLevel() を呼び出すことでこの動作を変更できます。ポリシーについては、管理者向けドキュメントをご覧ください。managed ストレージ領域の詳細については、ストレージ領域のマニフェストをご覧ください。

セッション

セッション ストレージは、拡張機能が読み込まれている間、データをメモリに保持します。拡張機能が無効になった場合、再読み込みされた場合、更新された場合、ブラウザが再起動された場合、ストレージはクリアされます。デフォルトでは、コンテンツ スクリプトに公開されませんが、chrome.storage.session.setAccessLevel() を呼び出すことでこの動作を変更できます。保存容量の上限は 10 MB です（Chrome 111 以前では 1 MB）。

storage.session インターフェースは、サービス ワーカーにおすすめのインターフェースの 1 つです。

同期

ユーザーが同期を有効にすると、ログインしているすべての Chrome ブラウザでデータが同期されます。無効になっている場合は、storage.local のように動作します。ブラウザがオフラインのときは、Chrome はデータをローカルに保存し、オンラインに戻ると同期を再開します。割り当ての上限は、約 100 KB（アイテムあたり 8 KB）です。

storage.sync を使用して、同期されたブラウザ間でユーザー設定を保持することをおすすめします。ユーザーの機密情報を扱う場合は、代わりに storage.session を使用してください。デフォルトでは、storage.sync はコンテンツ スクリプトに公開されますが、chrome.storage.sync.setAccessLevel() を呼び出すことでこの動作を変更できます。

メソッドとイベント

すべてのストレージ領域は StorageArea インターフェースを実装します。

get()

get() メソッドを使用すると、StorageArea から 1 つ以上のキーを読み取ることができます。

getBytesInUse()

getBytesInUse() メソッドを使用すると、StorageArea で使用されている割り当てを確認できます。

getKeys()

getKeys() メソッドを使用すると、StorageArea に保存されているすべてのキーを取得できます。

remove()

remove() メソッドを使用すると、StorageArea からアイテムを削除できます。

set()

set() メソッドを使用すると、StorageArea にアイテムを設定できます。

setAccessLevel()

setAccessLevel() メソッドを使用すると、StorageArea へのアクセスを制御できます。

clear()

clear() メソッドを使用すると、StorageArea からすべてのデータを消去できます。

onChanged

onChanged イベントを使用すると、StorageArea の変更をモニタリングできます。

ユースケース

以降のセクションでは、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);
});

DevTools

API を使用して保存されたデータは、DevTools で表示および編集できます。詳しくは、DevTools ドキュメントの拡張機能のストレージの表示と編集をご覧ください。

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