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 的简单示例。如需查看其他示例以及有关查看源代码的帮助，请参阅示例。

类型

表示 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 被标记为“Secure”（即其范围仅限于安全渠道，通常为 HTTPS），则为 True。

  • session

    布尔值

    如果 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 存储区与非无痕窗口使用的 Cookie 存储区不同。

属性

  • id

    字符串

    Cookie 存储区的唯一标识符。

  • tabIds

    number[]

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

FrameDetails

Chrome 132 及更高版本

用于标识帧的详细信息。

属性

  • documentId

    字符串（选填）

    相应文档的唯一标识符。如果提供了 frameId 和/或 tabId，系统会验证它们是否与通过提供的文档 ID 找到的文档相匹配。

  • frameId

    number 可选

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

  • tabId

    number 可选

    包含框架的标签页的唯一标识符。

OnChangedCause

Chrome 44 及更高版本

Cookie 更改的根本原因。如果通过显式调用“chrome.cookies.remove”插入或移除了 Cookie，“cause”将为“explicit”。如果 Cookie 因过期而被自动移除，“原因”将为“已过期”。如果某个 Cookie 因被已过期的过期日期覆盖而遭到移除，“原因”将设置为“expired_overwrite”。如果 Cookie 因垃圾回收而自动移除，“原因”将为“逐出”。如果因“set”调用覆盖了某个 Cookie 而导致该 Cookie 被自动移除，“原因”将为“覆盖”。请相应地规划您的回答。

枚举

“逐出”

“expired”

“explicit”

"expired_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"

“宽松”

“strict”

“未指定”

方法

get()

Promise 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
): Promise<Cookie | undefined>

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

参数

  • 详细信息

    CookieDetails

  • callback

    函数 可选

    callback 参数如下所示： 

    (cookie?: Cookie) => void

    • 饼干

      Cookie 可选

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

返回

  • Promise<Cookie | undefined>

    Chrome 88 及更高版本

getAll()

Promise 
chrome.cookies.getAll(
  details: object,
  callback?: function,
): Promise<Cookie[]>

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

参数

  • 详细信息

    对象

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

    • 网域

      字符串（选填）

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

    • name

      字符串（选填）

      按名称过滤 Cookie。

    • partitionKey

      CookiePartitionKey 可选

      Chrome 119 及更高版本

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

    • 路径

      字符串（选填）

      将检索到的 Cookie 限制为路径与此字符串完全匹配的 Cookie。

    • 安全

      布尔值（可选）

      按 Secure 属性过滤 Cookie。

    • session

      布尔值（可选）

      过滤掉会话 Cookie 与永久性 Cookie。

    • storeId

      字符串（选填）

      要从中检索 Cookie 的 Cookie 存储区。如果省略，则使用当前执行上下文的 Cookie 存储区。

    • 网址

      字符串（选填）

      将检索到的 Cookie 限制为与指定网址匹配的 Cookie。

  • callback

    函数 可选

    callback 参数如下所示： 

    (cookies: Cookie[]) => void

    • Cookie

      Cookie[]

      与给定 Cookie 信息匹配的所有现有未过期 Cookie。

返回

  • Promise<Cookie[]>

    Chrome 88 及更高版本

getAllCookieStores()

Promise 
chrome.cookies.getAllCookieStores(
  callback?: function,
): Promise<CookieStore[]>

列出所有现有的 Cookie 存储区。

参数

  • callback

    函数 可选

    callback 参数如下所示： 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      所有现有的 Cookie 存储区。

返回

getPartitionKey()

Promise Chrome 132 及更高版本 
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
): Promise<object>

所指示帧的分区键。

参数

  • 详细信息

    FrameDetails

  • callback

    函数 可选

    callback 参数如下所示： 

    (details: object) => void

    • 详细信息

      对象

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

      • partitionKey

        CookiePartitionKey

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

返回

  • Promise<object>

remove()

Promise 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
): Promise<object | undefined>

按名称删除 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 及更高版本

set()

Promise 
chrome.cookies.set(
  details: object,
  callback?: function,
): Promise<Cookie | undefined>

使用给定的 Cookie 数据设置 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 的同网站状态。默认为“unspecified”，即如果省略，则设置 Cookie 时不指定 SameSite 属性。

    • 安全

      布尔值（可选）

      是否应将 Cookie 标记为“Secure”。默认值为 false。

    • storeId

      字符串（选填）

      要在其中设置 Cookie 的 Cookie 存储区的 ID。默认情况下，Cookie 会设置在当前执行上下文的 Cookie 存储区中。

    • 网址

      字符串

      要与 Cookie 设置相关联的 request-URI。此值可能会影响所创建 Cookie 的默认网域和路径值。如果未在清单文件中指定相应网址的主机权限，API 调用将会失败。

    • 值

      字符串（选填）

      相应 Cookie 的值。如果省略，则默认为空。

  • callback

    函数 可选

    callback 参数如下所示： 

    (cookie?: Cookie) => void

    • 饼干

      Cookie 可选

      包含有关已设置 Cookie 的详细信息。如果因任何原因而设置失败，此值将为“null”，并且会设置 runtime.lastError。

返回

  • Promise<Cookie | undefined>

    Chrome 88 及更高版本

事件

onChanged

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (changeInfo: object) => void

    • changeInfo

      对象

      • Cookie 更改的根本原因。

      • 饼干

        Cookie

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

      • 已移除

        布尔值

        如果已移除 Cookie，则为 True。