chrome.cookies

Description

使用 chrome.cookies API 查询和修改 cookie，并在更改时收到通知。

Permissions

cookies

# Manifest

要使用 cookie API，您必须在清单中声明“cookies”权限，以及您要访问其 cookie 的任何主机的主机权限。例如：

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

# Examples

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

Summary

Types

Cookie

表示有关 HTTP cookie 的信息。

PROPERTIES

  • domain

    string

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

  • expirationDate

    number optional

    cookie 的到期日期，表示自 UNIX 纪元以来的秒数。不为会话 cookie 提供。

  • hostOnly

    boolean

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

  • httpOnly

    boolean

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

  • name

    string

    cookie 的名称。

  • path

    string

    cookie 的路径。

  • sameSite

    SameSiteStatus

    Chrome 51+

    cookie 的同站点状态（即 cookie 是否与跨站点请求一起发送）。

  • secure

    boolean

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

  • session

    boolean

    如果 cookie 是会话 cookie，而不是具有过期日期的持久 cookie，则为真。

  • storeId

    string

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

  • value

    string

    cookie 的值。

CookieDetails

Chrome 88+

用于识别 cookie 的详细信息。

PROPERTIES

  • name

    string

    要访问的 cookie 的名称。

  • storeId

    string optional

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

  • url

    string

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

CookieStore

表示浏览器中的 cookie 存储。例如，隐身模式窗口使用与非隐身窗口不同的 cookie 存储。

PROPERTIES

  • id

    string

    cookie 存储的唯一标识符。

  • tabIds

    number[]

    共享此 cookie 存储的所有浏览器选项卡的标识符。

OnChangedCause

Chrome 44+

cookie 更改背后的根本原因。如果通过显式调用“chrome.cookies.remove”插入或删除 cookie，则“原因(cause)”将是“显式(explicit)”。如果 cookie 因过期而被自动删除，“原因(cause)”将被“过期(expired)”。如果 cookie 因被已经过期的过期日期覆盖而被删除，则“原因(cause)”将设置为“expired_overwrite”。如果由于垃圾收集而自动删除了 cookie，则“原因(cause)”将被“驱逐(evicted)”。如果 cookie 由于覆盖它的“set”调用而被自动删除，则“cause”将是“overwrite”。相应地计划你的反应。

TYPE

"evicted", "expired", "explicit", "expired_overwrite", or "overwrite"

SameSiteStatus

Chrome 51+

cookie 的“SameSite”状态 (https://tools.ietf.org/html/draft-west-first-party-cookies)。 “no_restriction”对应于设置为“SameSite=None”、“lax”为“SameSite=Lax”、“strict”为“SameSite=Strict”的cookie。'unspecified' 对应于没有 SameSite 属性的 cookie 集。

TYPE

"no_restriction", "lax", "strict", or "unspecified"

Methods

get

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

Promise

检索有关单个 cookie 的信息。如果给定 URL 存在多个同名 cookie，则返回路径最长的那个。对于路径长度相同的cookie，将返回创建时间最早的cookie。

PARAMETERS

  • details

    CookieDetails

  • callback

    function optional

    The callback parameter looks like:

    (cookie?: Cookie) => void

    • cookie

      Cookie optional

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

RETURNS

  • Promise<Cookie | undefined>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

getAll 

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

Promise

从单个 cookie 存储中检索与给定信息匹配的所有 cookie。返回的 cookie 将被排序，路径最长的 cookie 排在最前面。如果多个cookies的路径长度相同，则创建时间最早的cookies优先。

PARAMETERS

  • details

    object

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

    • domain

      string optional

      将检索到的 cookie 限制为域匹配或者是该域的子域的 cookie。

    • name

      string optional

      按名称过滤 cookie。

    • path

      string optional

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

    • secure

      boolean optional

      按 cookie 的 Secure 属性过滤 cookie。

    • session

      boolean optional

      过滤掉会话与持久性 cookie。

    • storeId

      string optional

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

    • url

      string optional

      将检索到的 cookie 限制为与给定 URL 匹配的 cookie。

  • callback

    function optional

    The callback parameter looks like:

    (cookies: Cookie[]) => void

    • cookies

      Cookie[]

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

RETURNS

  • Promise<Cookie[]>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

getAllCookieStores 

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

Promise

列出所有现有的 cookie 存储

PARAMETERS

  • callback

    function optional

    The callback parameter looks like:

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      所有现有的 cookie 存储。

RETURNS

  • Promise<CookieStore[]>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

remove 

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

Promise

按名称删除 cookie。

PARAMETERS

  • details

    CookieDetails

  • callback

    function optional

    The callback parameter looks like:

    (details?: object) => void

    • details

      object optional

      包含有关已删除 cookie 的详细信息。如果由于任何原因删除失败，这将是“null”，并且 runtime.lastError 将被设置。

      • name

        string

        已删除的 cookie 的名称。

      • storeId

        string

        从中删除 cookie 的 cookie 存储的 ID。

      • url

        string

        与已删除 cookie 关联的 URL。

RETURNS

  • Promise<object | undefined>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

set 

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

Promise

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

PARAMETERS

  • details

    object

    有关正在设置的 cookie 的详细信息

    • domain

      string optional

      cookie 的域。如果省略，cookie 将成为仅主机 cookie。

    • expirationDate

      number optional

      cookie 的到期日期，表示自 UNIX 纪元以来的秒数。如果省略，cookie 将成为会话 cookie。

    • httpOnly

      boolean optional

      cookie 是否应标记为 HttpOnly。默认为假。

    • name

      string optional

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

    • path

      string optional

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

    • sameSite

      SameSiteStatus optional

      Chrome 51+

      cookie 的同站点(same-site)状态。默认为“未指定unspecified”，即，如果省略，则设置 cookie 时不指定 SameSite 属性。

    • secure

      boolean optional

      cookie 是否应标记为安全。默认为假。

    • storeId

      string optional

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

    • url

      string

      与 cookie 设置相关联的请求 URI。此值可能会影响创建的 cookie 的默认域和路径值。如果未在清单文件中指定此 URL 的主机权限，则 API 调用将失败。

    • value

      string optional

      cookie 的值。如果省略，则默认为空。

  • callback

    function optional

    The callback parameter looks like:

    (cookie?: Cookie) => void

    • cookie

      Cookie optional

      包含有关已设置的 cookie 的详细信息。如果由于任何原因设置失败，这将是“null”，并且 runtime.lastError 将被设置。

RETURNS

  • Promise<Cookie | undefined>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

Events

onChanged 

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

设置或删除 cookie 时触发。作为一种特殊情况，请注意，更新 cookie 的属性是通过两步过程实现的：首先将要更新的 cookie 完全删除，生成带有“覆盖(overwrite)”“原因(cause)”的通知。之后，用更新的值写入一个新的 cookie，生成带有“原因(cause)”“显式(explicit)”的第二个通知。

PARAMETERS

  • callback

    function

    The callback parameter looks like:

    (changeInfo: object) => void

    • changeInfo

      object

      • cause

        OnChangedCause

        cookie 更改背后的根本原因。

      • cookie

        Cookie

        有关设置或删除的 cookie 的信息。

      • removed

        boolean

        如果删除了 cookie，则为真。

By. 一粒技术服务

results matching ""

    No results matching ""