説明
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 に移動するには:
- 画面外ドキュメントの HTML ページとスクリプト ファイルを準備します。スクリプト ファイルには、変換ルーチンと
onMessage
ハンドラを含める必要があります。 - 拡張機能 Service Worker で
chrome.storage
のデータを確認します。 - データが見つからない場合は、
createDocument()
を呼び出します。 - 返された Promise が解決されたら、
sendMessage()
を呼び出して変換ルーティンを開始します。 - 画面外ドキュメントの
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
ストレージ領域のアクセスレベル。
列挙型
"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
Promise1 つ以上のアイテムで使用されているスペースの量(バイト単位)を取得します。
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
ストレージ領域のアクセスレベル。
-
-
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
ストレージ領域内のアイテムは、ドメイン管理者が設定したエンタープライズ ポリシーによって設定され、拡張機能の読み取り専用となります。この名前空間を変更しようとすると、エラーが発生します。ポリシーの構成については、ストレージ領域のマニフェストをご覧ください。
タイプ
session
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
文字列
-