説明
chrome.storage
API を使用して、ユーザーデータの変更を保存、取得、追跡します。
権限
storage
概要
Storage API は、ユーザーデータと状態を保持するための拡張機能固有の方法を提供します。これはウェブ プラットフォームのストレージ API(IndexedDB、Storage)に似ていますが、拡張機能のストレージのニーズを満たすように設計されています。主な機能は次のとおりです。
- 拡張機能のサービス ワーカーやコンテンツ スクリプトなど、すべての拡張機能コンテキストは Storage API にアクセスできます。
- JSON シリアル化可能な値は、オブジェクト プロパティとして保存されます。
- Storage API は、一括読み取りオペレーションと一括書き込みオペレーションで非同期です。
- ユーザーがキャッシュと閲覧履歴を削除しても、データは保持されます。
- 保存された設定は、分割シークレット モードを使用している場合でも保持されます。
- エンタープライズ ポリシー専用の読み取り専用マネージド ストレージ領域が含まれます。
拡張機能は、一部のコンテキスト(ポップアップやその他の HTML ページ)で [Storage
][mdn-storage] インターフェース(window.localStorage
からアクセス可能)を使用できますが、次の理由から使用はおすすめしません。
- 拡張機能のサービス ワーカーが
Storage
にアクセスできない。 - コンテンツ スクリプトはホストページとストレージを共有します。
Storage
インターフェースを使用して保存されたデータは、ユーザーが閲覧履歴を消去すると失われます。
Service Worker からウェブ ストレージ API から拡張機能ストレージ API にデータを移動するには:
- コンバージョン ルーティンと [
onMessage
][on-message] ハンドラを含む画面外ドキュメントを作成します。 - オフスクリーン ドキュメントにコンバージョン ルーティンを追加する。
- 拡張機能サービス ワーカーで、データの
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
のように動作します。Chrome は、ブラウザがオフラインのときにデータをローカルに保存し、オンラインに戻ったときに同期を再開します。割り当ての上限は約 100 KB(商品アイテムあたり 8 KB)です。同期されたブラウザ間でユーザー設定を保持するために使用することを検討してください。
- storage.session
- ブラウザ セッションの期間中、データをメモリに保持します。デフォルトでは、コンテンツ スクリプトには公開されませんが、
chrome.storage.session.setAccessLevel()
を設定することでこの動作を変更できます。割り当ての上限は約 10 MB です。サービス ワーカーの実行全体でグローバル変数を格納するために使用することを検討してください。
- 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
に保存します。サービス ワーカーは 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);
});
拡張機能の例
Storage API の他のデモについては、次のいずれかの例をご覧ください。
型
AccessLevel
ストレージ領域のアクセスレベル。
列挙型
"TRUSTED_CONTEXTS"
拡張機能自体から発生したコンテキストを指定します。
"TRUSTED_AND_UNTRUSTED_CONTEXTS"
拡張機能の外部から発生したコンテキストを指定します。
StorageArea
プロパティ
-
onChanged
Event<functionvoidvoid>
Chrome 73 以降1 つ以上のアイテムが変更されたときに発生します。
onChanged.addListener
関数は次のようになります。(callback: function) => {...}
-
callback
関数
callback
パラメータは次のようになります。(changes: object) => void
-
変更
オブジェクト
-
-
-
クリア
void
Promiseストレージからすべてのアイテムを削除します。
clear
関数は次のようになります。(callback?: function) => {...}
-
callback
function 省略可
callback
パラメータは次のようになります。() => void
-
戻り値
Promise<void>
Chrome 88 以降Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。
-
-
get
void
Promiseストレージから 1 つ以上のアイテムを取得します。
get
関数は次のようになります。(keys?: string | string[] | object, callback?: function) => {...}
-
鍵
string | string[] | object 省略可
取得する 1 つのキー、取得するキーのリスト、またはデフォルト値を指定する辞書(オブジェクトの説明を参照)。空のリストまたはオブジェクトを指定すると、空の結果オブジェクトが返されます。
null
を渡して、ストレージの内容全体を取得します。 -
callback
function 省略可
callback
パラメータは次のようになります。(items: object) => void
-
アイテム
オブジェクト
Key-Value マッピングにアイテムを含むオブジェクト。
-
-
戻り値
Promise<object>
Chrome 88 以降Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。
-
-
getBytesInUse
void
Promise1 つ以上のアイテムによって使用されているスペースの量(バイト単位)を取得します。
getBytesInUse
関数は次のようになります。(keys?: string | string[], callback?: function) => {...}
-
鍵
文字列 | 文字列の配列(省略可)
合計使用量を取得する 1 つのキーまたはキーのリスト。空のリストの場合は 0 が返されます。
null
を渡して、すべてのストレージの合計使用量を取得します。 -
callback
function 省略可
callback
パラメータは次のようになります。(bytesInUse: number) => void
-
bytesInUse
数値
ストレージで使用されている容量(バイト単位)。
-
-
戻り値
Promise<number>
Chrome 88 以降Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。
-
-
getKeys
void
Promise Chrome 130 以降ストレージからすべてのキーを取得します。
getKeys
関数は次のようになります。(callback?: function) => {...}
-
callback
function 省略可
callback
パラメータは次のようになります。(keys: string[]) => void
-
鍵
string[]
ストレージから読み取ったキーを含む配列。
-
-
戻り値
Promise<string[]>
Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。
-
-
削除
void
Promiseストレージから 1 つ以上のアイテムを削除します。
remove
関数は次のようになります。(keys: string | string[], callback?: function) => {...}
-
鍵
string | string[]
削除する項目のキー(単一またはリスト)。
-
callback
function 省略可
callback
パラメータは次のようになります。() => void
-
戻り値
Promise<void>
Chrome 88 以降Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。
-
-
set
void
Promise複数のアイテムを設定します。
set
関数は次のようになります。(items: object, callback?: function) => {...}
-
アイテム
オブジェクト
ストレージの更新に使用する各 Key-Value ペアを指定するオブジェクト。ストレージ内の他の Key-Value ペアには影響しません。
数値などのプリミティブ値は、想定どおりにシリアル化されます。
typeof
、"object"
、"function"
を含む値は通常、{}
にシリアル化されます。ただし、Array
(想定どおりにシリアル化)、Date
、Regex
(String
表現を使用してシリアル化)は例外です。 -
callback
function 省略可
callback
パラメータは次のようになります。() => void
-
戻り値
Promise<void>
Chrome 88 以降Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。
-
-
setAccessLevel
void
Promise Chrome 102 以降ストレージ領域に必要なアクセスレベルを設定します。デフォルトでは、信頼できるコンテキストのみが使用されます。
setAccessLevel
関数は次のようになります。(accessOptions: object, callback?: function) => {...}
-
accessOptions
オブジェクト
-
accessLevel
ストレージ領域のアクセスレベル。
-
-
callback
function 省略可
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
ストレージ領域内のアイテムは、ドメイン管理者が構成したエンタープライズ ポリシーによって設定され、拡張機能に対して読み取り専用です。この Namespace を変更しようとすると、エラーが発生します。ポリシーの構成については、ストレージ領域のマニフェストをご覧ください。
タイプ
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
1800
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
8,192
同期ストレージ内の各アイテムの最大サイズ(バイト単位)。値の JSON 文字列化とキーの長さで測定されます。この上限を超えるアイテムを含む更新はすぐに失敗し、コールバックを使用している場合や Promise が拒否された場合は
runtime.lastError
が設定されます。
イベント
onChanged
chrome.storage.onChanged.addListener(
callback: function,
)
1 つ以上のアイテムが変更されたときに発生します。
パラメータ
-
callback
関数
callback
パラメータは次のようになります。(changes: object, areaName: string) => void
-
変更
オブジェクト
-
areaName
文字列
-