說明
使用 chrome.storage
API 儲存、擷取及追蹤使用者資料的變更。
權限
storage
如要使用 Storage API,請在擴充功能中宣告 "storage"
權限
「資訊清單」。例如:
{
"name": "My extension",
...
"permissions": [
"storage"
],
...
}
概念和用法
Storage API 提供專用的擴充功能,可保留使用者資料和狀態。與網路平台的 Storage API (IndexedDB 和 Storage) 類似,但其設計為符合擴充功能的儲存空間需求。以下是幾項主要功能:
- 所有擴充功能內容,包括擴充功能 Service Worker 和內容指令碼,都可存取 Storage API。
- JSON 可序列化值會儲存為物件屬性。
- Storage API 具備大量讀取和寫入作業非同步。
- 即使使用者清除快取和瀏覽記錄,資料仍會保留。
- 即使使用分割無痕模式,儲存的設定仍會保持有效。
- 包含企業政策的專屬唯讀代管儲存空間區域。
擴充功能可以使用網路儲存空間 API 嗎?
儘管擴充功能在某些情境下 (彈出式視窗和其他 HTML 網頁) 可以使用 Storage
介面 (可從 window.localStorage
存取),但我們不建議這麼做,原因如下:
- 擴充功能 Service Worker 無法使用 Web Storage API。
- 內容指令碼會與主網頁共用儲存空間。
- 使用者清除瀏覽記錄時,使用 Web Storage API 所儲存的資料將會遺失。
如要將網路儲存空間 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
介面是我們建議服務工作處理程序使用的其中一種介面。 storage.sync
- 如果已啟用同步功能,資料就會同步處理至使用者登入的任何 Chrome 瀏覽器。如果停用,運作情形會與
storage.local
相同。當瀏覽器離線時,Chrome 會將資料儲存在本機,並在瀏覽器恢復連線後繼續同步處理。配額上限約為 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
事件<functionvoid>
Chrome 73 以上版本一或多個項目變更時觸發。
onChanged.addListener
函式如下所示:(callback: function) => {...}
-
回呼
函式
callback
參數如下所示:(changes: object) => void
-
變更
物件
-
-
-
關閉
void
Promise從儲存空間中移除所有項目。
clear
函式如下所示:(callback?: function) => {...}
-
回呼
函式 選用
callback
參數如下所示:() => void
-
returns
承諾<void>
Chrome 88 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
-
-
get
void
Promise從儲存空間取得一或多個項目。
get
函式如下所示:(keys?: string | string[] | object, callback?: function) => {...}
-
金鑰
string |string[] |物件 optional
要取得的單一鍵、要取得的鍵清單,或指定預設值的字典 (請參閱物件說明)。空白清單或物件會傳回空的結果物件。傳入
null
,即可取得完整儲存空間內容。 -
回呼
函式 選用
callback
參數如下所示:(items: object) => void
-
items
物件
包含其鍵/值對應項目的物件。
-
-
returns
Promise<object>
Chrome 88 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
-
-
getBytesInUse
void
Promise取得一或多個項目使用的空間量 (以位元組為單位)。
getBytesInUse
函式如下所示:(keys?: string | string[], callback?: function) => {...}
-
金鑰
string |string[] 選填
要取得總用量的單一索引鍵或索引鍵清單。如果清單空白,系統會傳回 0。傳入
null
,即可取得全部儲存空間的總用量。 -
回呼
函式 選用
callback
參數如下所示:(bytesInUse: number) => void
-
bytesInUse
數字
儲存空間使用的空間量,以位元組為單位。
-
-
returns
Promise<number>
Chrome 88 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
-
-
getKeys
void
Promise 待處理從儲存空間取得所有金鑰。
getKeys
函式如下所示:(callback?: function) => {...}
-
回呼
函式 選用
callback
參數如下所示:(keys: string[]) => void
-
金鑰
string[]
含有從儲存空間讀取金鑰的陣列。
-
-
returns
Promise<string[]>
Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
-
-
移除
void
Promise從儲存空間中移除一或多個項目。
remove
函式如下所示:(keys: string | string[], callback?: function) => {...}
-
金鑰
string |字串 []
單一鍵或待移除項目的鍵清單。
-
回呼
函式 選用
callback
參數如下所示:() => void
-
returns
承諾<void>
Chrome 88 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
-
-
set
void
Promise設定多個項目。
set
函式如下所示:(items: object, callback?: function) => {...}
-
items
物件
此為物件,每個鍵/值組合都可用來更新儲存空間。儲存空間內的任何其他鍵/值組合不會受到影響。
數字等原始值會如預期進行序列化。含有
typeof
"object"
和"function"
的值通常會序列化為{}
,但Array
(按預期進行序列化)、Date
和Regex
除外 (使用其String
表示法進行序列化)。 -
回呼
函式 選用
callback
參數如下所示:() => void
-
returns
承諾<void>
Chrome 88 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
-
-
setAccessLevel
void
Promise Chrome 102 以上版本設定儲存區域的所需存取層級。預設為信任的內容。
setAccessLevel
函式如下所示:(accessOptions: object, callback?: function) => {...}
-
accessOptions
物件
-
accessLevel
儲存區域的存取層級。
-
-
回呼
函式 選用
callback
參數如下所示:() => void
-
returns
承諾<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
系統會透過 Chrome 同步功能同步處理 sync
儲存區中的項目。
類型
StorageArea和物體
屬性
-
MAX_ITEMS
512
可儲存在同步處理儲存空間中的項目數量上限。可能導致超過這項限制的更新作業立即失敗,並在使用回呼或 Promise 遭拒時設定
runtime.lastError
。 -
MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE
1000000
已淘汰storage.sync API 不再有持續寫入作業配額。
-
MAX_WRITE_OPERATIONS_PER_HOUR
1800
每小時可執行的
set
、remove
或clear
作業數量上限。這為每 2 秒 1 次,比短期寫入上限的短期上限還低。可能導致超過這項限制的更新作業立即失敗,並在使用回呼或 Promise 遭拒時設定
runtime.lastError
。 -
MAX_WRITE_OPERATIONS_PER_MINUTE
120
每分鐘可執行的
set
、remove
或clear
作業數量上限。每秒 2 次,在短時間內,總處理量高於每小時寫入 2 次。可能導致超過這項限制的更新作業立即失敗,並在使用回呼或 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,
)
一或多個項目變更時觸發。
參數
-
回呼
函式
callback
參數如下所示:(changes: object, areaName: string) => void
-
變更
物件
-
areaName
字串
-