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

chrome.storage

說明

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

權限

storage

總覽

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

所有擴充功能內容，包括擴充功能服務 worker 和內容指令碼，皆可存取 Storage API。
JSON 可序列化的值會儲存為物件屬性。
Storage API 會以非同步方式執行大量讀取和寫入作業。
即使使用者清除快取和瀏覽記錄，資料仍會保留。
即使使用分割無痕模式，儲存的設定仍會保留。
包含專屬的唯讀管理儲存區，供企業政策使用。

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

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

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

使用轉換常式和 [onMessage][on-message] 處理常式建立螢幕外文件。
在螢幕外文件中新增轉換例行程序。
在擴充功能服務 worker 中，檢查 chrome.storage 是否有您的資料。
如果找不到資料，請 [create][create-offscreen] 建立離線文件，然後呼叫 [sendMessage()][send-message] 來啟動轉換例行作業。
在螢幕外文件的 onMessage 處理常式中，呼叫轉換例行程序。

網路儲存空間 API 在擴充功能中的運作方式也有所不同。詳情請參閱「[儲存空間和 Cookie][storage-and-cookies]」一文。

儲存空間

Storage API 可分為下列四個區塊 (「儲存空間」)：

storage.local: 資料會儲存在本機，並在移除擴充功能時清除。配額限制約為 10 MB，但您可以要求 "unlimitedStorage" 權限來增加配額。建議您使用這項功能儲存大量資料。

storage.sync: 如果啟用同步功能，系統會將資料同步至使用者登入的任何 Chrome 瀏覽器。如果停用，則會像 storage.local 一樣運作。Chrome 會在瀏覽器離線時將資料儲存在本機，並在重新上線時恢復同步處理。配額限制約為 100 KB，每個項目約為 8 KB。建議您使用這項功能，在同步處理的瀏覽器之間保留使用者設定。

警告：本機和同步儲存區不應儲存機密使用者資料，因為這些區域並未加密。處理機密資料時，建議您使用 session 儲存區，在瀏覽器關閉前，將值保留在記憶體中。

storage.session: 在瀏覽器工作階段期間，將資料保留在記憶體中。根據預設，這項資訊不會公開給內容指令碼，但您可以設定 chrome.storage.session.setAccessLevel() 來變更這項行為。配額限制約為 10 MB。建議您使用此方法，在服務工作程執行期間儲存全域變數。

storage.managed: 管理員可以使用結構定義和企業政策，在受管理的環境中設定支援的擴充功能設定。這個儲存區是唯讀的。

資訊清單

如要使用儲存空間 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 擴充功能有時需要在執行事件處理常式之前，以非同步方式從儲存空間載入資料。為此，下列程式碼片段會使用非同步 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);
});

擴充功能範例

如要查看 Storage API 的其他示範，請參閱下列任一範例：

類型

AccessLevel

Chrome 102 以上版本

儲存區的存取層級。

列舉

"TRUSTED_CONTEXTS"
指定來自擴充功能本身的背景資訊。

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

StorageArea

屬性

onChanged

Event<functionvoidvoid>

Chrome 73 以上版本

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

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

void

Promise

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

clear 函式如下所示：
```
(callback?: function) => {...}
```
- 回呼
  
  函式選填
  
  callback 參數如下所示：
```
() => void
```
- returns
  Promise<void>
  
  Chrome 88 以上版本
  
  承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
get

void

Promise

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

get 函式如下所示：
```
(keys?: string | string[] | object, callback?: function) => {...}
```
- 金鑰
  
  string | string[] | object 選用
  
  要取得的單一鍵、要取得的鍵清單，或指定預設值的字典 (請參閱物件的說明)。空白清單或物件會傳回空白結果物件。傳入 null 即可取得儲存空間的完整內容。
- 回呼
  
  函式選填
  
  callback 參數如下所示：
```
(items: object) => void
```
  - 項目
    
    物件
    
    物件含有鍵/值對應項目。
- returns
  Promise<object>
  
  Chrome 88 以上版本
  
  承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
getBytesInUse

void

Promise

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

getBytesInUse 函式如下所示：
```
(keys?: string | string[], callback?: function) => {...}
```
- 金鑰
  
  string | string[] 選填
  
  單一鍵或鍵清單，用於取得使用次數總和。空白清單會傳回 0。傳入 null，即可取得所有儲存空間的總用量。
- 回呼
  
  函式選填
  
  callback 參數如下所示：
```
(bytesInUse: number) => void
```
  - bytesInUse
    
    數字
    
    儲存空間中已使用的空間量 (以位元組為單位)。
- returns
  Promise<number>
  
  Chrome 88 以上版本
  
  承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
getKeys

void

Promise Chrome 130 以上版本

從儲存空間取得所有鍵。

getKeys 函式如下所示：
```
(callback?: function) => {...}
```
- 回呼
  
  函式選填
  
  callback 參數如下所示：
```
(keys: string[]) => void
```
  - 金鑰
    
    string[]
    
    從儲存空間讀取的鍵陣列。
- returns
  Promise<string[]>
  
  承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
移除

void

Promise

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

remove 函式如下所示：
```
(keys: string | string[], callback?: function) => {...}
```
- 金鑰
  
  string | string[]
  
  要移除的項目的單一鍵或鍵清單。
- 回呼
  
  函式選填
  
  callback 參數如下所示：
```
() => void
```
- returns
  Promise<void>
  
  Chrome 88 以上版本
  
  承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
set

void

Promise

設定多個項目。

set 函式如下所示：
```
(items: object, callback?: function) => {...}
```
- 項目
  
  物件
  
  這個物件會提供每個鍵/值組合，用於更新儲存空間。儲存空間中的其他鍵/值組合不會受到影響。
  
  數字等原始值會按照預期進行序列化。含有 typeof "object" 和 "function" 的值通常會序列化為 {}，但 Array (會如預期序列化)、Date 和 Regex (會使用其 String 表示法序列化) 除外。
- 回呼
  
  函式選填
  
  callback 參數如下所示：
```
() => void
```
- returns
  Promise<void>
  
  Chrome 88 以上版本
  
  承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。
setAccessLevel

void

Promise Chrome 102 以上版本

設定儲存空間區域的所需存取層級。預設值只會是受信任的內容。

setAccessLevel 函式如下所示：
```
(accessOptions: object, callback?: function) => {...}
```
- accessOptions
  
  物件
  - accessLevel
    
    AccessLevel
    
    儲存區的存取層級。
- 回呼
  
  函式選填
  
  callback 參數如下所示：
```
() => void
```
- returns
  Promise<void>
  
  承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

StorageChange

屬性

newValue

任何選填

項目的新值 (如有)。
oldValue

任何選填

項目的舊值 (如果有)。

屬性

local

local 儲存區中的項目是各機器的本機項目。

類型

StorageArea & object

屬性

QUOTA_BYTES

10485760

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

managed

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

類型

StorageArea

sync

sync 儲存區中的項目會使用 Chrome 同步功能進行同步。

類型

StorageArea & object

屬性

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 字串化加上鍵長度來評估。如果更新內容包含的項目大於此限制，則會立即失敗，並在使用回呼或 Promise 遭到拒絕時，設定 runtime.lastError。

活動

onChanged

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

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

參數

回呼

函式

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