構文
let results = browser.storage.<storageType>.get(
keys // null、文字列、オブジェクト、または文字列の配列
)
<storageType> は、書き込み可能なストレージ種別であり、storage.local、storage.session、storage.sync のいずれかです。
引数
keys-
ストレージから取得するアイテムを特定するキー(
string)、キーの配列、またはデフォルト値を指定するオブジェクトです。空のオブジェクトまたは配列を渡すと、空のオブジェクトが返されます。nullまたはundefinedを渡すと、ストレージ内のすべてのアイテムが返されます。
返値
keys で指定され、ストレージ領域内に存在する各キーと値のペアを含む results オブジェクトで履行される Promise です。keys がオブジェクトの場合、ストレージ内にないキーには keys オブジェクトで指定されたデフォルト値が使用されます。
操作に失敗した場合、Promise はエラーメッセージとともに拒否されます。
managed ストレージが設定されていない場合、undefined が返されます。
警告:
Firefox では、拡張機能の managed ストレージがネイティブマニフェストまたは 3rdparty エンタープライズポリシー(英語)で設定されていない場合、この関数で managed ストレージにアクセスすると例外が発生します(Firefox バグ 1868153を参照)。エラーを捕捉すれば、この問題を回避できます。この問題は、マニフェストキー storage.managed_schema に対応していないことに関連しています(Firefox バグ 1771731を参照)。
例
ストレージに次の 2 つのアイテムが格納されているとします。
// ストレージに "kitten" と "monster" の 2 つのアイテムが格納されています
browser.storage.local.set({
kitten: { name: "Mog", eats: "mice" },
monster: { name: "Kraken", eats: "people" },
});
プロミスの成功時と失敗時のハンドラーを定義します。
function onGot(item) {
console.log(item);
}
function onError(error) {
console.log(`Error: ${error}`);
}
keys 引数を指定せずに、すべてのアイテムを取得します。
let gettingItem = browser.storage.local.get();
gettingItem.then(onGot, onError);
// -> Object { kitten: Object, monster: Object }
空の keys 引数を渡すと、何も取得されません。
// 空の配列を渡すと、何も取得されません
let gettingItem = browser.storage.local.get([]);
gettingItem.then(onGot, onError);
// -> Object { }
オブジェクト名を指定して、一致するアイテムを取得します。
let gettingItem = browser.storage.local.get("kitten");
gettingItem.then(onGot, onError);
// -> Object { kitten: Object }
オブジェクト名の配列を指定して、一致するアイテムをすべて取得します。
let gettingItem = browser.storage.local.get([
"kitten",
"monster",
"grapefruit",
]);
gettingItem.then(onGot, onError);
// -> Object { kitten: Object, monster: Object }
オブジェクト名をキー、デフォルト値を値とするオブジェクトを指定して取得します。
let gettingItem = browser.storage.local.get({
kitten: "no kitten",
monster: "no monster",
grapefruit: {
name: "Grape Fruit",
eats: "Water",
},
});
// -> Object { kitten: Object, monster: Object, grapefruit: Object }
Chrome での例
chrome.storage.local.get("kitten", (items) => {
console.log(items.kitten); // -> {name:"Mog", eats:"mice"}
});
Promise を使用する例です。
let gettingItem = new Promise((resolve) =>
chrome.storage.local.get("kitten", resolve),
);
gettingItem.then(onGot); // -> Object { kitten: Object }
ブラウザーの互換性
メモ:
この API は Chromium の chrome.storage(英語) API に基づいています。このドキュメントは Chromium のコードにある storage.json から派生したものです。