说明
使用 chrome.cookies
API 查询和修改 Cookie,并在 Cookie 发生更改时收到通知。
权限
cookies
清单
要使用 Cookie API,您必须声明“Cookie”权限 清单以及您需要其 Cookie 的所有主机的主机权限 访问。例如:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
分区
通过分区 Cookie,网站可以标记特定 Cookie 应针对 顶级帧的原点。也就是说,如果网站 A 是使用 iframe 嵌入网站 B 中的 和网站 C,则分区 Cookie 中的每个 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 的网域完全匹配,则为 True)。
-
httpOnly
布尔值
如果 Cookie 被标记为 HttpOnly(即客户端脚本无法访问 Cookie),则为 true。
-
name
字符串
Cookie 的名称。
-
partitionKeyChrome 119 及更高版本
分区键,用于读取或修改具有“分区”属性的 Cookie。
-
路径
字符串
Cookie 的路径。
-
sameSiteChrome 51 及更高版本
Cookie 的同网站状态(即 Cookie 是否随跨网站请求一起发送)。
-
安全
布尔值
如果 Cookie 被标记为“安全”(即,其范围仅限于安全通道,通常为 HTTPS),则为 True。
-
会话
布尔值
如果 Cookie 是会话 Cookie,则此值为 true,与具有失效日期的永久 Cookie 相反。
-
storeId
字符串
包含此 Cookie 的 Cookie 存储区的 ID,在 getAllCookieStores() 中提供。
-
值
字符串
Cookie 的值。
CookieDetails
用于标识 Cookie 的详细信息。
属性
-
name
字符串
要访问的 Cookie 的名称。
-
partitionKeyChrome 119 及更高版本
分区键,用于读取或修改具有“分区”属性的 Cookie。
-
storeId
字符串(可选)
要在其中查找 Cookie 的 Cookie 存储区的 ID。默认情况下,将使用当前执行上下文的 Cookie 存储区。
-
网址
字符串
要访问的 Cookie 所关联的网址。该参数可以是完整的网址,在这种情况下,网址路径后面的任何数据(例如查询字符串)都会被直接忽略。如果未在清单文件中指定此网址的主机权限,API 调用将会失败。
CookiePartitionKey
表示分区 Cookie 的分区键。
属性
-
topLevelSite
字符串(可选)
提供分区 Cookie 的顶级网站。
CookieStore
表示浏览器中的 Cookie 存储。例如,隐身模式窗口会在非隐身窗口中使用单独的 Cookie 存储区。
属性
-
id
字符串
Cookie 存储区的唯一标识符。
-
tabIds
数值 []
共享此 Cookie 存储区的所有浏览器标签页的标识符。
OnChangedCause
Cookie 发生变化的根本原因。如果插入了 Cookie,或通过明确调用“chrome.cookies.remove”而删除了 Cookie,则“cause”都将是“露骨内容”。如果 Cookie 因过期而被自动移除,则“原因”将会“过期”。如果 Cookie 因被已过期的失效日期被覆盖而遭到移除,“原因”将设置为“expired_overwrite”。如果 Cookie 因垃圾回收而被自动移除,则“原因”将被“逐出”。如果 Cookie 因“已设置”而自动移除CANNOT TRANSLATE将被“覆盖”。制定相应的应对计划。
枚举
“逐出”
"expired"
"露骨内容"
"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”。“unspecified”对应于未设置 SameSite 属性的 Cookie 集。
枚举
"no_restriction"
"lax"
"strict"
"unspecified"
方法
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
检索单个 Cookie 的相关信息。如果指定网址存在多个同名 Cookie,则返回路径最长的 Cookie。对于路径长度相同的 Cookie,将返回创建时间最早的 Cookie。
参数
返回
-
Promise<Cookie |未定义>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
从单个 Cookie 存储区中检索符合指定信息的所有 Cookie。系统会对返回的 Cookie 进行排序,路径最长的 Cookie 排在最前面。如果多个 Cookie 的路径长度相同,则创建时间最早的 Cookie 将排在最前面。此方法只会检索该扩展程序拥有托管权限的网域的 Cookie。
参数
-
详细信息
对象
用于过滤正在检索的 Cookie 的信息。
-
网域
字符串(可选)
将检索到的 Cookie 限制为域与此 Cookie 匹配或者是其子网域的 Cookie。
-
name
字符串(可选)
按名称过滤 Cookie。
-
partitionKeyChrome 119 及更高版本
分区键,用于读取或修改具有“分区”属性的 Cookie。
-
路径
字符串(可选)
将检索到的 Cookie 限制为路径与此字符串完全匹配的 Cookie。
-
安全
布尔值(可选)
按 Secure 属性过滤 Cookie。
-
会话
布尔值(可选)
过滤掉会话 Cookie 和永久 Cookie。
-
storeId
字符串(可选)
要从中检索 Cookie 的 Cookie 存储区。如果省略,将使用当前执行上下文的 Cookie 存储区。
-
网址
字符串(可选)
将检索到的 Cookie 限制为与指定网址匹配的 Cookie。
-
-
callback
函数(可选)
callback
参数如下所示:(cookies: Cookie[]) => void
-
Cookie
Cookie[]
符合指定 Cookie 信息的所有未过期的现有 Cookie。
-
返回
-
Promise<Cookie[]>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
列出所有现有的 Cookie 存储区。
参数
-
callback
函数(可选)
callback
参数如下所示:(cookieStores: CookieStore[]) => void
-
cookieStores
所有现有的 Cookie 存储区。
-
返回
-
Promise<CookieStore[]>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
按名称删除 Cookie。
参数
-
详细信息
-
callback
函数(可选)
callback
参数如下所示:(details?: object) => void
-
详细信息
对象(可选)
包含已移除的 Cookie 的详细信息。如果移除因任何原因失败,此值将为“null”,并设置
runtime.lastError
。-
name
字符串
已移除的 Cookie 的名称。
-
partitionKeyChrome 119 及更高版本
分区键,用于读取或修改具有“分区”属性的 Cookie。
-
storeId
字符串
从中删除了相应 Cookie 的 Cookie 存储区的 ID。
-
网址
字符串
与已移除的 Cookie 相关联的网址。
-
-
返回
-
Promise<object |未定义>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
set()
chrome.cookies.set(
details: object,
callback?: function,
)
使用指定的 Cookie 数据设置 Cookie;可能会覆盖等效的 Cookie(如果存在)。
参数
-
详细信息
对象
正在设置的 Cookie 的详细信息。
-
网域
字符串(可选)
Cookie 的网域。如果省略,该 Cookie 会成为主机专用 Cookie。
-
expirationDate
编号(选填)
Cookie 的有效期,以从 UNIX 纪元开始计算的秒数。如果省略,Cookie 将成为会话 Cookie。
-
httpOnly
布尔值(可选)
Cookie 是否应标记为 HttpOnly。默认值为 false。
-
name
字符串(可选)
Cookie 的名称。如果省略,则默认为为空。
-
partitionKeyChrome 119 及更高版本
分区键,用于读取或修改具有“分区”属性的 Cookie。
-
路径
字符串(可选)
Cookie 的路径。默认值为网址参数的路径部分。
-
sameSiteChrome 51 及更高版本
Cookie 同一网站的状态。默认值为“unspecified”,即如果省略,则会设置 Cookie,而不指定 SameSite 属性。
-
安全
布尔值(可选)
Cookie 是否应标记为“安全”。默认值为 false。
-
storeId
字符串(可选)
要在其中设置 Cookie 的 Cookie 存储区的 ID。默认情况下,Cookie 在当前执行环境的 Cookie 存储区中设置。
-
网址
字符串
要与 Cookie 设置相关联的请求 URI。此值可能会影响所创建 Cookie 的默认网域和路径值。如果未在清单文件中指定此网址的主机权限,API 调用将会失败。
-
值
字符串(可选)
Cookie 的值。如果省略,则默认为为空。
-
-
callback
函数(可选)
callback
参数如下所示:(cookie?: Cookie) => void
-
饼干
Cookie 可选
包含已设置的 Cookie 的详细信息。如果设置因任何原因失败,此字段将为“null”,并设置
runtime.lastError
。
-
返回
-
Promise<Cookie |未定义>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
事件
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
在设置或移除 Cookie 时触发。请注意,一种特殊情况是,更新 Cookie 属性的过程分为两个步骤:首先彻底删除要更新的 Cookie,然后生成一条包含“原因”的通知,共“覆盖”,了解所有最新动态。之后,新的 Cookie 会写入更新后的值,从而生成第二条通知,其中显示“cause”“露骨内容”。
参数
-
callback
函数
callback
参数如下所示:(changeInfo: object) => void
-
changeInfo
对象
-
cause
Cookie 发生变化的根本原因。
-
饼干
所设置或移除的 Cookie 的相关信息。
-
已移除
布尔值
如果移除了 Cookie,则为“true”。
-
-