說明
使用 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 的簡單範例。如需其他範例和查看原始碼的說明，請參閱「範例」。
類型
Cookie
代表 HTTP Cookie 的相關資訊。
屬性
-
網域
字串
Cookie 的網域 (例如「www.google.com」、「example.com」)。
-
expirationDate
數字 選填
Cookie 的到期日，以 Unix 紀元起算，單位為秒。不適用於工作階段 Cookie。
-
hostOnly
布林值
如果 Cookie 是僅限主機的 Cookie (即要求的主機必須與 Cookie 的網域完全相符)，則為 True。
-
httpOnly
布林值
如果 Cookie 標示為 HttpOnly (即用戶端指令碼無法存取 Cookie)，則為 True。
-
名稱
字串
Cookie 的名稱。
-
partitionKeyChrome 119 以上版本 Chrome 148 以上版本的 browser.*
用於讀取或修改具有 Partitioned 屬性的 Cookie 的分區鍵。
-
路徑
字串
Cookie 的路徑。
-
sameSiteChrome 51 以上版本 Chrome 148 以上版本為 browser.*
Cookie 的同網站狀態 (即 Cookie 是否與跨網站要求一併傳送)。
-
安全
布林值
如果 Cookie 標示為「安全」(即範圍僅限安全管道，通常是 HTTPS)，則為 True。
-
工作階段
布林值
如果 Cookie 是工作階段 Cookie (而非有到期日的永久 Cookie)，則為 True。
-
storeId
字串
包含這個 Cookie 的 Cookie 存放區 ID，如 getAllCookieStores() 所示。
-
值
字串
Cookie 的值。
CookieDetails
用於識別 Cookie 的詳細資料。
屬性
-
名稱
字串
要存取的 Cookie 名稱。
-
partitionKeyChrome 119 以上版本 Chrome 148 以上版本的 browser.*
用於讀取或修改具有 Partitioned 屬性的 Cookie 的分區鍵。
-
storeId
字串 選填
要尋找 Cookie 的 Cookie 存放區 ID。根據預設，系統會使用目前執行環境的 Cookie 儲存庫。
-
網址
字串
與要存取的 Cookie 相關聯的網址。這個引數可以是完整網址，在這種情況下，網址路徑後方的任何資料 (例如查詢字串) 都會遭到忽略。如果資訊清單檔案未指定這個網址的主機權限，API 呼叫就會失敗。
CookiePartitionKey
代表分區 Cookie 的分區鍵。
屬性
-
hasCrossSiteAncestor
布林值 選填
Chrome 130 以上版本 Chrome 148 起為 browser.*指出 Cookie 是否在跨網站情境中設定。這樣一來，嵌入跨網站環境的頂層網站，就無法存取頂層網站在同網站環境中設定的 Cookie。
-
topLevelSite
字串 選填
可使用分區 Cookie 的頂層網站。
CookieStore
代表瀏覽器中的 Cookie 存放區。舉例來說，無痕模式視窗使用的 Cookie 存放區與非無痕視窗不同。
屬性
-
id
字串
Cookie 儲存庫的專屬 ID。
-
tabIds
number[]
共用這個 Cookie 儲存庫的所有瀏覽器分頁 ID。
FrameDetails
用於識別影格的詳細資料。
屬性
-
documentId
字串 選填
文件的專屬 ID。如果提供 frameId 和/或 tabId，系統會驗證這些 ID 是否與指定文件 ID 找到的文件相符。
-
frameId
數字 選填
分頁中頁框的專屬 ID。
-
tabId
數字 選填
包含頁框的分頁專屬 ID。
OnChangedCause
Cookie 變更的根本原因。如果 Cookie 是透過明確呼叫「chrome.cookies.remove」插入或移除，「cause」會是「explicit」。如果 Cookie 因到期而自動移除，「cause」會是「expired」。如果 Cookie 因到期日已過而遭覆寫移除，「cause」會設為「expired_overwrite」。如果 Cookie 因垃圾收集而自動移除，「cause」會是「evicted」。如果 Cookie 因「set」呼叫覆寫而自動移除，「cause」會是「overwrite」。請據此規劃因應措施。
列舉
"evicted"
"expired"
"explicit"
"expired_overwrite"
"overwrite"
SameSiteStatus
Cookie 的「SameSite」狀態 (https://tools.ietf.org/html/draft-west-first-party-cookies)。「no_restriction」對應至設為「SameSite=None」的 Cookie，「lax」對應至「SameSite=Lax」，「strict」則對應至「SameSite=Strict」。「unspecified」對應至未設定 SameSite 屬性的 Cookie。
列舉
"no_restriction"
"lax"
"strict"
"unspecified"
方法
get()
browser.cookies.get(
details: CookieDetails,
): Promise<Cookie | undefined>
擷取單一 Cookie 的資訊。如果指定網址有多個同名 Cookie，系統會傳回路徑最長的 Cookie。如果 Cookie 的路徑長度相同，系統會傳回建立時間最早的 Cookie。
參數
-
詳細資料
傳回
-
Promise<Cookie | undefined>
Chrome 88 以上版本 Chrome 148 起為瀏覽器。*
getAll()
browser.cookies.getAll(
details: object,
): Promise<Cookie[]>
從單一 Cookie 儲存庫中，擷取與指定資訊相符的所有 Cookie。傳回的 Cookie 會經過排序，路徑最長的 Cookie 會排在最前面。如果多個 Cookie 的路徑長度相同，則建立時間最早的 Cookie 會排在最前面。這個方法只會擷取擴充功能具備主機權限的網域 Cookie。
參數
-
詳細資料
物件
用於篩選所擷取 Cookie 的資訊。
-
網域
字串 選填
限制擷取的 Cookie，僅限網域與此網域相符或為此網域子網域的 Cookie。
-
名稱
字串 選填
依名稱篩選 Cookie。
-
partitionKeyChrome 119 以上版本 Chrome 148 以上版本的 browser.*
用於讀取或修改具有 Partitioned 屬性的 Cookie 的分區鍵。
-
路徑
字串 選填
限制擷取的 Cookie，只擷取路徑與這個字串完全相符的 Cookie。
-
安全
布林值 選填
依據 Secure 屬性篩選 Cookie。
-
工作階段
布林值 選填
篩除工作階段 Cookie 和永久 Cookie。
-
storeId
字串 選填
要從中擷取 Cookie 的 Cookie 存放區。如未提供，則會使用目前執行內容的 Cookie 儲存庫。
-
網址
字串 選填
限制擷取的 Cookie 必須與指定網址相符。
-
傳回
-
<Cookie[]> 的 Promise
Chrome 88 以上版本 Chrome 148 起為瀏覽器。*
getAllCookieStores()
browser.cookies.getAllCookieStores(): Promise<CookieStore[]>
列出所有現有的 Cookie 存放區。
傳回
-
<CookieStore[]> 承諾
Chrome 88 以上版本 Chrome 148 起為瀏覽器。*
getPartitionKey()
browser.cookies.getPartitionKey(
details: FrameDetails,
): Promise<object>
指定頁框的分區鍵。
參數
-
詳細資料
傳回
-
Promise<object>
remove()
browser.cookies.remove(
details: CookieDetails,
): Promise<object | undefined>
依名稱刪除 Cookie。
參數
-
詳細資料
傳回
-
Promise<object | undefined>
Chrome 88 以上版本 Chrome 148 起為瀏覽器。*
set()
browser.cookies.set(
details: object,
): Promise<Cookie | undefined>
使用指定的 Cookie 資料設定 Cookie；如果已有相同的 Cookie，可能會覆寫。
參數
-
詳細資料
物件
Cookie 設定的詳細資料。
-
網域
字串 選填
Cookie 的網域。如果省略，Cookie 會變成僅限主機的 Cookie。
-
expirationDate
數字 選填
Cookie 的到期日，以 Unix 紀元起算，單位為秒。如果省略，Cookie 會變成工作階段 Cookie。
-
httpOnly
布林值 選填
Cookie 是否應標示為 HttpOnly。預設值為 false。
-
名稱
字串 選填
Cookie 的名稱。如省略，預設為空白。
-
partitionKeyChrome 119 以上版本 Chrome 148 以上版本的 browser.*
用於讀取或修改具有 Partitioned 屬性的 Cookie 的分區鍵。
-
路徑
字串 選填
Cookie 的路徑。預設為網址參數的路徑部分。
-
sameSiteChrome 51 以上版本 Chrome 148 以上版本為 browser.*
Cookie 的 SameSite 狀態。預設值為「unspecified」，也就是說，如果省略，系統設定 Cookie 時不會指定 SameSite 屬性。
-
安全
布林值 選填
是否應將 Cookie 標示為「Secure」。預設值為 false。
-
storeId
字串 選填
要設定 Cookie 的 Cookie 儲存庫 ID。根據預設，Cookie 會設定在目前執行環境的 Cookie 儲存庫中。
-
網址
字串
與 Cookie 設定建立關聯的要求 URI。這個值可能會影響所建立 Cookie 的預設網域和路徑值。如果資訊清單檔案未指定這個網址的主機權限，API 呼叫就會失敗。
-
值
字串 選填
Cookie 的值。如省略，預設為空白。
-
傳回
-
Promise<Cookie | undefined>
Chrome 88 以上版本 Chrome 148 起為瀏覽器。*
事件
onChanged
browser.cookies.onChanged.addListener(
callback: function,
)
設定或移除 Cookie 時觸發。請注意，更新 Cookie 屬性是特殊情況，會分兩步驟執行：首先，系統會完全移除要更新的 Cookie，並產生「原因」為「覆寫」的通知。接著，系統會寫入含有更新值的新 Cookie，並產生第二個通知，其中「cause」為「explicit」。
參數
-
callback
函式
callback參數如下：(changeInfo: object) => void
-
changeInfo
物件
-
Cookie 變更的根本原因。
-
餅乾
已設定或移除的 Cookie 相關資訊。
-
已移除
布林值
如果 Cookie 已移除，則為 True。
-
-