本頁面由 Cloud Translation API 翻譯而成。

chrome.storage

說明

使用 chrome.storage API 儲存、擷取及追蹤使用者資料的變更。

權限

storage

如要使用 Storage API，請在擴充功能的資訊清單中宣告 "storage" 權限。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "storage"
  ],
  ...
}

概念與用途

Storage API 提供擴充功能專屬方式，可保存使用者資料和狀態。這與網頁平台的儲存空間 API (IndexedDB 和 Storage) 類似，但專為滿足擴充功能的儲存空間需求而設計。以下列舉幾項主要功能：

所有擴充功能環境 (包括擴充功能服務工作人員和內容指令碼) 都能存取 Storage API。
可序列化為 JSON 的值會儲存為物件屬性。
Storage API 採用非同步機制，可進行大量讀取和寫入作業。
即使使用者清除快取和瀏覽記錄，資料仍會保留。
即使使用分割無痕模式，儲存的設定也會保留。
包括企業政策專用的唯讀代管儲存空間。

擴充功能可以使用 Web Storage API 嗎？

雖然擴充功能可以在某些情況下 (彈出式視窗和其他 HTML 網頁) 使用 Storage 介面 (可從 window.localStorage 存取)，但我們不建議這麼做，原因如下：

擴充功能服務工作人員無法使用 Web Storage API。
內容指令碼會與代管網頁共用儲存空間。
使用者清除瀏覽記錄時，以 Web Storage API 儲存的資料就會遺失。

如要從服務工作人員將資料從 Web 儲存空間 API 移至擴充功能儲存空間 API，請按照下列步驟操作：

準備螢幕外文件 HTML 網頁和指令碼檔案。指令碼檔案應包含轉換常式和 onMessage 處理常式。
在擴充功能服務工作人員中，檢查資料的 chrome.storage。
如果找不到資料，請呼叫 createDocument()。
傳回的 Promise 解析完成後，請呼叫 sendMessage() 來啟動轉換常式。
在螢幕外文件的 onMessage 處理常式中，呼叫轉換常式。

此外，網路儲存空間 API 在擴充功能中的運作方式也有些細微差異。詳情請參閱「儲存空間和 Cookie」一文。

儲存空間

Storage API 分為下列儲存空間：

storage.local: 資料會儲存在本機，移除擴充功能時會清除資料。儲存空間上限為 10 MB (Chrome 113 和更早版本為 5 MB)，但可以要求 "unlimitedStorage" 權限來提高上限。建議使用 storage.local 儲存大量資料。根據預設，這項屬性會向內容指令碼公開，但您可以呼叫 chrome.storage.local.setAccessLevel() 變更這項行為。
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.sync 會公開給內容指令碼，但您可以呼叫 chrome.storage.sync.setAccessLevel() 變更這項行為。

儲存空間和節流限制

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，服務工作人員則會使用 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 擴充功能有時需要從儲存空間非同步載入資料，才能執行事件處理常式。為此，下列程式碼片段會使用非同步 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);
});

開發人員工具

您可以在開發人員工具中查看及編輯透過 API 儲存的資料。詳情請參閱開發人員工具說明文件中的「查看及編輯擴充功能儲存空間」頁面。

範例

下列範例示範 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

Chrome 102 以上版本

儲存空間的存取層級。

列舉

「TRUSTED_CONTEXTS」
指定源自擴充功能的背景資訊。

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
指定來自擴充功能外部的背景資訊。

StorageArea

屬性

onChanged

Event<functionvoidvoid>

Chrome 73 以上版本

一或多個項目變更時觸發。

onChanged.addListener 函式如下所示：
```
(callback: function) => {...}
```
- callback
  
  函式
  
  callback 參數如下：
```
(changes: object) => void
```
  - 變更
    
    物件
關閉

void

Promise

移除儲存空間中的所有項目。

clear 函式如下所示：
```
(callback?: function) => {...}
```
- callback
  
  函式選用
  
  callback 參數如下：
```
() => void
```
- returns
  Promise<void>
  
  Chrome 95 以上版本
  
  資訊清單 V3 以上版本支援 Promise，但為了確保回溯相容性，系統仍提供回呼。您無法在同一個函式呼叫中使用這兩者。這個 Promise 會以傳遞至回呼的相同型別解析。
get

void

Promise

從儲存空間取得一或多個項目。

get 函式如下所示：
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- 金鑰
  
  字串 | 字串陣列 | 物件選用
  
  要取得的單一鍵、要取得的鍵清單，或指定預設值的字典 (請參閱物件說明)。空白清單或物件會傳回空白結果物件。傳入 null 即可取得儲存空間的所有內容。
- callback
  
  函式選用
  
  callback 參數如下：
```
(items: object) => void
```
  - 項目
    
    物件
    
    物件，內含鍵/值對應中的項目。
- returns
  Promise<object>
  
  Chrome 95 以上版本
  
  資訊清單 V3 以上版本支援 Promise，但為了確保回溯相容性，系統仍提供回呼。您無法在同一個函式呼叫中使用這兩者。這個 Promise 會以傳遞至回呼的相同型別解析。
getBytesInUse

void

Promise

取得一或多個項目使用的空間量 (以位元組為單位)。

getBytesInUse 函式如下所示：
```
(keys?: string | string[], callback?: function) => {...}
```
- 金鑰
  
  string | string[] optional
  
  要取得總用量的單一金鑰或金鑰清單。如果清單為空白，則會傳回 0。傳遞 null 即可取得所有儲存空間的總用量。
- callback
  
  函式選用
  
  callback 參數如下：
```
(bytesInUse: number) => void
```
  - bytesInUse
    
    數字
    
    儲存空間用量，以位元組為單位。
- returns
  Promise<number>
  
  Chrome 95 以上版本
  
  資訊清單 V3 以上版本支援 Promise，但為了確保回溯相容性，系統仍提供回呼。您無法在同一個函式呼叫中使用這兩者。這個 Promise 會以傳遞至回呼的相同型別解析。
getKeys

void

Promise Chrome 130 以上版本

從儲存空間取得所有金鑰。

getKeys 函式如下所示：
```
(callback?: function) => {...}
```
- callback
  
  函式選用
  
  callback 參數如下：
```
(keys: string[]) => void
```
  - 金鑰
    
    string[]
    
    從儲存空間讀取的鍵陣列。
- returns
  Promise<string[]>
  
  資訊清單 V3 以上版本支援 Promise，但為了確保回溯相容性，系統仍提供回呼。您無法在同一個函式呼叫中使用這兩者。這個 Promise 會以傳遞至回呼的相同型別解析。
移除

void

Promise

從儲存空間中移除一或多個項目。

remove 函式如下所示：
```
(keys: string | string[], callback?: function) => {...}
```
- 金鑰
  
  字串 | 字串陣列
  
  要移除的項目鍵 (單一鍵或鍵清單)。
- callback
  
  函式選用
  
  callback 參數如下：
```
() => void
```
- returns
  Promise<void>
  
  Chrome 95 以上版本
  
  資訊清單 V3 以上版本支援 Promise，但為了確保回溯相容性，系統仍提供回呼。您無法在同一個函式呼叫中使用這兩者。這個 Promise 會以傳遞至回呼的相同型別解析。
set

void

Promise

設定多個項目。

set 函式如下所示：
```
(items: object, callback?: function) => {...}
```
- 項目
  
  物件
  
  這個物件會提供每個鍵/值組合，用來更新儲存空間。儲存空間中的其他鍵/值組不會受到影響。
  
  數字等原始值會如預期序列化。含有 typeof "object" 和 "function" 的值通常會序列化為 {}，但 Array (會如預期序列化)、Date 和 Regex 除外 (會使用 String 表示法序列化)。
- callback
  
  函式選用
  
  callback 參數如下：
```
() => void
```
- returns
  Promise<void>
  
  Chrome 95 以上版本
  
  資訊清單 V3 以上版本支援 Promise，但為了確保回溯相容性，系統仍提供回呼。您無法在同一個函式呼叫中使用這兩者。這個 Promise 會以傳遞至回呼的相同型別解析。
setAccessLevel

void

Promise Chrome 102 以上版本

設定儲存空間的所需存取層級。根據預設，session 儲存空間僅限受信任的環境 (擴充功能網頁和 Service Worker) 存取，而 local 和 sync 儲存空間則允許受信任和不受信任的環境存取。

setAccessLevel 函式如下所示：
```
(accessOptions: object, callback?: function) => {...}
```
- accessOptions
  
  物件
  - accessLevel
    
    AccessLevel
    
    儲存空間的存取層級。
- callback
  
  函式選用
  
  callback 參數如下：
```
() => void
```
- returns
  Promise<void>
  
  資訊清單 V3 以上版本支援 Promise，但為了確保回溯相容性，系統仍提供回呼。您無法在同一個函式呼叫中使用這兩者。這個 Promise 會以傳遞至回呼的相同型別解析。

StorageChange

屬性

newValue

不限選填

項目的新值 (如有)。
oldValue

不限選填

項目的舊值 (如有)。

屬性

local

local 儲存空間中的項目僅限於每部機器。

類型

StorageArea 和物件

屬性

QUOTA_BYTES

10485760

可儲存在本機儲存空間的資料量上限 (以位元組為單位)，計算方式為每個值的 JSON 字串化加上每個鍵的長度。如果擴充功能具有 unlimitedStorage 權限，系統會忽略這個值。如果更新會導致超出這項限制，系統會立即失敗，並在使用回呼時設定 runtime.lastError，或在使用 async/await 時設定遭拒的 Promise。

managed

managed 儲存空間中的項目是由網域管理員設定的企業政策所決定，且擴充功能只能讀取這些項目；嘗試修改這個命名空間會導致錯誤。如要瞭解如何設定政策，請參閱儲存空間區域資訊清單。

類型

StorageArea

session

Chrome 102 以上版本 MV3 以上版本

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

1800

每小時可執行的 set、remove 或 clear 作業數量上限。也就是每 2 秒 1 次，比短期內每分鐘寫入次數上限還低。

如果更新會導致超出這項限制，系統會立即失敗，並在使用回呼或 Promise 遭拒時設定 runtime.lastError。
MAX_WRITE_OPERATIONS_PER_MINUTE

120

每分鐘可執行的 set、remove 或 clear 作業數量上限。也就是每秒 2 次，在較短的時間內提供比每小時寫入次數更高的處理量。

如果更新會導致超出這項限制，系統會立即失敗，並在使用回呼或 Promise 遭拒時設定 runtime.lastError。
QUOTA_BYTES

102400

可儲存在同步儲存空間的資料總量上限 (以位元組為單位)，計算方式為每個值的 JSON 字串化加上每個鍵的長度。如果更新會導致超出這項限制，系統會立即失敗，並在使用回呼或 Promise 遭拒時設定 runtime.lastError。
QUOTA_BYTES_PER_ITEM

8192

同步儲存空間中每個項目的最大大小 (以位元組為單位)，計算方式為值的 JSON 字串化加上鍵長度。如果更新包含超過此限制的項目，系統會立即失敗並設定 runtime.lastError (使用回呼時) 或拒絕 Promise。

事件

onChanged

chrome.storage.onChanged.addListener(
  callback: function,
)

一或多個項目變更時觸發。

參數

callback

函式

callback 參數如下：
```
(changes: object, areaName: string) => void
```
- 變更
  
  物件
- areaName
  
  字串