chrome.cookies

说明

使用 chrome.cookies API 查询和修改 Cookie，并在 Cookie 发生变化时接收通知。

权限

cookies

如需使用 Cookie API，请在清单中声明 "cookies" 权限，并为您要访问 Cookie 的所有主机声明主机权限。例如：

{
  "name": "My extension",
  ...
  "host_permissions": [
    "*://*.google.com/"
  ],
  "permissions": [
    "cookies"
  ],
  ...
}

分区

通过分区 Cookie，网站可以标记某些 Cookie 应以顶级框架的来源作为键。例如，这意味着，如果网站 A 使用 iframe 嵌入到网站 B 和网站 C 中，则来自 A 的分区 Cookie 的嵌入版本在 B 和 C 中可能具有不同的值。

默认情况下，所有 API 方法都针对未分区的 Cookie 进行操作。partitionKey 属性可用于替换此行为。

如需详细了解分区对扩展程序的一般影响，请参阅存储空间和 Cookie。

示例

您可以在 examples/api/cookies 目录中找到使用 Cookie API 的简单示例。如需查看其他示例以及有关查看源代码的帮助，请参阅示例。

类型

Cookie

表示 HTTP Cookie 的相关信息。

属性

• 网域

  字符串

  Cookie 的网域（例如“www.google.com”“example.com”）。

• expirationDate

  number 可选

  Cookie 的过期日期，以自 UNIX 纪年以来的秒数表示。不适用于会话 Cookie。

• hostOnly

  布尔值

  如果 Cookie 是主机专用 Cookie（即请求的主机必须与 Cookie 的网域完全匹配，则为 true）。

• httpOnly

  布尔值

  如果 Cookie 被标记为 HttpOnly（即客户端脚本无法访问该 Cookie），则为 true。

• name

  字符串

  Cookie 的名称。

• partitionKey

  CookiePartitionKey（可选）

  Chrome 119 及更高版本

  用于读取或修改具有“Partitioned”属性的 Cookie 的分区键。

• 路径

  字符串

  Cookie 的路径。

• sameSite

  SameSiteStatus

  Chrome 51 及更高版本

  Cookie 的同网站状态（即 Cookie 是否随跨网站请求一起发送）。

• 安全

  布尔值

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

• 会话

  布尔值

  如果 Cookie 是会话 Cookie（而非具有有效期的永久 Cookie），则为 true。

• storeId

  字符串

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

• 值

  字符串

  Cookie 的值。

CookieDetails

Chrome 88 及更高版本

用于标识 Cookie 的详细信息。

属性

• name

  字符串

  要访问的 Cookie 的名称。

• partitionKey

  CookiePartitionKey（可选）

  Chrome 119 及更高版本

  用于读取或修改具有“Partitioned”属性的 Cookie 的分区键。

• storeId

  字符串（选填）

  用于查找 Cookie 的 Cookie 存储区的 ID。默认情况下，系统会使用当前执行上下文的 Cookie 存储区。

• 网址

  字符串

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

CookiePartitionKey

Chrome 119 及更高版本

表示分区 Cookie 的分区键。

属性

• hasCrossSiteAncestor

  布尔值（可选）

  Chrome 130 及更高版本

  指示 Cookie 是否是在跨跨网站环境中设置。这样可以防止嵌入在跨网站环境中的顶级网站访问顶级网站在同网站环境中设置的 Cookie。

• topLevelSite

  字符串（可选）

  分区 Cookie 可用的顶级网站。

CookieStore

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

属性

• id

  字符串

  Cookie 存储区的唯一标识符。

• tabIds

  number[]

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

FrameDetails

待处理

用于识别帧的详细信息。

属性

• documentId

  字符串（可选）

  文档的唯一标识符。如果提供了 frameId 和/或 tabId，系统会对其进行验证，以确保其与通过提供的文档 ID 找到的文档相匹配。

• frameId

  number 可选

  标签页中框架的唯一标识符。

• tabId

  number 可选

  包含该帧的标签页的唯一标识符。

OnChangedCause

Chrome 44 及更高版本

导致 Cookie 发生更改的根本原因。如果是通过明确调用“chrome.cookies.remove”来插入或移除 Cookie，则“原因”将为“明确”。如果某个 Cookie 因过期而被自动移除，“原因”将为“已过期”。如果 Cookie 因被已过期的失效日期被覆盖而遭到移除，“cause”将设置为“expired_overwrite”。如果某个 Cookie 因垃圾回收而被自动移除，“原因”将被“驱逐”。如果 Cookie 因“set”调用覆盖它而被自动移除，则“cause”将为“覆盖”。相应地规划您的响应。

枚举

“evicted”

"expired"

"露骨内容"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 及更高版本

Cookie 的“SameSite”状态 (https://tools.ietf.org/html/draft-west-first-party-cookies)。“no_restriction”对应于设置为“SameSite=None”的 Cookie，“lax”对应于“SameSite=Lax”，而“strict”对应于“SameSite=Strict”。“未指定”对应于未设置 SameSite 属性的 Cookie。

枚举

"no_restriction"

"lax"

"strict"

"unspecified"

方法

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 | undefined>

  Chrome 88 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getAll()

prometido

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

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

参数

• 详细信息

  对象

  用于过滤要检索的 Cookie 的信息。

  • 网域

    字符串（选填）

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

  • name

    字符串（选填）

    按名称过滤 Cookie。

  • partitionKey

    CookiePartitionKey（可选）

    Chrome 119 及更高版本

    用于读取或修改具有“Partitioned”属性的 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，但提供了回调以确保向后兼容性。您不能在同一函数调用中同时使用这两种方法。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 的解析结果与传递给回调的类型相同。

getPartitionKey()

Promise 待处理

chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

所指帧的分区键。

参数

• 详细信息

  FrameDetails

• callback

  函数（可选）

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    包含有关已检索的分区键的详细信息。

    • partitionKey

      CookiePartitionKey

      分区键，用于读取或修改具有“分区”属性的 Cookie。

返回

• Promise<object>

  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

      字符串

      已移除的 Cookie 的名称。

    • partitionKey

      CookiePartitionKey（可选）

      Chrome 119 及更高版本

      用于读取或修改具有“Partitioned”属性的 Cookie 的分区键。

    • storeId

      字符串

      移除 Cookie 的 Cookie 存储区的 ID。

    • 网址

      字符串

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

返回

• Promise<object | undefined>

  Chrome 88 及更高版本

  Manifest V3 及更高版本支持 Promise，但提供了回调以确保向后兼容性。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

set()

prometido

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

使用给定 Cookie 数据设置 Cookie；可能会覆盖等效 Cookie（如果存在）。

参数

• 详细信息

  对象

  有关要设置的 Cookie 的详细信息。

  • 网域

    字符串（可选）

    Cookie 的网域。如果省略，Cookie 将成为主机专用 Cookie。

  • expirationDate

    number 可选

    Cookie 的过期日期，以自 UNIX 纪年以来的秒数表示。如果省略，Cookie 将成为会话 Cookie。

  • httpOnly

    布尔值（可选）

    是否应将 Cookie 标记为 HttpOnly。默认值为 false。

  • name

    字符串（选填）

    Cookie 的名称。如果省略，则默认为空。

  • partitionKey

    CookiePartitionKey（可选）

    Chrome 119 及更高版本

    用于读取或修改具有“Partitioned”属性的 Cookie 的分区键。

  • 路径

    字符串（选填）

    Cookie 的路径。默认值为网址参数的路径部分。

  • sameSite

    SameSiteStatus（可选）

    Chrome 51 及更高版本

    Cookie 的同网站状态。默认为“未指定”，即如果省略，则在设置 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 | undefined>

  Chrome 88 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

事件

onChanged

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

在设置或移除 Cookie 时触发。请注意，作为一种特殊情况，更新 Cookie 的属性是通过两步流程实现的：系统会先完全移除要更新的 Cookie，然后生成一个“原因”为“覆盖”的通知。之后，系统会使用更新后的值写入新的 Cookie，并生成第二个“cause”为“explicit”的通知。

参数

• callback

  函数

  callback 参数如下所示：

  (changeInfo: object) => void

  • changeInfo

    对象

    • cause

      OnChangedCause

      导致 Cookie 发生更改的根本原因。

    • 饼干

      Cookie

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

    • 已移除

      布尔值

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