說明
使用 chrome.cookies
API 查詢及修改 Cookie,並在 Cookie 變更時收到通知。
權限
cookies
資訊清單
如要使用 Cookie API,您必須在資訊清單中宣告「Cookie」權限,並針對您要存取 Cookie 的任何主機宣告主機權限。例如:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
分區
分區 Cookie 可讓網站標示特定 Cookie 應與頂層頁框的來源標記。也就是說,如果網站 A 使用網站 B 和網站 C 中的 iframe 來嵌入,則分區的 Cookie 可以有不同的值。
chrome.cookies
不支援分區,這表示所有方法都讀取及寫入所有分區的 Cookie。cookies.set()
方法會將 Cookie 儲存在預設分區中。
如要進一步瞭解擴充功能分區的一般影響,請參閱儲存空間與 Cookie。
示例
您可以在 examples/api/cookies 目錄中找到使用 Cookie API 的簡易範例。如需其他範例及查看原始碼的相關說明,請參閱範例。
類型
Cookie
代表 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 的名稱。
-
partitionKeyChrome 119 以上版本
分區索引鍵,用於透過分區屬性讀取或修改 Cookie。
-
path
字串
Cookie 的路徑。
-
sameSiteChrome 51 以上版本
Cookie 的相同網站狀態 (例如是否隨著跨網站要求一併傳送 Cookie)。
-
安全
boolean
如果 Cookie 標示為「安全」(也就是範圍僅限於安全通道,通常是 HTTPS),則為 True。
-
工作階段
boolean
如果 Cookie 是工作階段 Cookie,與設有到期日的永久 Cookie 不同,則為 True。
-
storeId
字串
包含此 Cookie 的 Cookie 儲存庫 ID,在 getAllCookieStores() 中提供。
-
值
字串
Cookie 的值。
CookieDetails
用於識別 Cookie 的詳細資料。
屬性
-
名稱
字串
要存取的 Cookie 名稱。
-
partitionKeyChrome 119 以上版本
分區索引鍵,用於透過分區屬性讀取或修改 Cookie。
-
storeId
字串 選用
要尋找 Cookie 的 Cookie 儲存庫 ID。根據預設,系統會使用目前執行內容的 Cookie 儲存庫。
-
網址
字串
與存取 Cookie 相關聯的網址。這個引數可能是完整網址,系統會直接忽略網址路徑後方的任何資料 (例如查詢字串)。如未在資訊清單檔案中指定這個網址的主機權限,API 呼叫就會失敗。
CookiePartitionKey
代表分區 Cookie 的分區索引鍵。
屬性
-
topLevelSite
字串 選用
可使用分區 Cookie 的頂層網站。
CookieStore
代表瀏覽器中的 Cookie 儲存庫。舉例來說,無痕模式視窗與非無痕視窗不同,會另外使用一個 Cookie 儲存庫。
屬性
-
id
字串
Cookie 儲存庫的專屬 ID。
-
tabIds
數字 []
共用此 Cookie 儲存庫的所有瀏覽器分頁 ID。
OnChangedCause
Cookie 改變的基本原因。如果 Cookie 是透過明確呼叫「chrome.cookies.remove」插入或移除,「cause」就會是「明確」。如果 Cookie 因過期而自動移除,「原因」就會「失效」。如果 Cookie 因為到期日過期而遭到移除,「原因」就會設為「expired_overwrite」。如果 Cookie 因為垃圾收集而自動移除,「原因」也會「移除」。如果 Cookie 是因為「set」呼叫而自動移除,而「原因」為覆寫該 Cookie 而遭自動移除,則「原因」會是「覆寫」。請據此規劃回應方式。
列舉
"expired_overwrite"
SameSiteStatus
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()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
擷取單一 Cookie 的相關資訊。如果指定網址有多個相同名稱的 Cookie,系統會傳迴路徑最長的 Cookie。對於路徑長度相同的 Cookie,系統會傳回建立時間最早的 Cookie。
參數
傳回
-
Promise<Cookie | undefined>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
從單一 Cookie 儲存庫擷取符合指定資訊的所有 Cookie。系統會依傳回的 Cookie 排序,Cookie 數量最長的 Cookie。如果多個 Cookie 的路徑長度相同,則會先建立建立時間最早的 Cookie。這個方法只會擷取擴充功能具有主機權限的網域的 Cookie。
參數
-
詳細資料
物件
用於篩選所擷取 Cookie 的資訊。
-
網域
字串 選用
將擷取的 Cookie 限制在網域相符或屬於這個網域的子網域。
-
名稱
字串 選用
依名稱篩選 Cookie。
-
partitionKeyChrome 119 以上版本
分區索引鍵,用於透過分區屬性讀取或修改 Cookie。
-
path
字串 選用
限制擷取的 Cookie 僅包含路徑與此字串完全相符的 Cookie。
-
安全
布林值 (選用)
根據 Cookie 的安全屬性篩選 Cookie。
-
工作階段
布林值 (選用)
篩除工作階段和永久性 Cookie。
-
storeId
字串 選用
要擷取 Cookie 的 Cookie 儲存區。如果省略,系統會使用目前執行內容的 Cookie 儲存庫。
-
網址
字串 選用
限制擷取的 Cookie 僅符合指定網址的項目。
-
-
回呼
函式選用
callback
參數如下所示:(cookies: Cookie[]) => void
-
Google Cloud 網站上的 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
-
詳細資料
物件選用
內含已移除 Cookie 的詳細資料。如果因故移除失敗,這個欄位的值會是「空值」,並設為
runtime.lastError
。-
名稱
字串
要移除的 Cookie 名稱。
-
partitionKeyChrome 119 以上版本
分區索引鍵,用於透過分區屬性讀取或修改 Cookie。
-
storeId
字串
已移除 Cookie 的 Cookie 儲存庫 ID。
-
網址
字串
與已移除 Cookie 相關聯的網址。
-
-
傳回
-
Promise<object | undefined>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
set()
chrome.cookies.set(
details: object,
callback?: function,
)
設定含有指定 Cookie 資料的 Cookie,並覆寫相同 Cookie (如果存在)。
參數
-
詳細資料
物件
所設定 Cookie 的詳細資料。
-
網域
字串 選用
Cookie 的網域。如果省略,Cookie 就會成為主機專用的 Cookie。
-
expirationDate
數字 選填
Cookie 的到期日,以從 UNIX 紀元開始算起的秒數。如果省略,Cookie 就會變成工作階段 Cookie。
-
httpOnly
布林值 (選用)
是否應將 Cookie 標示為 HttpOnly。預設值為 false。
-
名稱
字串 選用
Cookie 的名稱。若省略,則預設為空白。
-
partitionKeyChrome 119 以上版本
分區索引鍵,用於透過分區屬性讀取或修改 Cookie。
-
path
字串 選用
Cookie 的路徑。預設為網址參數的路徑部分。
-
sameSiteChrome 51 以上版本
Cookie 的相同網站狀態。預設為「未指定」。也就是說,如果省略,系統會在沒有指定 SameSite 屬性的情況下設定 Cookie。
-
安全
布林值 (選用)
是否應將 Cookie 標示為「安全」。預設值為 false。
-
storeId
字串 選用
用來設定 Cookie 的 Cookie 儲存庫 ID。根據預設,Cookie 是在目前執行內容的 Cookie 儲存庫中設定。
-
網址
字串
要與 Cookie 設定建立關聯的要求 URI。這個值可能會影響已建立 Cookie 的預設網域和路徑值,如未在資訊清單檔案中指定這個網址的主機權限,API 呼叫就會失敗。
-
值
字串 選用
Cookie 的值。若省略,則預設為空白。
-
-
回呼
函式選用
callback
參數如下所示:(cookie?: Cookie) => void
-
餅乾
Cookie 選用
包含已設定的 Cookie 詳情。如果因任何原因而設定失敗,這個欄位將會設為「空值」,並設為
runtime.lastError
。
-
傳回
-
Promise<Cookie | undefined>
Chrome 88 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
活動
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
在設定或移除 Cookie 時觸發。舉例來說,更新 Cookie 的屬性是兩個步驟進行:先完全移除要更新的 Cookie,然後產生「原因」為「覆寫」的通知。之後,系統會使用更新的值寫入新的 Cookie,產生第二次通知,並顯示「原因」為「明確」。
參數
-
回呼
功能
callback
參數如下所示:(changeInfo: object) => void
-
changeInfo
物件
-
cause
Cookie 改變的基本原因。
-
餅乾
所設定或移除的 Cookie 相關資訊。
-
已移除
boolean
如果 Cookie 已移除,則為「是」。
-
-