chrome.cookies

說明

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

權限

cookies

如要使用 Cookie API，請在資訊清單中宣告 "cookies" 權限，並為要存取 Cookie 的任何主機宣告主機權限。例如：

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

分區

分割 Cookie 可讓網站標記特定 Cookie，以便根據頂層框架的來源建立索引鍵。舉例來說，如果網站 A 是透過 iframe 內嵌在網站 B 和 C 中，則來自 A 的分割 Cookie 內嵌版本在 B 和 C 上可能會有不同的值。

根據預設，所有 API 方法都會對未分割的 Cookie 執行作業。partitionKey 屬性可用於覆寫這個行為。

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

範例

您可以在 examples/api/cookies 目錄中找到使用 Cookie 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 的 SameSite 狀態 (即 Cookie 是否會隨跨網站要求傳送)。

  • 安全

    布林值

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

  • 工作階段

    布林值

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

  • storeId

    字串

    包含這個 Cookie 的 Cookie 商店 ID，如 getAllCookieStores() 中所提供。

  • 值

    字串

    Cookie 的值。

CookieDetails

Chrome 88 以上版本

用來識別 Cookie 的詳細資料。

屬性

  • 名稱

    字串

    要存取的 Cookie 名稱。

  • partitionKey

    CookiePartitionKey 選用

    Chrome 119 以上版本

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

  • storeId

    字串 選填

    要搜尋 Cookie 的 Cookie 商店 ID。根據預設，系統會使用目前執行環境的 Cookie 儲存區。

  • 網址

    字串

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

CookiePartitionKey

Chrome 119 以上版本

代表分區 Cookie 的分區金鑰。

屬性

  • hasCrossSiteAncestor

    布林值 選填

    Chrome 130 以上版本

    指出 Cookie 是否是在跨網站環境中設定。這樣一來，嵌入跨網站環境的頂層網站就無法存取頂層網站在同網站環境中設定的 Cookie。

  • topLevelSite

    字串 選填

    分區 Cookie 可用的頂層網站。

CookieStore

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

屬性

  • id

    字串

    Cookie 商店的專屬 ID。

  • tabIds

    number[]

    共用這個 Cookie 儲存空間的所有瀏覽器分頁的 ID。

FrameDetails

Chrome 132 以上版本

識別影格的詳細資料。

屬性

  • documentId

    字串 選填

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

  • frameId

    號碼 選填

    索引標籤中影格的專屬 ID。

  • tabId

    號碼 選填

    含有影格的分頁專屬 ID。

OnChangedCause

Chrome 44 以上版本

Cookie 變更的根本原因。如果透過明確呼叫「chrome.cookies.remove」插入或移除 Cookie，「cause」會是「explicit」。如果 Cookie 因過期而自動移除，「原因」會是「expired」。如果系統因覆寫已過期的到期日而移除 Cookie，「原因」會設為「expired_overwrite」。如果 Cookie 因垃圾收集而自動移除，「原因」會是「已清除」。如果 Cookie 因「設定」呼叫而遭到覆寫，並因此自動移除，「原因」會是「覆寫」。請據此規劃回覆內容。

列舉

「evicted」

"expired"

「explicit」

「expired_overwrite」

「overwrite」

SameSiteStatus

Chrome 51 以上版本

Cookie 的「SameSite」狀態 (https://tools.ietf.org/html/draft-west-first-party-cookies)。「no_restriction」對應於設有「SameSite=None」的 Cookie；「lax」對應於「SameSite=Lax」；「strict」對應於「SameSite=Strict」。「未指定」對應於未設定 SameSite 屬性的 Cookie。

列舉

「no_restriction」

「lax」

「strict」

「unspecified」

方法

get()

chrome.cookies.get(
  details: CookieDetails,
): Promise<Cookie | undefined>

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

參數

傳回

  • Promise<Cookie | undefined>

    Chrome 88 以上版本

getAll()

chrome.cookies.getAll(
  details: object,
): Promise<Cookie[]>

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

參數

  • 詳細資料

    物件

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

    • 網域

      字串 選填

      將擷取的 Cookie 限制為網域與這個網域相符或為這個網域的子網域。

    • 名稱

      字串 選填

      依名稱篩選 Cookie。

    • partitionKey

      CookiePartitionKey 選用

      Chrome 119 以上版本

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

    • 路徑

      字串 選填

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

    • 安全

      布林值 選填

      依據 Secure 屬性篩選 Cookie。

    • 工作階段

      布林值 選填

      篩除工作階段 Cookie 與永久 Cookie。

    • storeId

      字串 選填

      要從中擷取 Cookie 的 Cookie 商店。如果省略，系統會使用目前執行環境的 Cookie 儲存區。

    • 網址

      字串 選填

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

傳回

  • Promise<Cookie[]>

    Chrome 88 以上版本

getAllCookieStores()

chrome.cookies.getAllCookieStores(): Promise<CookieStore[]>

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

傳回

getPartitionKey()

Chrome 132 以上版本 
chrome.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

所指出影格的分區鍵。

參數

傳回

  • Promise<object>

remove()

chrome.cookies.remove(
  details: CookieDetails,
): Promise<object | undefined>

依名稱刪除 Cookie。

參數

傳回

  • Promise<object | undefined>

    Chrome 88 以上版本

set()

chrome.cookies.set(
  details: object,
): Promise<Cookie | undefined>

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

參數

  • 詳細資料

    物件

    設定的 Cookie 詳細資料。

    • 網域

      字串 選填

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

    • expirationDate

      號碼 選填

      Cookie 的到期日，以自 UNIX 紀元起算經過的秒數表示。如果省略，Cookie 會變成工作階段 Cookie。

    • httpOnly

      布林值 選填

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

    • 名稱

      字串 選填

      Cookie 的名稱。如果省略，預設為空白。

    • partitionKey

      CookiePartitionKey 選用

      Chrome 119 以上版本

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

    • 路徑

      字串 選填

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

    • sameSite

      SameSiteStatus 選填

      Chrome 51 以上版本

      Cookie 的同網站狀態。預設值為「unspecified」，也就是說，如果省略這個屬性，系統會設定 Cookie，但不指定 SameSite 屬性。

    • 安全

      布林值 選填

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

    • storeId

      字串 選填

      要設定 Cookie 的 Cookie 商店 ID。根據預設，Cookie 會在目前執行環境的 Cookie 存放區中設定。

    • 網址

      字串

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

    • 值

      字串 選填

      Cookie 的值。如果省略，預設為空白。

傳回

  • Promise<Cookie | undefined>

    Chrome 88 以上版本

事件

onChanged

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

在設定或移除 Cookie 時觸發。請注意，更新 Cookie 屬性是兩步驟程序，屬於特殊情況：系統會先完全移除要更新的 Cookie，並產生「原因」為「覆寫」的通知。接著，系統會寫入含有更新值的新 Cookie，並產生第二則「原因」為「明確」的通知。

參數

  • callback

    函式

    callback 參數如下： 

    (changeInfo: object) => void

    • changeInfo

      物件

      • Cookie 變更的根本原因。

      • 餅乾

        Cookie

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

      • 已移除

        布林值

        如果已移除 Cookie，則為 True。