chrome.storage

說明

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

權限

storage

總覽

Storage API 提供專用的擴充功能，可保留使用者資料和狀態。與網路平台的 Storage API (IndexedDB 和 Storage) 類似，但其設計為符合擴充功能的儲存空間需求。以下是幾項主要功能：

  • 所有擴充功能內容，包括擴充功能 Service Worker 和內容指令碼，都可存取 Storage API。
  • JSON 可序列化值會儲存為物件屬性。
  • Storage API 具備大量讀取和寫入作業非同步。
  • 即使使用者清除快取和瀏覽記錄，資料仍會保留。
  • 即使使用分割無痕模式，儲存的設定仍會保持有效。
  • 包含企業政策的專屬唯讀代管儲存空間區域。

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

  • 擴充功能的 Service Worker 無法存取 Storage。
  • 內容指令碼會與主網頁共用儲存空間。
  • 使用者清除瀏覽記錄後，使用 Storage 介面儲存的資料會遺失。

如要將網路儲存空間 API 中的資料從 Service Worker 移至擴充功能儲存空間 API，請按照下列指示操作：

  1. 建立含有轉換處理常式和 [onMessage][訊息內容] 處理常式的螢幕外文件。
  2. 在畫面外的文件中新增轉換日常安排。
  3. 在擴充功能 Service Worker 中，檢查資料為 chrome.storage。
  4. 如果找不到您的資料，請 [建立][create-offscreen] 畫面外文件並呼叫 [sendMessage()][send-message] 來啟動轉換日常安排。
  5. 在畫面外文件的 onMessage 處理常式中，呼叫轉換處理常式。

此外，網站儲存空間 API 在擴充功能中的運作方式也有一些細微差異。詳情請參閱 [儲存空間和 Cookie][storage-and-cookies] 一文。

儲存空間區域

Storage API 分為以下四個值區 (「儲存區域」)：

storage.local
資料儲存在本機，擴充功能移除時就會清除這些資料。配額上限約為 10 MB，但您可以要求 "unlimitedStorage" 權限來提高配額。建議使用此語言儲存大量資料。
，瞭解如何調查及移除這項存取權。
storage.sync
如果已啟用同步功能，資料就會同步處理至使用者登入的任何 Chrome 瀏覽器。如果停用，運作情形會與 storage.local 相同。當瀏覽器離線時，Chrome 會將資料儲存在本機，並在瀏覽器恢復連線後繼續同步處理。配額上限約為 100 KB (每個項目 8 KB)。建議您使用這項功能，在保持同步的瀏覽器中保留使用者設定。
，瞭解如何調查及移除這項存取權。
storage.session
在瀏覽器工作階段期間，將資料保存在記憶體中。根據預設，系統不會向內容指令碼公開此行為，但您可以設定 chrome.storage.session.setAccessLevel() 來變更這項行為。配額上限約為 10 MB。請考慮用來在 Service Worker 執行作業中儲存全域變數。
，瞭解如何調查及移除這項存取權。
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，而 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);
});

擴充功能範例

如要查看 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

      字串