chrome.cookies

说明

使用 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 的简单示例。如需查看其他示例以及在查看源代码方面获得帮助，请参阅示例。

类型

表示 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 的名称。

  • partitionKey

    CookiePartitionKey 可选

    Chrome 119 及更高版本

    用于通过 Partitioned 属性读取或修改 Cookie 的分区键。

  • path

    string

    Cookie 的路径。

  • sameSite

    SameSiteStatus

    Chrome 51 及更高版本

    Cookie 的同网站状态（即 Cookie 是否通过跨网站请求发送）。

  • 安全

    boolean

    如果 Cookie 被标记为安全（即其范围被限定为安全通道，通常为 HTTPS），则为 true。

  • session

    boolean

    如果 Cookie 是会话 Cookie，而不是具有失效日期的持久性 Cookie，则为 true。

  • storeId

    string

    包含此 Cookie 的 Cookie 存储区的 ID，由 getAllCookieStores() 提供。

  • 值

    string

    Cookie 的值。

CookieDetails

Chrome 88 及更高版本

用于标识 Cookie 的详细信息。

属性

  • name

    string

    要访问的 Cookie 的名称。

  • partitionKey

    CookiePartitionKey 可选

    Chrome 119 及更高版本

    用于通过 Partitioned 属性读取或修改 Cookie 的分区键。

  • storeId

    字符串（可选）

    要在其中查找 Cookie 的 Cookie 存储区的 ID。默认情况下，将使用当前执行上下文的 Cookie 存储。

  • 网址

    string

    与要访问的 Cookie 相关联的网址。该参数可以是完整的网址，在这种情况下，系统会直接忽略网址路径后面的任何数据（例如查询字符串）。如果未在清单文件中指定此网址的主机权限，API 调用将会失败。

CookiePartitionKey

Chrome 119 及更高版本

表示分区 Cookie 的分区键。

属性

  • topLevelSite

    字符串（可选）

    提供分区 Cookie 的顶级网站。

CookieStore

表示浏览器中的 Cookie 存储。例如，无痕模式窗口会使用与非无痕式窗口分开的 Cookie 存储。

属性

  • id

    string

    Cookie 存储的唯一标识符。

  • tabIds

    数值 []

    共享此 Cookie 存储区的所有浏览器标签页的标识符。

OnChangedCause

Chrome 44 及更高版本

Cookie 发生变化的根本原因。如果插入了 Cookie，或通过明确调用“chrome.cookies.remove”移除了或移除了 Cookie，则“原因”将为“露骨内容”。如果 Cookie 是因过期而自动移除的，则“原因”对应的值会显示为“已过期”。如果 Cookie 因被过期日期覆盖而被移除，“原因”将设为“expired_overwrite”。如果 Cookie 是由于垃圾回收而自动移除的，则“原因”将会是“逐出”。如果 Cookie 是由于“set”调用覆盖了该 Cookie 而被自动移除，则“cause”将为“覆盖”。相应地制定响应计划。

枚举

"expired"

"expired_overwrite"

SameSiteStatus

Chrome 51 及更高版本

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()

Promise 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

检索单个 Cookie 的相关信息。如果指定网址存在多个同名的 Cookie，则返回路径最长的 Cookie。对于具有相同路径长度的 Cookie，系统将会返回创建时间最早的 Cookie。

参数

  • 明细

    CookieDetails

  • callback

    函数（可选）

    callback 参数如下所示：

    (cookie?: Cookie)=>void

    • 饼干

      Cookie（可选）

      包含有关 Cookie 的详细信息。如果找不到此类 Cookie，此参数为 null。

返回

  • Promise<Cookie|未定义>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getAll()

Promise 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

从单个 Cookie 存储区中检索与指定信息匹配的所有 Cookie。系统会对返回的 Cookie 进行排序，其中路径最长的 Cookie 排在最前面。如果多个 Cookie 的路径长度相同，则创建时间最早的 Cookie 排在最前面。此方法仅检索扩展程序拥有主机权限的网域的 Cookie。

参数

  • 明细

    对象

    用于过滤正在检索的 Cookie 的信息。

    • 网域

      字符串（可选）

      将检索到的 Cookie 限制为域与该 Cookie 匹配或属于其子网域的 Cookie。

    • name

      字符串（可选）

      按名称过滤 Cookie。

    • partitionKey

      CookiePartitionKey 可选

      Chrome 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()

Promise 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

列出所有现有的 Cookie 存储。

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

      所有现有的 Cookie 存储。

返回

  • Promise<CookieStore[]>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

remove()

Promise 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

按名称删除 Cookie。

参数

  • 明细

    CookieDetails

  • callback

    函数（可选）

    callback 参数如下所示：

    (details?: object)=>void

    • 明细

      对象（可选）

      包含已被移除的 Cookie 的详细信息。如果移除因任何原因失败，此字段将为“null”并设置 runtime.lastError。

      • name

        string

        已移除的 Cookie 的名称。

      • partitionKey

        CookiePartitionKey 可选

        Chrome 119 及更高版本

        用于通过 Partitioned 属性读取或修改 Cookie 的分区键。

      • storeId

        string

        从中移除 Cookie 的 Cookie 存储区的 ID。

      • 网址

        string

        与已被移除的 Cookie 相关联的网址。

返回

  • Promise<object|undefined>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

set()

Promise 
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 的名称。如果省略，则默认为空。

    • partitionKey

      CookiePartitionKey 可选

      Chrome 119 及更高版本

      用于通过 Partitioned 属性读取或修改 Cookie 的分区键。

    • path

      字符串（可选）

      Cookie 的路径。默认为 url 参数的路径部分。

    • sameSite

      SameSiteStatus 可选

      Chrome 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|未定义>

    Chrome 88 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

活动

onChanged

chrome.cookies.onChanged.addListener(
  callback: function,
)

在设置或移除 Cookie 时触发。需要特别注意的是，Cookie 属性的更新过程分为两个步骤：首先，将要更新的 Cookie 完全删除，并生成“原因”为“覆盖”的通知。之后，系统会使用更新后的值写入一个新的 Cookie，从而生成第二个包含“原因”为“露骨内容”的通知。

参数

  • callback

    功能

    callback 参数如下所示：

    (changeInfo: object)=>void

    • changeInfo

      对象

      • Cookie 发生变化的根本原因。

      • 饼干

        Cookie

        与已设置或移除的 Cookie 相关的信息。

      • 已删除

        boolean

        如果 Cookie 已被移除，则为 true。