chrome.cookies

說明

使用 chrome.cookies API 查詢及修改 Cookie，並在 Cookie 變更時收到通知。

權限

cookies

資訊清單

如要使用 cookies API，您必須在資訊清單中宣告「cookies」權限，以及您要存取 cookie 的任何主機的主機權限。例如：

{
  "name": "My extension",
  ...
  "host_permissions": [
    "*://*.google.com/"
  ],
  "permissions": [
    "cookies"
  ],
  ...
}

分區

分區 Cookie 可讓網站標示特定 Cookie 應以頂層框架的來源做為索引。也就是說，如果網站 A 使用 iframe 嵌入網站 B 和網站 C，則分割 Cookie 在各網站中的值可能不同。

chrome.cookies 不支援分區，也就是說，所有方法都會讀取及寫入所有分區的 Cookie。cookies.set() 方法會將 Cookie 儲存在預設分區中。

如要進一步瞭解擴充功能分區的一般影響，請參閱「儲存空間和 Cookie」。

範例

您可以在 examples/api/cookies 目錄中找到使用 cookies API 的簡單範例。如需其他範例，以及查看原始碼的相關說明，請參閱「範例」。

類型

代表 HTTP Cookie 的資訊。

屬性

  • 網域

    字串

    Cookie 的網域 (例如「www.google.com」、「example.com」)。

  • expirationDate

    號碼 選填

    Cookie 的到期日，以自 Unix 紀元開始算起的秒數為單位。不適用於工作階段 Cookie。

  • hostOnly

    布林值

    如果 Cookie 是主機專用 Cookie (也就是要求的主機必須與 Cookie 的網域完全相符)，則為 True。

  • httpOnly

    布林值

    如果 Cookie 已標示為 HttpOnly (也就是說，Cookie 無法由用戶端側指令碼存取)，則為 True。

  • 名稱

    字串

    Cookie 的名稱。

  • partitionKey

    CookiePartitionKey 選填

    Chrome 119 以上版本

    使用 Partitioned 屬性讀取或修改 Cookie 的分區索引鍵。

  • 路徑

    字串

    Cookie 的路徑。

  • sameSite

    SameSiteStatus

    Chrome 51 以上版本

    Cookie 的同網站狀態 (也就是 Cookie 是否透過跨網站要求傳送)。

  • 安全

    布林值

    如果 cookie 標示為「安全」，則為 True (也就是說，其範圍僅限於安全管道，通常是 HTTPS)。

  • 工作階段

    布林值

    如果 Cookie 是工作階段 Cookie (而非設有到期日期的永久 Cookie)，則為 True。

  • storeId

    字串

    包含此 Cookie 的 Cookie 儲存庫 ID，如 getAllCookieStores() 所提供。

  • 值

    字串

    Cookie 的值。

CookieDetails

Chrome 88 以上版本

用於識別 Cookie 的詳細資料。

屬性

  • 名稱

    字串

    要存取的 Cookie 名稱。

  • partitionKey

    CookiePartitionKey 選填

    Chrome 119 以上版本

    使用 Partitioned 屬性讀取或修改 Cookie 的分區索引鍵。

  • storeId

    string 選填

    要查找 Cookie 的 Cookie 儲存庫 ID。根據預設，系統會使用目前執行情境的 Cookie 儲存庫。

  • 網址

    字串

    與要存取的 Cookie 相關聯的網址。這個引數可能是完整網址，在這種情況下，系統會直接忽略網址路徑後方的任何資料 (例如查詢字串)。如果資訊清單檔案未指定此網址的主機權限，API 呼叫就會失敗。

CookiePartitionKey

Chrome 119 以上版本

代表分區 Cookie 的分區索引鍵。

屬性

  • hasCrossSiteAncestor

    boolean 選填

    Chrome 130 以上版本

    指出 Cookie 是否在跨網站內容中設定。這可防止在跨網站內容中嵌入的頂層網站，存取同網站內容中頂層網站設定的 Cookie。

  • topLevelSite

    string 選填

    分區 Cookie 可用的頂層網站。

CookieStore

代表瀏覽器中的 Cookie 儲存庫。舉例來說，無痕模式視窗會使用與非無痕模式視窗不同的 Cookie 儲存庫。

屬性

  • id

    字串

    Cookie 儲存庫的專屬 ID。

  • tabIds

    number[]

    共用此 Cookie 儲存庫的所有瀏覽器分頁 ID。

FrameDetails

待處理

用於識別影格片段的詳細資料。

屬性

  • documentId

    string 選填

    文件的專屬 ID。如果提供 frameId 和/或 tabId，系統會驗證這些值是否與所提供的文件 ID 所找到的文件相符。

  • frameId

    號碼 選填

    分頁中框架的專屬 ID。

  • tabId

    號碼 選填

    包含框架的分頁的專屬 ID。

OnChangedCause

Chrome 44 以上版本

變更 Cookie 的根本原因。如果您是透過明確呼叫「chrome.cookies.remove」插入或移除 Cookie，則「原因」會是「明確」。如果 Cookie 因到期而自動移除，則「原因」會顯示「expired」。如果 Cookie 已遭到覆寫，且覆寫的 Cookie 已過期，則「cause」會設為「expired_overwrite」。如果 Cookie 因垃圾收集而自動移除，則「原因」會是「evicted」。如果 Cookie 因「set」呼叫覆寫而自動移除，「cause」會是「overwrite」。並據此規劃回應方式。

列舉

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 以上版本

Cookie 的「SameSite」狀態 (https://tools.ietf.org/html/draft-west-first-party-cookies)。「no_restriction」對應至 Cookie 集，其中「SameSite=None」、「lax」對應至「SameSite=Lax」，「strict」對應至「SameSite=Strict」。「未指定」對應至未附加 SameSite 屬性的 Cookie 集。

列舉

"no_restriction"

"lax"

"strict"

"unspecified"

方法

get()

Promise 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

擷取單一 Cookie 的相關資訊。如果指定網址有一個以上的同名 Cookie，系統會傳回路徑最長的 Cookie。對於路徑長度相同的 Cookie，系統會傳回建立時間最早的 Cookie。

參數

  • 詳細資料

    CookieDetails

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (cookie?: Cookie) => void

    • 餅乾

      Cookie 選填

      包含 Cookie 的詳細資料。如果找不到這類 Cookie，這個參數會為空值。

傳回

  • Promise<Cookie | undefined>

    Chrome 88 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getAll()

Promise 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

從單一 Cookie 存放區擷取與指定資訊相符的所有 Cookie。系統會將傳回的 Cookie 排序，先傳回路徑最長的 Cookie。如果有多個 Cookie 的路徑長度相同，系統會優先使用建立時間最早的 Cookie。這個方法只會擷取擴充功能有主機權限的網域 Cookie。

參數

  • 詳細資料

    物件

    用於篩選要擷取的 Cookie 資訊。

    • 網域

      string 選填

      將擷取的 Cookie 限制在網域相符或為此網域子網域的 Cookie。

    • 名稱

      string 選填

      依名稱篩選 Cookie。

    • partitionKey

      CookiePartitionKey 選填

      Chrome 119 以上版本

      使用 Partitioned 屬性讀取或修改 Cookie 的分區索引鍵。

    • 路徑

      string 選填

      將擷取的 Cookie 限制為路徑與此字串完全相符的 Cookie。

    • 安全

      boolean 選填

      依 Secure 屬性篩選 Cookie。

    • 工作階段

      boolean 選填

      篩除工作階段和持續性 Cookie。

    • storeId

      string 選填

      要擷取 Cookie 的 Cookie 儲存庫。如果省略，系統會使用目前執行作業環境的 Cookie 儲存庫。

    • 網址

      string 選填

      將擷取的 Cookie 限制為與指定網址相符的 Cookie。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (cookies: Cookie[]) => void

    • Cookie

      Cookie[]

      所有符合指定 Cookie 資訊的現有 Cookie。

傳回

  • Promise<Cookie[]>

    Chrome 88 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getAllCookieStores()

Promise 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

列出所有現有的 Cookie 儲存庫。

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      所有現有的 Cookie 儲存庫。

傳回

  • Promise<CookieStore[]>

    Chrome 88 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getPartitionKey()

Promise 待處理
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

所指示影格片段的分割鍵。

參數

  • 詳細資料

    FrameDetails

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      包含已擷取的分割鍵詳細資料。

      • partitionKey

        CookiePartitionKey

        使用 Partitioned 屬性讀取或修改 Cookie 的分區索引鍵。

傳回

  • Promise<object>

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

remove()

Promise 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

依名稱刪除 Cookie。

參數

  • 詳細資料

    CookieDetails

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (details?: object) => void

    • 詳細資料

      物件 選填

      包含已移除的 Cookie 詳細資料。如果移除作業因任何原因失敗，這項屬性會設為「null」，並設定 runtime.lastError。

      • 名稱

        字串

        已移除的 Cookie 名稱。

      • partitionKey

        CookiePartitionKey 選填

        Chrome 119 以上版本

        使用 Partitioned 屬性讀取或修改 Cookie 的分區索引鍵。

      • storeId

        字串

        移除 Cookie 的 Cookie 儲存庫 ID。

      • 網址

        字串

        與已移除的 Cookie 相關聯的網址。

傳回

  • Promise<object | undefined>

    Chrome 88 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

set()

Promise 
chrome.cookies.set(
  details: object,
  callback?: function,
)

使用指定的 Cookie 資料設定 Cookie；如果有相等的 Cookie，可能會覆寫這些 Cookie。

參數

  • 詳細資料

    物件

    所設定 Cookie 的詳細資料。

    • 網域

      string 選填

      Cookie 的網域。如果省略，Cookie 就會變成僅限主機的 Cookie。

    • expirationDate

      號碼 選填

      Cookie 的到期日，以自 Unix 紀元開始算起的秒數為單位。如果省略，Cookie 就會變成工作階段 Cookie。

    • httpOnly

      boolean 選填

      是否應將 Cookie 標示為 HttpOnly。預設值為 false。

    • 名稱

      string 選填

      Cookie 的名稱。如未提供，預設為空白。

    • partitionKey

      CookiePartitionKey 選填

      Chrome 119 以上版本

      使用 Partitioned 屬性讀取或修改 Cookie 的分區索引鍵。

    • 路徑

      string 選填

      Cookie 的路徑。預設為網址參數的路徑部分。

    • sameSite

      SameSiteStatus 選填

      Chrome 51 以上版本

      Cookie 的同網站狀態。預設值為「unspecified」，也就是說，如果省略，則 Cookie 會在未指定 SameSite 屬性的情況下設定。

    • 安全

      boolean 選填

      是否要將 Cookie 標示為安全。預設值為 false。

    • storeId

      string 選填

      要設定 Cookie 的 Cookie 儲存庫 ID。根據預設，Cookie 會在目前執行作業內容的 Cookie 儲存庫中設定。

    • 網址

      字串

      與 Cookie 設定相關聯的要求 URI。這個值可能會影響建立的 Cookie 的預設網域和路徑值。如果資訊清單檔案未指定此網址的主機權限，API 呼叫就會失敗。

    • 值

      string 選填

      Cookie 的值。如未提供，預設為空白。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (cookie?: Cookie) => void

    • 餅乾

      Cookie 選填

      包含已設定的 Cookie 詳細資料。如果設定失敗，則會設為「null」，並設定 runtime.lastError。

傳回

  • Promise<Cookie | undefined>

    Chrome 88 以上版本

    承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

活動

onChanged

chrome.cookies.onChanged.addListener(
  callback: function,
)

在設定或移除 Cookie 時觸發。請注意，更新 Cookie 屬性是透過兩個步驟完成的特殊作業：系統會先完全移除要更新的 Cookie，然後產生通知，其中的「原因」為「覆寫」。接著，系統會使用更新後的值寫入新的 Cookie，並產生第二個通知，其中的「原因」為「明確」。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (changeInfo: object) => void

    • changeInfo

      物件

      • 變更 Cookie 的根本原因。

      • 餅乾

        Cookie

        已設定或移除的 Cookie 相關資訊。

      • 已移除

        布林值

        如果 Cookie 已移除，則為 True。