chrome.cookies

说明

使用 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 目录中。如需其他示例以及查看方面的帮助， 请参阅示例。

类型

表示有关 HTTP Cookie 的信息。

属性

  • 网域

    字符串

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

  • expirationDate

    编号（选填）

    Cookie 的有效期，以从 UNIX 纪元开始计算的秒数。不会为会话 Cookie 提供。

  • hostOnly

    布尔值

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

  • httpOnly

    布尔值

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

  • name

    字符串

    Cookie 的名称。

  • partitionKey

    CookiePartitionKey（可选）

    Chrome 119 及更高版本

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

  • 路径

    字符串

    Cookie 的路径。

  • sameSite

    SameSiteStatus

    Chrome 51 及更高版本

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

  • 安全

    布尔值

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

  • 会话

    布尔值

    如果 Cookie 是会话 Cookie，则此值为 true，与具有失效日期的永久 Cookie 相反。

  • storeId

    字符串

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

  • 值

    字符串

    Cookie 的值。

CookieDetails

Chrome 88 及更高版本

用于标识 Cookie 的详细信息。

属性

  • name

    字符串

    要访问的 Cookie 的名称。

  • partitionKey

    CookiePartitionKey（可选）

    Chrome 119 及更高版本

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

  • storeId

    字符串（可选）

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

  • 网址

    字符串

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

CookiePartitionKey

Chrome 119 及更高版本

表示分区 Cookie 的分区键。

属性

  • topLevelSite

    字符串（可选）

    提供分区 Cookie 的顶级网站。

CookieStore

表示浏览器中的 Cookie 存储。例如，隐身模式窗口会在非隐身窗口中使用单独的 Cookie 存储区。

属性

  • id

    字符串

    Cookie 存储区的唯一标识符。

  • tabIds

    数值 []

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

OnChangedCause

Chrome 44 及更高版本

Cookie 发生变化的根本原因。如果插入了 Cookie，或通过明确调用“chrome.cookies.remove”而删除了 Cookie，则“cause”都将是“露骨内容”。如果 Cookie 因过期而被自动移除，则“原因”将会“过期”。如果 Cookie 因被已过期的失效日期被覆盖而遭到移除，“原因”将设置为“expired_overwrite”。如果 Cookie 因垃圾回收而被自动移除，则“原因”将被“逐出”。如果 Cookie 因“已设置”而自动移除CANNOT TRANSLATE将被“覆盖”。制定相应的应对计划。

枚举

“逐出”

"expired"

"露骨内容"

"expired_overwrite"

“覆盖”

SameSiteStatus

Chrome 51 及更高版本

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

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

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

参数

  • 详细信息

    CookieDetails

  • callback

    函数（可选）

    callback 参数如下所示： 

    (cookie?: Cookie) => void

    • 饼干

      Cookie 可选

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

返回

  • Promise&lt;Cookie |未定义>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getAll()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

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

参数

  • 详细信息

    对象

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

    • 网域

      字符串（可选）

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

    • name

      字符串（可选）

      按名称过滤 Cookie。

    • partitionKey

      CookiePartitionKey（可选）

      Chrome 119 及更高版本

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

    • 路径

      字符串（可选）

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

    • 安全

      布尔值（可选）

      按 Secure 属性过滤 Cookie。

    • 会话

      布尔值（可选）

      过滤掉会话 Cookie 和永久 Cookie。

    • storeId

      字符串（可选）

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

    • 网址

      字符串（可选）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (cookies: Cookie[]) => void

    • Cookie

      Cookie[]

      符合指定 Cookie 信息的所有未过期的现有 Cookie。

返回

  • Promise&lt;Cookie[]&gt;

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getAllCookieStores()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      所有现有的 Cookie 存储区。

返回

  • Promise&lt;CookieStore[]&gt;

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

remove()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

按名称删除 Cookie。

参数

  • 详细信息

    CookieDetails

  • callback

    函数（可选）

    callback 参数如下所示： 

    (details?: object) => void

    • 详细信息

      对象（可选）

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

      • name

        字符串

        已移除的 Cookie 的名称。

      • partitionKey

        CookiePartitionKey（可选）

        Chrome 119 及更高版本

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

      • storeId

        字符串

        从中删除了相应 Cookie 的 Cookie 存储区的 ID。

      • 网址

        字符串

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

返回

  • Promise&lt;object |未定义>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

set()

<ph type="x-smartling-placeholder"></ph> 承诺 
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 及更高版本

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

    • 路径

      字符串（可选）

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

    • sameSite

      SameSiteStatus 可选

      Chrome 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&lt;Cookie |未定义>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

onChanged

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

在设置或移除 Cookie 时触发。请注意，一种特殊情况是，更新 Cookie 属性的过程分为两个步骤：首先彻底删除要更新的 Cookie，然后生成一条包含“原因”的通知，共“覆盖”，了解所有最新动态。之后，新的 Cookie 会写入更新后的值，从而生成第二条通知，其中显示“cause”“露骨内容”。

参数

  • callback

    函数

    callback 参数如下所示： 

    (changeInfo: object) => void

    • changeInfo

      对象

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

      • 饼干

        Cookie

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

      • 已移除

        布尔值

        如果移除了 Cookie，则为“true”。