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

chrome.storage

說明

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

權限

storage

總覽

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

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

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

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

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

使用轉換常式和 [onMessage][on-message] 處理常式建立螢幕外文件。
在螢幕外文件中新增轉換常式。
在擴充功能服務工作人員檢查 chrome.storage 您的資料。
如果找不到資料，請 [建立][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: 管理員可以使用結構定義和企業政策，在受管理環境中設定支援的擴充功能。這個儲存空間是唯讀。

資訊清單

如要使用 Storage 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
  
  函式
  
  callback 參數如下：
```
(changes: object) => void
```
  - 變更
    
    物件
關閉

void

Promise

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

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

void

Promise

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

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

void

Promise Chrome 130 以上版本

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

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

void

Promise

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

remove 函式如下所示：
```
(keys: string | string[], callback?: function) => {...}
```
- 金鑰
  
  字串 | 字串陣列
  
  要移除的項目鍵 (單一鍵或鍵清單)。
- callback
  
  函式選用
  
  callback 參數如下：
```
() => void
```
- returns
  Promise<void>
  
  Chrome 95 以上版本
  
  只有資訊清單 V3 以上版本支援 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，其他平台則需使用回呼。
setAccessLevel

void

Promise Chrome 102 以上版本

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

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

StorageChange

屬性

newValue

不限選填

項目的新值 (如有)。
oldValue

不限選填

項目的舊值 (如有)。

屬性

local

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

類型

StorageArea 和物件

屬性

QUOTA_BYTES

10485760

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

managed

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

類型

StorageArea

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 次，比短期內每分鐘寫入次數上限還低。

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

120

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

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

102400

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

8192

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

事件

onChanged

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

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

參數

callback

函式

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

chrome.storage 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

說明

權限

總覽

儲存空間

資訊清單

用量

storage.local

storage.sync

storage.session

儲存空間和節流限制

用途

同步回應儲存空間更新

從儲存空間非同步預先載入

擴充功能範例

類型

AccessLevel

列舉

StorageArea

屬性

StorageChange

屬性

屬性

local

類型

屬性

managed

類型

sync

類型

屬性

事件

onChanged

參數

chrome.storage