chrome.storage

說明

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

權限

storage

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

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

概念和用法

Storage API 提供特定擴充功能專用的方法來保存使用者資料和狀態。這與網路平台的儲存 API (IndexedDB 和 Storage) 類似，但是專為滿足擴充功能儲存需求而設計。以下是幾項主要功能：

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

擴充功能可以使用網路儲存空間 API 嗎？

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

• 擴充功能服務工作站無法使用 Web Storage API。
• 內容指令碼與代管網頁共用儲存空間。
• 使用者清除瀏覽記錄時，使用 Web Storage API 儲存的資料會遺失。

如何將網路儲存空間 API 中的資料移至擴充功能儲存空間 API，以便從 Service Worker 進行以下操作：

1. 準備畫面外的文件 HTML 網頁與指令碼檔案。指令碼檔案應包含轉換處理常式和 onMessage 處理常式。
2. 在擴充功能 Service Worker 中，檢查您的資料 chrome.storage。
3. 如果找不到資料，請呼叫 createDocument()。
4. 在傳回的 Promise 解決後，呼叫 sendMessage() 來啟動轉換日常安排。
5. 在畫面外文件的 onMessage 處理常式中，呼叫轉換處理常式。

而 Web Storage 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 介面是我們推薦給 Service Worker 的其中一個介面。

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"
指定來自擴充功能本身的結構定義。

"TRUSTED_AND_UNTRUSTED_CONTEXTS"
指定來自擴充功能外的結構定義。

StorageArea

屬性

• onChanged

  事件<functionvoidvoid>

  Chrome 73 以上版本

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

  onChanged.addListener 函式如下所示：

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

  • 回呼

    功能

    callback 參數如下所示：

    (changes: object)=>void

    • 變更

      物件

• 關閉

  void

  Promise

  從儲存空間移除所有項目。

  clear 函式如下所示：

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

  • 回呼

    函式選用

    callback 參數如下所示：

    ()=>void

  • returns

    Promise<void>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

• get

  void

  Promise

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

  get 函式如下所示：

  (keys?: string|string[]|object,callback?: function)=> {...}

  • 金鑰

    string|string[]|object optional

    要取得的單一鍵、要取得的鍵清單，或指定預設值的字典 (請參閱物件說明)。空白的清單或物件會傳回空的結果物件。傳入 null，即可取得儲存空間的完整內容。

  • 回呼

    函式選用

    callback 參數如下所示：

    (items: object)=>void

    • items

      物件

      內含項目的鍵/值對應項目。

  • returns

    Promise<object>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

• getBytesInUse

  void

  Promise

  取得一或多個項目正在使用的空間量 (以位元組為單位)。

  getBytesInUse 函式如下所示：

  (keys?: string|string[],callback?: function)=> {...}

  • 金鑰

    string|string[] optional

    用來取得總用量的單一鍵或鍵清單。空白清單會傳回 0。傳入 null 即可取得所有儲存空間的總用量。

  • 回呼

    函式選用

    callback 參數如下所示：

    (bytesInUse: number)=>void

    • bytesInUse

      號碼

      儲存空間中使用的空間量，以位元組為單位。

  • returns

    Promise<number>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

• remove

  void

  Promise

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

  remove 函式如下所示：

  (keys: string|string[],callback?: function)=> {...}

  • 金鑰

    字串|字串 []

    列出要移除的單一鍵或項目的按鍵清單。

  • 回呼

    函式選用

    callback 參數如下所示：

    ()=>void

  • returns

    Promise<void>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

• set

  void

  Promise

  設定多個項目。

  set 函式如下所示：

  (items: object,callback?: function)=> {...}

  • items

    物件

    物件，可為每個鍵/值組合提供更新儲存空間所用的物件。儲存空間中的任何其他鍵/值組合不會受到影響。

    數字等原始值會正常序列化。含有 typeof "object" 和 "function" 的值通常會序列化為 {}，但 Array 除外 (會正常序列化)、Date 和 Regex (使用其 String 表示法序列化)。

  • 回呼

    函式選用

    callback 參數如下所示：

    ()=>void

  • returns

    Promise<void>

    Chrome 88 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

• setAccessLevel

  void

  Promise Chrome 102 以上版本

  設定儲存區域所需的存取層級。只會預設為可信任的結構定義。

  setAccessLevel 函式如下所示：

  (accessOptions: object,callback?: function)=> {...}

  • accessOptions

    物件

    • accessLevel

      AccessLevel

      儲存空間區域的存取層級。

  • 回呼

    函式選用

    callback 參數如下所示：

    ()=>void

  • returns

    Promise<void>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

StorageChange

屬性

• newValue

  任何選填

  項目的新值 (如果有的話)。

• oldValue

  任何選填

  項目的舊值 (如有舊值)。

屬性

local

local 儲存區域中的項目是每部機器的本機檔案。

類型

StorageArea&object

屬性

• QUOTA_BYTES

  10485760
  

  可儲存在本機儲存空間中的資料大小上限 (以位元組為單位)，這是根據每個值加上每個鍵長度的 JSON 字串值測量而得。如果擴充功能具備 unlimitedStorage 權限，系統會忽略這個值。會導致立即超過這項限制的更新作業立即失敗，並在使用回呼時設定 runtime.lastError；如果使用 async/await，則拒絕 Promise。

managed

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

類型

StorageArea

session

Chrome 102 以上版本 MV3 以上版本

session 儲存空間區域中的項目會儲存在記憶體中，不會保存至磁碟。

類型

StorageArea&object

屬性

• QUOTA_BYTES

  10485760
  

  可儲存在記憶體中的資料大小上限 (以位元組為單位)，這是根據每個值和鍵的動態分配記憶體用量估計值計算得出。會導致立即超過這項限制的更新作業立即失敗，並在使用回呼或 Promise 遭拒時設定 runtime.lastError。

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

    字串