說明
請使用 chrome.cookies
API 查詢及修改 Cookie,並在 Cookie 變更時接收通知。
權限
cookies
資訊清單
若要使用 Cookie API,您必須宣告「Cookie」授予相關權限 以及您想要的 Cookie 主機的主機權限 。例如:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
分區
分區 Cookie 可允許網站標示特定的 Cookie 應以 也包含頂層頁框的原點也就是說,如果網站 A 是透過網站 B 的 iframe 嵌入 和網站 C,分區 Cookie 的每個值可能都不同。
chrome.cookies
不支援分區,這代表所有方法
讀取及寫入所有分區的 Cookie。cookies.set()
方法會將 Cookie 儲存在
預設分區
如要進一步瞭解將擴充功能分區的一般影響,請參閱 儲存空間和 Cookie。
範例
您可以在 examples/api/cookies 目錄。其他範例及說明 原始碼,請參閱範例。
類型
Cookie
代表 HTTP Cookie 相關資訊。
屬性
-
網域
字串
Cookie 的網域 (例如「www.google.com」、「example.com」)。
-
expirationDate
編號 選填
Cookie 的到期日,以自 UNIX 紀元時間起算的秒數。未提供工作階段 Cookie。
-
hostOnly
布林值
如果 Cookie 是僅限主機專用的 Cookie,則為「是」(亦即,請求的主機必須與 Cookie 的網域完全相符)。
-
httpOnly
布林值
如果 Cookie 標示為 HttpOnly (例如用戶端指令碼無法存取 Cookie),則為「是」。
-
名稱
字串
Cookie 的名稱。
-
partitionKeyChrome 119 以上版本
使用分區屬性讀取或修改 Cookie 的分區索引鍵。
-
路徑
字串
Cookie 的路徑。
-
sameSiteChrome 51 以上版本
Cookie 的同網站狀態 (也就是 Cookie 是否與跨網站要求一併送出)。
-
安全
布林值
如果 Cookie 標示為安全 (即範圍僅限於安全管道,通常是 HTTPS),則為「true」。
-
工作階段
布林值
如果 Cookie 是工作階段 Cookie,而不是有到期日的持續 Cookie,則為 True。
-
storeId
字串
含有此 Cookie 的 Cookie 儲存庫 ID (由 getAllCookieStores() 提供)。
-
值
字串
Cookie 的值。
CookieDetails
用來識別 Cookie 的詳細資料。
屬性
-
名稱
字串
存取的 Cookie 名稱。
-
partitionKeyChrome 119 以上版本
使用分區屬性讀取或修改 Cookie 的分區索引鍵。
-
storeId
string optional
用來尋找 Cookie 的 Cookie 儲存庫 ID。根據預設,系統會使用目前執行內容的 Cookie 儲存庫。
-
網址
字串
與要存取 Cookie 相關聯的網址。此引數可以是完整網址,在此情況下,網址路徑 (例如查詢字串) 後方的資料會遭到直接忽略。如未在資訊清單檔案中指定這個網址的主機權限,API 呼叫就會失敗。
CookiePartitionKey
代表分區 Cookie 的分區金鑰。
屬性
-
topLevelSite
string optional
可使用分區 Cookie 的頂層網站。
CookieStore
代表瀏覽器的 Cookie 儲存庫。舉例來說,無痕模式視窗會從非無痕式視窗另外使用 Cookie 儲存庫。
屬性
-
id
字串
Cookie 存放區的專屬 ID。
-
tabIds
數字 []
共用此 Cookie 儲存庫的所有瀏覽器分頁的 ID。
OnChangedCause
Cookie 異動的根本原因。如果 Cookie 是透過明確呼叫「chrome.cookies.remove」插入或移除,「原因」為「煽情露骨內容」。如果 Cookie 因到期而自動移除,請「原因」的狀態為「已過期」。如果 Cookie 因到期日已失效覆寫而遭到移除,系統會標示為「原因」會設為「expired_overwrite」。如果 Cookie 因垃圾收集而遭到自動移除,請「原因」標示為「撤銷」的狀態。Cookie 因「設定」而遭到自動移除打電話給你說了。「原因」變更為「覆寫」據此規劃回應方式。
列舉
"evicted"
"已過期"
「煽情露骨內容」
"expired_overwrite"
"覆寫"
SameSiteStatus
Cookie 的「SameSite」狀態 (https://tools.ietf.org/html/draft-west-first-party-cookies)。「no_restriction」對應至含有「SameSite=None」和「lax」的 Cookie「SameSite=Lax」和「strict」設為「SameSite=Strict」。「未指定」對應到不含 SameSite 屬性的 Cookie。
列舉
"no_restriction"
「寬鬆」
「嚴格」
"未指定"
方法
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
擷取單一 Cookie 的相關資訊。如果指定網址存在多個相同名稱的 Cookie,系統會傳迴路徑最長的 Cookie。如果是路徑長度相同的 Cookie,系統會傳回建立時間最早的 Cookie。
參數
傳回
-
Promise<Cookie |未定義>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
從單一 Cookie 儲存庫擷取所有與指定資訊相符的 Cookie。系統會將傳回的 Cookie 排序,路徑最長的 Cookie 會優先顯示。如果多個 Cookie 的路徑長度相同,系統會優先採用建立時間最早的 Cookie。這個方法只會針對擴充功能具有主機權限的網域擷取 Cookie。
參數
-
詳細資料
物件
用於篩選已擷取 Cookie 的資訊。
-
網域
string optional
將擷取的 Cookie 限制在網域相符或隸屬於其子網域的 Cookie。
-
名稱
string optional
按照名稱篩選 Cookie。
-
partitionKeyChrome 119 以上版本
使用分區屬性讀取或修改 Cookie 的分區索引鍵。
-
路徑
string optional
將擷取的 Cookie 限制在路徑與這個字串完全相符的 Cookie 內。
-
安全
布林值 選填
按照 Cookie 安全屬性篩選 Cookie。
-
工作階段
布林值 選填
篩選出工作階段與永久 Cookie。
-
storeId
string optional
用來擷取 Cookie 的 Cookie 儲存區。如果省略,系統會使用目前執行內容的 Cookie 儲存庫。
-
網址
string optional
將擷取的 Cookie 限制為符合指定網址的 Cookie。
-
-
回呼
函式 選用
callback
參數如下所示:(cookies: Cookie[]) => void
-
Cookie
Cookie[]
所有符合指定 Cookie 資訊的現有未過期 Cookie。
-
傳回
-
Promise<Cookie[]>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
列出所有現有的 Cookie 儲存庫。
參數
-
回呼
函式 選用
callback
參數如下所示:(cookieStores: CookieStore[]) => void
-
cookieStores
所有現有 Cookie 儲存庫。
-
傳回
-
Promise<CookieStore[]>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。
參數
-
詳細資料
-
回呼
函式 選用
callback
參數如下所示:(details?: object) => void
-
詳細資料
物件 optional
內含已移除的 Cookie 詳細資料。如果因為任何原因移除失敗,這個欄位會設為「null」,系統會在
runtime.lastError
中設定。-
名稱
字串
已移除的 Cookie 名稱,
-
partitionKeyChrome 119 以上版本
使用分區屬性讀取或修改 Cookie 的分區索引鍵。
-
storeId
字串
Cookie 移除來源的 ID。
-
網址
字串
與已移除的 Cookie 相關聯的網址。
-
-
傳回
-
Promise<object |未定義>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。
set()
chrome.cookies.set(
details: object,
callback?: function,
)
設定具有指定 Cookie 資料的 Cookie;可能會覆寫現有的 Cookie (如果有的話)。
參數
-
詳細資料
物件
所設定 Cookie 的詳細資料。
-
網域
string optional
Cookie 的網域。若省略,該 Cookie 會成為主機專用的 Cookie。
-
expirationDate
編號 選填
Cookie 的到期日,以自 UNIX 紀元時間起算的秒數。如果省略,該 Cookie 會成為工作階段 Cookie。
-
httpOnly
布林值 選填
是否應將 Cookie 標示為 HttpOnly。預設值為 false。
-
名稱
string optional
Cookie 的名稱。省略時則預設為空白。
-
partitionKeyChrome 119 以上版本
使用分區屬性讀取或修改 Cookie 的分區索引鍵。
-
路徑
string optional
Cookie 的路徑。預設為網址參數的路徑部分。
-
sameSiteChrome 51 以上版本
Cookie 的相同網站狀態。預設值為「未指定」,也就是說如未指定 SameSite 屬性,系統會設定 Cookie。
-
安全
布林值 選填
Cookie 是否應標示為安全。預設值為 false。
-
storeId
string optional
用於設定 Cookie 的 Cookie 儲存庫 ID。根據預設,Cookie 會設定在目前執行環境的 Cookie 儲存庫中。
-
網址
字串
與 Cookie 設定建立關聯的要求 URI。這個值會影響所建立 Cookie 的預設網域和路徑值。如未在資訊清單檔案中指定這個網址的主機權限,API 呼叫就會失敗。
-
值
string optional
Cookie 的值。省略時則預設為空白。
-
-
回呼
函式 選用
callback
參數如下所示:(cookie?: Cookie) => void
-
餅乾
Cookie 選用
內含所設定 Cookie 的詳細資料。如果因任何原因設定失敗,則會是「null」並
runtime.lastError
設定。
-
傳回
-
Promise<Cookie |未定義>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。
活動
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
設定或移除 Cookie 時觸發。在特殊案例中,請注意更新 Cookie 屬性的過程分為兩個步驟:系統會先徹底移除要更新的 Cookie,並產生一則含有「原因」的通知的「覆寫」,直接在 Google Cloud 控制台實際操作。之後,系統會使用更新的值寫入新的 Cookie,產生第二則通知,並註明「原因」「煽情露骨內容」。
參數
-
回呼
函式
callback
參數如下所示:(changeInfo: object) => void
-
changeInfo
物件
-
Cookie 異動的根本原因。
-
餅乾
設定或移除的 Cookie 相關資訊。
-
已移除
布林值
如果 Cookie 已遭移除,則為「true」。
-
-