説明
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
インターフェースを使用して保存されたデータは、ユーザーが閲覧履歴を削除すると失われます。
データを Web Storage API から Service Worker から拡張機能ストレージ API に移動するには:
- 変換ルーティンと [
onMessage
][on-message] ハンドラを使用して、画面外ドキュメントを作成します。 - 画面外ドキュメントに変換ルーティンを追加します。
- 拡張機能 Service Worker で
chrome.storage
のデータを確認します。 - データが見つからない場合は、画面外のドキュメントを [create][create-offscreen] して [
sendMessage()
][send-message] を呼び出して、変換ルーティンを開始します。 - 画面外ドキュメントの
onMessage
ハンドラ内で、変換ルーチンを呼び出します。
また、拡張機能での Web Storage API の動作には若干の違いがあります。詳しくは、[ストレージと Cookie][storage-and-cookies] の記事をご覧ください。
収納エリア
Storage API は、次の 4 つのバケット(「ストレージ領域」)に分かれています。
storage.local
- データはローカルに保存され、拡張機能を削除すると消去されます。割り当て上限は約 10 MB ですが、
"unlimitedStorage"
権限をリクエストすることで増やすことができます。大量のデータを保存するために使用を検討してください。
storage.sync
- 同期を有効にすると、ユーザーがログインしているすべての Chrome ブラウザにデータが同期されます。無効にすると、
storage.local
のように動作します。ブラウザがオフラインのときはデータをローカルに保存し、オンラインに戻ると同期が再開されます。割り当て上限は約 100 KB、アイテムあたり 8 KB です。同期しているブラウザ間でユーザー設定を維持するには、この機能の使用を検討してください。
- storage.session
- ブラウザ セッションの間、データをメモリに保持します。デフォルトでは、コンテンツ スクリプトには公開されませんが、
chrome.storage.session.setAccessLevel()
を設定することでこの動作を変更できます。割り当て上限は約 10 MB です。Service Worker の実行全体でグローバル変数を保存するために使用することを検討してください。
- storage.managed
- 管理者は、スキーマとエンタープライズ ポリシーを使用して、マネージド環境でサポートする拡張機能の設定を構成できます。このストレージ領域は読み取り専用です。
マニフェスト
Storage API を使用するには、拡張機能のマニフェストで "storage"
権限を宣言します。次に例を示します。
{
"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 拡張機能では、イベント ハンドラを実行する前にストレージから非同期でデータを読み込むことが必要になる場合があります。そのために、次のスニペットでは非同期の 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);
});
拡張機能の例
Storage API のその他のデモを見るには、以下の例のいずれかをご覧ください。
型
AccessLevel
ストレージ領域のアクセスレベル。
列挙型
"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 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
-
-
get
void
Promiseストレージから 1 つ以上のアイテムを取得します。
get
関数は次のようになります。(keys?: string | string[] | object, callback?: function) => {...}
-
鍵
文字列 | 文字列 [] | オブジェクト(省略可)
取得する単一のキー、取得するキーのリスト、デフォルト値を指定するディクショナリ(オブジェクトの説明を参照)。空のリストまたはオブジェクトは、空の結果オブジェクトを返します。
null
を渡して、ストレージのコンテンツ全体を取得します。 -
callback
関数(省略可)
callback
パラメータは次のようになります。(items: object) => void
-
items
オブジェクト
Key-Value マッピングにアイテムを含むオブジェクト。
-
-
戻り値
Promise<object>
Chrome 88 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
-
-
getBytesInUse
void
Promise1 つ以上のアイテムで使用されているスペースの量(バイト単位)を取得します。
getBytesInUse
関数は次のようになります。(keys?: string | string[], callback?: function) => {...}
-
鍵
string | string[] 省略可
合計使用量を取得する単一のキーまたはキーのリスト。リストが空の場合は 0 が返されます。
null
を渡して、すべての保存容量の合計使用量を取得します。 -
callback
関数(省略可)
callback
パラメータは次のようになります。(bytesInUse: number) => void
-
bytesInUse
数値
ストレージで使用されている容量(バイト単位)。
-
-
戻り値
Promise<数値>
Chrome 88 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
-
-
remove
void
Promiseストレージからアイテムを削除します。
remove
関数は次のようになります。(keys: string | string[], callback?: function) => {...}
-
鍵
文字列 | 文字列 []
削除するアイテムの単一のキーまたはキーのリスト。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
-
戻り値
Promise<void>
Chrome 88 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
-
-
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 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
-
-
setAccessLevel
void
Promise Chrome 102 以降ストレージ領域に必要なアクセスレベルを設定します。デフォルトは、信頼できるコンテキストのみです。
setAccessLevel
関数は次のようになります。(accessOptions: object, callback?: function) => {...}
-
accessOptions
オブジェクト
-
accessLevel
ストレージ領域のアクセスレベル。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
-
戻り値
Promise<void>
Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
-
StorageChange
プロパティ
-
newValue
省略可
新しい値がある場合、商品アイテムの新しい値。
-
oldValue
省略可
商品アイテムの古い値(古い値がある場合)。
プロパティ
local
local
ストレージ領域のアイテムは各マシンにローカルです。
タイプ
StorageArea とオブジェクト
プロパティ
-
QUOTA_BYTES
10485760
ローカル ストレージに保存できるデータの最大量(バイト単位)。各値の JSON 文字列化とすべてのキーの長さの合計で測定されます。拡張機能に
unlimitedStorage
権限がある場合、この値は無視されます。この上限を超える更新は直ちに失敗し、コールバックを使用している場合はruntime.lastError
が設定され、async/await を使用している場合は拒否された Promise が設定されます。
managed
managed
ストレージ領域内のアイテムは、ドメイン管理者が設定したエンタープライズ ポリシーによって設定され、拡張機能の読み取り専用となります。この名前空間を変更しようとすると、エラーが発生します。ポリシーの構成については、ストレージ領域のマニフェストをご覧ください。
タイプ
session
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
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
string
-