说明
使用 chrome.cookies
API 查询和修改 Cookie,并在发生变化时收到通知。
权限
cookies
如需使用 Cookie API,请在清单中声明 "cookies"
权限,以及您要访问其 Cookie 的所有主机的主机权限。例如:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
分区
分区 Cookie 可让网站标记特定 Cookie 应与顶级框架的来源进行键控。这意味着,例如,如果使用网站 B 和网站 C 中的 iframe 嵌入网站 A,则来自 A 的分区 Cookie 的嵌入版本在 B 和 C 上具有不同的值。
默认情况下,所有 API 方法均对未分区的 Cookie 执行操作。partitionKey
属性可用于替换此行为。
如需详细了解对扩展程序进行分区的总体影响,请参阅存储和 Cookie。
示例
您可以在 examples/api/cookies 目录中找到使用 cookies API 的简单示例。如需查看其他示例以及在查看源代码方面获得帮助,请参阅示例。
类型
Cookie
表示 HTTP Cookie 的相关信息。
属性
-
网域
string
Cookie 的网域(例如“www.google.com”“example.com”)。
-
expirationDate
数字可选
Cookie 的有效期,以自 UNIX 纪元以来的秒数表示。不针对会话 Cookie 提供。
-
hostOnly
boolean
如果 Cookie 是主机专用 Cookie(即请求的主机必须与该 Cookie 的网域完全匹配),则为 true。
-
httpOnly
boolean
如果 Cookie 被标记为 HttpOnly(即客户端脚本无法访问该 Cookie),则该值为 true。
-
name
string
Cookie 的名称。
-
partitionKeyChrome 119 及更高版本
用于通过 Partitioned 属性读取或修改 Cookie 的分区键。
-
path
string
Cookie 的路径。
-
sameSiteChrome 51 及更高版本
Cookie 的同网站状态(即 Cookie 是否通过跨网站请求发送)。
-
安全
boolean
如果 Cookie 被标记为安全(即其范围被限定为安全通道,通常为 HTTPS),则为 true。
-
session
boolean
如果 Cookie 是会话 Cookie,而不是具有失效日期的持久性 Cookie,则为 true。
-
storeId
string
包含此 Cookie 的 Cookie 存储区的 ID,由 getAllCookieStores() 提供。
-
值
string
Cookie 的值。
CookieDetails
用于标识 Cookie 的详细信息。
属性
-
name
string
要访问的 Cookie 的名称。
-
partitionKeyChrome 119 及更高版本
用于通过 Partitioned 属性读取或修改 Cookie 的分区键。
-
storeId
字符串(可选)
要在其中查找 Cookie 的 Cookie 存储区的 ID。默认情况下,将使用当前执行上下文的 Cookie 存储。
-
网址
string
与要访问的 Cookie 相关联的网址。该参数可以是完整的网址,在这种情况下,系统会直接忽略网址路径后面的任何数据(例如查询字符串)。如果未在清单文件中指定此网址的主机权限,API 调用将会失败。
CookiePartitionKey
表示分区 Cookie 的分区键。
属性
-
topLevelSite
字符串(可选)
提供分区 Cookie 的顶级网站。
CookieStore
表示浏览器中的 Cookie 存储。例如,无痕模式窗口会使用与非无痕式窗口分开的 Cookie 存储。
属性
-
id
string
Cookie 存储的唯一标识符。
-
tabIds
数值 []
共享此 Cookie 存储区的所有浏览器标签页的标识符。
OnChangedCause
Cookie 发生变化的根本原因。如果插入了 Cookie,或通过明确调用“chrome.cookies.remove”移除了或移除了 Cookie,则“原因”将为“露骨内容”。如果 Cookie 是因过期而自动移除的,则“原因”对应的值会显示为“已过期”。如果 Cookie 因被过期日期覆盖而被移除,“原因”将设为“expired_overwrite”。如果 Cookie 是由于垃圾回收而自动移除的,则“原因”将会是“逐出”。如果 Cookie 是由于“set”调用覆盖了该 Cookie 而被自动移除,则“cause”将为“覆盖”。相应地制定响应计划。
枚举
"expired"
"expired_overwrite"
SameSiteStatus
Cookie 的“SameSite”状态 (https://tools.ietf.org/html/draft-west-first-party-cookies)。“no_restriction”对应于将 Cookie 设置为“SameSite=None”,将“lax”设置为“SameSite=Lax”,将“strict”设置为“SameSite=Strict”。“unspecified”对应于设置了 SameSite 属性的 Cookie。
枚举
"no_restriction"
"strict"
方法
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
检索单个 Cookie 的相关信息。如果指定网址存在多个同名的 Cookie,则返回路径最长的 Cookie。对于具有相同路径长度的 Cookie,系统将会返回创建时间最早的 Cookie。
参数
返回
-
Promise<Cookie | undefined>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
从单个 Cookie 存储区中检索与指定信息匹配的所有 Cookie。系统会对返回的 Cookie 进行排序,其中路径最长的 Cookie 排在最前面。如果多个 Cookie 的路径长度相同,则创建时间最早的 Cookie 排在最前面。此方法仅检索扩展程序拥有主机权限的网域的 Cookie。
参数
-
详细信息
对象
用于过滤正在检索的 Cookie 的信息。
-
网域
字符串(可选)
将检索到的 Cookie 限制为域与该 Cookie 匹配或属于其子网域的 Cookie。
-
name
字符串(可选)
按名称过滤 Cookie。
-
partitionKeyChrome 119 及更高版本
用于通过 Partitioned 属性读取或修改 Cookie 的分区键。
-
path
字符串(可选)
将检索到的 Cookie 限制为路径与该字符串完全匹配的 Cookie。
-
安全
布尔值 选填
按安全属性过滤 Cookie。
-
session
布尔值 选填
过滤掉会话 Cookie 和永久性 Cookie。
-
storeId
字符串(可选)
要从中检索 Cookie 的 Cookie 存储区。如果省略此参数,系统会使用当前执行上下文的 Cookie 存储。
-
网址
字符串(可选)
将检索到的 Cookie 限制为与指定网址匹配的 Cookie。
-
-
callback
函数(可选)
callback
参数如下所示:(cookies: Cookie[]) => void
-
Google Cloud 网站上的 Cookie,
Cookie[]
与指定 Cookie 信息匹配的所有现有未过期 Cookie。
-
返回
-
Promise<Cookie[]>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
列出所有现有的 Cookie 存储。
参数
-
callback
函数(可选)
callback
参数如下所示:(cookieStores: CookieStore[]) => void
-
cookieStores
所有现有的 Cookie 存储。
-
返回
-
Promise<CookieStore[]>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
参数
-
详细信息
-
callback
函数(可选)
callback
参数如下所示:(details?: object) => void
-
详细信息
对象(可选)
包含已被移除的 Cookie 的详细信息。如果移除因任何原因失败,此字段将为“null”并设置
runtime.lastError
。-
name
string
已移除的 Cookie 的名称。
-
partitionKeyChrome 119 及更高版本
用于通过 Partitioned 属性读取或修改 Cookie 的分区键。
-
storeId
string
从中移除 Cookie 的 Cookie 存储区的 ID。
-
网址
string
与已被移除的 Cookie 相关联的网址。
-
-
返回
-
Promise<object | undefined>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。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 及更高版本
用于通过 Partitioned 属性读取或修改 Cookie 的分区键。
-
path
字符串(可选)
Cookie 的路径。默认为 url 参数的路径部分。
-
sameSiteChrome 51 及更高版本
Cookie 的同网站状态。默认值为“未指定”,也就是说,如果省略,则设置 Cookie 时不指定 SameSite 属性。
-
安全
布尔值 选填
是否应将 Cookie 标记为“安全”。默认值为 false。
-
storeId
字符串(可选)
要在其中设置 Cookie 的 Cookie 存储区的 ID。默认情况下,系统会在当前执行环境的 Cookie 存储区中设置此 Cookie。
-
网址
string
与 Cookie 设置相关联的请求 URI。此值可影响所创建 Cookie 的默认网域值和路径值。如果未在清单文件中指定此网址的主机权限,API 调用将会失败。
-
值
字符串(可选)
Cookie 的值。如果省略,则默认为空。
-
-
callback
函数(可选)
callback
参数如下所示:(cookie?: Cookie) => void
-
饼干
Cookie(可选)
包含已设置的 Cookie 的相关详细信息。如果设置因任何原因失败,此值将为“null”,并将设置
runtime.lastError
。
-
返回
-
Promise<Cookie | undefined>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
活动
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
在设置或移除 Cookie 时触发。需要特别注意的是,Cookie 属性的更新过程分为两个步骤:首先,将要更新的 Cookie 完全删除,并生成“原因”为“覆盖”的通知。之后,系统会使用更新后的值写入一个新的 Cookie,从而生成第二个包含“原因”为“露骨内容”的通知。
参数
-
callback
功能
callback
参数如下所示:(changeInfo: object) => void
-
changeInfo
对象
-
cause
Cookie 发生变化的根本原因。
-
饼干
与已设置或移除的 Cookie 相关的信息。
-
已移除
boolean
如果 Cookie 已被移除,则为 true。
-
-