chrome.storage

說明

使用 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，請按照下列指示操作：

  1. 請備妥螢幕外的文件 HTML 網頁和指令碼檔案。指令碼檔案應包含轉換處理常式和 onMessage 處理常式。
  2. 在擴充功能 Service Worker 中，檢查資料為 chrome.storage。
  3. 如果找不到所需資料，請呼叫 createDocument()。
  4. 傳回的 Promise 解析後，請呼叫 sendMessage() 來啟動轉換日常安排。
  5. 在畫面外文件的 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

Chrome 102 以上版本

儲存區域的存取層級。

列舉

"TRUSTED_CONTEXTS"
指定來自擴充功能本身的結構定義。

&quot;TRUSTED_AND_UNTRUSTED_CONTEXTS&quot;
指定源自於副檔名的背景資訊。

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&lt;object&gt;

      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&lt;number&gt;

      Chrome 88 以上版本

      Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

  • getKeys

    void

    Promise 待處理

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

    getKeys 函式如下所示： 

    (callback?: function) => {...}

    • 回呼

      函式 選用

      callback 參數如下所示： 

      (keys: string[]) => void

      • 金鑰

        string[]

        含有從儲存空間讀取金鑰的陣列。

    • returns

      Promise&lt;string[]&gt;

      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

        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 儲存空間區域的項目是由網域管理員設定的企業政策所設定，在擴充功能中處於唯讀狀態。嘗試修改這個命名空間導致錯誤。如要瞭解如何設定政策，請參閱儲存空間區域的資訊清單。

類型

StorageArea

session

Chrome 102 以上版本 MV3 以上

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

      字串