StorageArea

refresh date: 2026-09-25 robots: noindex

chrome.storage API 會使用 StorageArea 介面。

方法

clear()

Promise 
chrome.storage.StorageArea.clear(
  callback?: function,
): Promise<void>

移除儲存空間中的所有項目。

參數

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 95 以上版本

    成功時會解析，失敗時會拒絕的 Promise。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

get()

Promise 
chrome.storage.StorageArea.get(
  keys?: string | string[] | object,
  callback?: function,
): Promise<object>

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

參數

  • 金鑰

    字串 | 字串陣列 | 物件 選用

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

  • callback

    函式 選填

    callback 參數如下： 

    (items: object) => void

    • 項目

      物件

      物件，內含鍵/值對應中的項目。

傳回

  • Promise<object>

    Chrome 95 以上版本

    這個 Promise 會解析為物件，其中包含所要求項目的鍵/值對應，或在失敗時遭到拒絕。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

getBytesInUse()

Promise 
chrome.storage.StorageArea.getBytesInUse(
  keys?: string | string[],
  callback?: function,
): Promise<number>

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

參數

  • 金鑰

    字串 | 字串陣列 選用

    單一金鑰或金鑰清單，用於取得總用量。如果清單為空白，則會傳回 0。傳遞 null 即可取得所有儲存空間的總用量。

  • callback

    函式 選填

    callback 參數如下： 

    (bytesInUse: number) => void

    • bytesInUse

      數字

      儲存空間用量 (以位元組為單位)。

傳回

  • Promise<數字>

    Chrome 95 以上版本

    這個 Promise 會解析儲存空間用量，或在失敗時拒絕。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

getKeys()

Promise Chrome 130 以上版本 
chrome.storage.StorageArea.getKeys(
  callback?: function,
): Promise<string[]>

從儲存空間取得所有鍵。

參數

  • callback

    函式 選填

    callback 參數如下： 

    (keys: string[]) => void

    • 金鑰

      string[]

      從儲存空間讀取的鍵陣列。

傳回

  • Promise<string[]>

    Promise，會以儲存空間金鑰解析，或在失敗時拒絕。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

remove()

Promise 
chrome.storage.StorageArea.remove(
  keys: string | string[],
  callback?: function,
): Promise<void>

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

參數

  • 金鑰

    字串 | 字串陣列

    要移除的項目索引鍵 (單一索引鍵或索引鍵清單)。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 95 以上版本

    成功時會解析，失敗時會拒絕的 Promise。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

set()

Promise 
chrome.storage.StorageArea.set(
  items: object,
  callback?: function,
): Promise<void>

設定多個項目。

參數

  • 項目

    物件

    這個物件會提供每個鍵/值組合，用來更新儲存空間。儲存空間中的其他鍵/值組不受影響。

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

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 95 以上版本

    成功時會解析的 Promise，或失敗時會拒絕的 Promise。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

setAccessLevel()

Promise Chrome 102 以上版本 
chrome.storage.StorageArea.setAccessLevel(
  accessOptions: object,
  callback?: function,
): Promise<void>

設定儲存空間的所需存取層級。根據預設，session 儲存空間僅限於可信任的環境 (擴充功能網頁和 Service Worker)，而 managed、local 和 sync 儲存空間則允許從可信任和不可信任的環境存取。

參數

  • accessOptions

    物件

    • accessLevel

      AccessLevel

      儲存空間的存取層級。

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    成功時會解析的 Promise，或失敗時會拒絕的 Promise。

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

onChanged

Chrome 73 以上版本 
chrome.storage.StorageArea.onChanged.addListener(
  callback: function,
)

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

參數

  • callback

    函式

    callback 參數如下： 

    (changes: object) => void

    • 變更

      物件