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，請按照下列步驟操作：

  1. 使用轉換常式和 [onMessage][on-message] 處理常式建立螢幕外文件。
  2. 在螢幕外文件中新增轉換例行程序。
  3. 在擴充功能服務 worker 中，檢查 chrome.storage 是否有您的資料。
  4. 如果找不到資料，請 [create][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。建議您使用此方法，在服務工作程執行期間儲存全域變數。
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

      物件

    • 回呼

      函式 選填

      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

      字串