chrome.cookies

說明

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

權限

cookies

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

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

分區

分區 Cookie 可讓網站將特定 Cookie 加上頂層頁框的來源標記。這表示若網站 A 使用網站 B 和網站 C 中的 iframe 嵌入網站，則 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

    boolean

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

  • httpOnly

    boolean

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

  • 名稱

    字串

    Cookie 的名稱。

  • partitionKey

    CookiePartitionKey 選用

    Chrome 119 以上版本

    分區索引鍵，用於透過分區屬性讀取或修改 Cookie。

  • path

    字串

    Cookie 的路徑。

  • sameSite

    SameSiteStatus

    Chrome 51 以上版本

    Cookie 的相同網站狀態 (例如是否隨著跨網站要求一併傳送 Cookie)。

  • 安全

    boolean

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

  • 工作階段

    boolean

    如果 Cookie 是工作階段 Cookie，與設有到期日的永久 Cookie 不同，則為 True。

  • storeId

    字串

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

  • 值

    字串

    Cookie 的值。

CookieDetails

Chrome 88 以上版本

用於識別 Cookie 的詳細資料。

屬性

  • 名稱

    字串

    要存取的 Cookie 名稱。

  • partitionKey

    CookiePartitionKey 選用

    Chrome 119 以上版本

    分區索引鍵，用於透過分區屬性讀取或修改 Cookie。

  • storeId

    字串 選用

    要尋找 Cookie 的 Cookie 儲存庫 ID。根據預設，系統會使用目前執行內容的 Cookie 儲存庫。

  • url

    字串

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

CookiePartitionKey

Chrome 119 以上版本

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

屬性

  • topLevelSite

    字串 選用

    可使用分區 Cookie 的頂層網站。

CookieStore

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

屬性

  • id

    字串

    Cookie 儲存庫的專屬 ID。

  • tabIds

    數字 []

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

OnChangedCause

Chrome 44 以上版本

Cookie 改變的基本原因。如果 Cookie 是透過明確呼叫「chrome.cookies.remove」插入或移除，「cause」就會是「明確」。如果 Cookie 因過期而自動移除，「原因」就會「失效」。如果 Cookie 因為到期日過期而遭到移除，「原因」就會設為「expired_overwrite」。如果 Cookie 因為垃圾收集而自動移除，「原因」也會「移除」。如果 Cookie 是因為「set」呼叫而自動移除，而「原因」為覆寫該 Cookie 而遭自動移除，則「原因」會是「覆寫」。請據此規劃回應方式。

列舉

"expired_overwrite"

SameSiteStatus

Chrome 51 以上版本

Cookie 的「SameSite」狀態 (https://tools.ietf.org/html/draft-west-first-party-cookies)。「no_restriction」會對應至使用「SameSite=None」、「lax」至「SameSite=Lax」且「Strict」至「SameSite=Strict」的 Cookie 組合。「未指定」代表的 Cookie 組合不含 SameSite 屬性。

列舉

"no_restriction"

"lax"

方法

get()

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

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

參數

  • 詳細資料

    CookieDetails

  • 回呼

    函式選用

    callback 參數如下所示： 

    (cookie?: Cookie)=>void

    • 餅乾

      Cookie 選用

      內含 Cookie 的詳細資料。如果找不到這類 Cookie，這個參數就會是 null。

傳回

  • Promise<Cookie|未定義>

    Chrome 88 以上版本

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

getAll()

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

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

參數

  • 詳細資料

    物件

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

    • 網域

      字串 選用

      將擷取的 Cookie 限制在網域相符或屬於這個網域的子網域。

    • 名稱

      字串 選用

      依名稱篩選 Cookie。

    • partitionKey

      CookiePartitionKey 選用

      Chrome 119 以上版本

      分區索引鍵，用於透過分區屬性讀取或修改 Cookie。

    • path

      字串 選用

      限制擷取的 Cookie 僅包含路徑與此字串完全相符的 Cookie。

    • 安全

      布林值 (選用)

      根據 Cookie 的安全屬性篩選 Cookie。

    • 工作階段

      布林值 (選用)

      篩除工作階段和永久性 Cookie。

    • storeId

      字串 選用

      要擷取 Cookie 的 Cookie 儲存區。如果省略，系統會使用目前執行內容的 Cookie 儲存庫。

    • url

      字串 選用

      限制擷取的 Cookie 僅符合指定網址的項目。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (cookies: Cookie[])=>void

    • Google Cloud 網站上的 Cookie

      Cookie[]

      所有與指定 Cookie 資訊相符的現有未過期 Cookie。

傳回

  • Promise<Cookie[]>

    Chrome 88 以上版本

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

getAllCookieStores()

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

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

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

      所有現有的 Cookie 儲存區。

傳回

  • Promise<CookieStore[]>

    Chrome 88 以上版本

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

remove()

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

依名稱刪除 Cookie。

參數

  • 詳細資料

    CookieDetails

  • 回呼

    函式選用

    callback 參數如下所示： 

    (details?: object)=>void

    • 詳細資料

      物件選用

      內含已移除 Cookie 的詳細資料。如果因故移除失敗，這個欄位的值會是「空值」，並設為 runtime.lastError。

      • 名稱

        字串

        要移除的 Cookie 名稱。

      • partitionKey

        CookiePartitionKey 選用

        Chrome 119 以上版本

        分區索引鍵，用於透過分區屬性讀取或修改 Cookie。

      • storeId

        字串

        已移除 Cookie 的 Cookie 儲存庫 ID。

      • url

        字串

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

傳回

  • Promise<object|undefined>

    Chrome 88 以上版本

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

set()

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

設定含有指定 Cookie 資料的 Cookie，並覆寫相同 Cookie (如果存在)。

參數

  • 詳細資料

    物件

    所設定 Cookie 的詳細資料。

    • 網域

      字串 選用

      Cookie 的網域。如果省略，Cookie 就會成為主機專用的 Cookie。

    • expirationDate

      數字 選填

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

    • httpOnly

      布林值 (選用)

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

    • 名稱

      字串 選用

      Cookie 的名稱。若省略，則預設為空白。

    • partitionKey

      CookiePartitionKey 選用

      Chrome 119 以上版本

      分區索引鍵，用於透過分區屬性讀取或修改 Cookie。

    • path

      字串 選用

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

    • sameSite

      SameSiteStatus 選用

      Chrome 51 以上版本

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

    • 安全

      布林值 (選用)

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

    • storeId

      字串 選用

      用來設定 Cookie 的 Cookie 儲存庫 ID。根據預設，Cookie 是在目前執行內容的 Cookie 儲存庫中設定。

    • url

      字串

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

    • 值

      字串 選用

      Cookie 的值。若省略，則預設為空白。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (cookie?: Cookie)=>void

    • 餅乾

      Cookie 選用

      包含已設定的 Cookie 詳情。如果因任何原因而設定失敗，這個欄位將會設為「空值」，並設為 runtime.lastError。

傳回

  • Promise<Cookie|未定義>

    Chrome 88 以上版本

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

活動

onChanged

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

在設定或移除 Cookie 時觸發。舉例來說，更新 Cookie 的屬性是兩個步驟進行：先完全移除要更新的 Cookie，然後產生「原因」為「覆寫」的通知。之後，系統會使用更新的值寫入新的 Cookie，產生第二次通知，並顯示「原因」為「明確」。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (changeInfo: object)=>void

    • changeInfo

      物件

      • Cookie 改變的基本原因。

      • 餅乾

        Cookie

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

      • 已移除

        boolean

        如果 Cookie 已移除，則為「是」。