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

chrome.storage

說明

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

權限

storage

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

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

範例

以下範例示範 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 is set");
});

chrome.storage.session.get(["key"]).then((result) => {
  console.log("Value is " + result.key);
});

如要查看 Storage API 的其他試用版，請瀏覽下列任一範例：

概念和用途

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 的用量限制如下：

儲存資料會產生效能成本，且 API 包含儲存空間配額。規劃要儲存的資料，以維持儲存空間。
儲存作業可能需要一段時間才能完成。請根據該時間調整程式碼結構。

如要瞭解儲存空間限制，以及超出限制時會發生什麼情況，請參閱 sync、local 和 session 的配額資訊。

儲存空間

Storage API 分為下列儲存空間：

局部

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

代管

對於透過政策安裝的擴充功能，受管理儲存空間為唯讀。系統管理員會使用開發人員定義的結構和企業政策管理這項服務。政策與選項類似，但由系統管理員設定，而非使用者。這樣一來，擴充功能就能為機構的所有使用者預先設定。

根據預設，storage.managed 會公開給內容指令碼，但您可以呼叫 chrome.storage.managed.setAccessLevel() 變更這項行為。如要瞭解政策，請參閱管理員說明文件。如要進一步瞭解managed儲存空間區域，請參閱儲存空間區域資訊清單。

工作階段

工作階段儲存空間會在擴充功能載入時將資料保留在記憶體中。如果擴充功能遭到停用、重新載入、更新，以及瀏覽器重新啟動，儲存空間就會清除。根據預設，這項屬性不會向內容指令碼公開，但您可以呼叫 chrome.storage.session.setAccessLevel() 變更這項行為。儲存空間上限為 10 MB (Chrome 111 版以前為 1 MB)。

storage.session 介面是我們建議用於服務工作人員的介面之一。

同步

如果使用者啟用同步功能，資料就會同步到使用者登入的每個 Chrome 瀏覽器。如果停用，則行為與 storage.local 相同。瀏覽器離線時，Chrome 會在本機儲存資料，並在瀏覽器重新連線後繼續同步處理資料。配額限制約為 100 KB，每個項目 8 KB。

建議使用 storage.sync，在同步處理的瀏覽器之間保留使用者設定。如果您處理的是機密使用者資料，請改用 storage.session。根據預設，storage.sync 會公開給內容指令碼，但您可以呼叫 chrome.storage.sync.setAccessLevel() 變更這項行為。

方法和事件

所有儲存空間區域都會實作 StorageArea 介面。

get()

get() 方法可讓您從 StorageArea 讀取一或多個鍵。

getBytesInUse()

getBytesInUse() 方法可讓您查看 StorageArea 使用的配額。

getKeys()

getKeys() 方法可讓您取得儲存在 StorageArea 中的所有金鑰。

remove()

remove() 方法可讓您從 StorageArea 移除項目。

set()

set() 方法可讓您在 StorageArea 中設定項目。

setAccessLevel()

setAccessLevel() 方法可讓您控管 StorageArea 的存取權。

clear()

clear() 方法可讓您清除 StorageArea 中的所有資料。

onChanged

onChanged 事件可讓您監控 StorageArea 的變更。

用途

以下各節說明 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 儲存的資料。詳情請參閱開發人員工具說明文件中的「查看及編輯擴充功能儲存空間」頁面。

類型

AccessLevel

Chrome 102 以上版本

儲存空間的存取層級。

列舉

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

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

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

可儲存在記憶體中的資料量上限 (以位元組為單位)，計算方式為估算每個值和鍵的動態分配記憶體用量。如果更新會導致超出這項限制，系統會立即失敗並設定 runtime.lastError (使用回呼時) 或拒絕 Promise。

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 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

說明

權限

範例

範例 (當地)

範例 (同步)

範例 (工作階段)

概念和用途

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

儲存空間和節流限制

儲存空間

局部

代管

工作階段

同步

方法和事件

get()

getBytesInUse()

getKeys()

remove()

set()

setAccessLevel()

clear()

onChanged

用途

回應儲存空間更新

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

開發人員工具

類型

AccessLevel

列舉

StorageChange

屬性

屬性

local

類型

屬性

managed

類型

session

類型

屬性

sync

類型

屬性

事件

onChanged

參數

chrome.storage