chrome.cookies

描述 使用 chrome.cookies API 查询和修改 Cookie,并在 Cookie 更改时得到通知。
可用版本 从 Chrome 6 开始支持。
权限 "cookies"
主机权限

清单文件

要使用 Cookie API,您必须在清单文件中声明 "cookies" 权限,以及用于访问 Cookie 的主机权限。例如:

      {
        "name": "我的应用",
        ...
        "permissions": [
          "cookies",
          "*://*.google.com"
        ],
        ...
      }
      

摘要

类型
Cookie
CookieStore
方法
get chrome.cookies.get(object details, function callback)
getAll chrome.cookies.getAll(object details, function callback)
set chrome.cookies.set(object details, function callback)
getAllCookieStores chrome.cookies.getAllCookieStores(function callback)
事件
onChanged

类型

代表一个 HTTP Cookie 的有关信息。
属性

CookieStore

代表浏览器中的一个 Cookie 存储区。例如隐身窗口使用与非隐身窗口不同的单独的 Cookie 存储区。
属性
string id

Cookie 存储区的标识符。

array of integer tabIds

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

方法

get

chrome.cookies.get(object details, function callback)

获得单个 Cookie 的有关信息。如果给定的 URL 具有多个名称相同的 Cookie,将返回路径最长的一个。如果路径长度相同,将返回创建时间最早的一个。

参数
object details

需要获得的Cookie详情。

string url

与需要获取的 Cookie 相关联的 URL。该参数可以是一个完整的 URL,这种情况下 URL 路径后的任何数据(例如查询字符串)将被忽略。如果该 URL 的主机权限没有在清单文件中指定,该 API 将会失败。

string name

需要获取的 Cookie 的名称。

string (可选)
storeId

需要搜索的 Cookie 存储区的标识符。默认情况下,将使用当前执行环境的 Cookie 存储区。

function callback

callback 参数应该是一个如下形式的函数:

function( Cookie cookie) {...};

getAll

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

返回一个 Cookie 存储区中符合给定条件的所有 Cookie。返回的 Cookie 将按照路径长度从大到小排序,如果多个 Cookie 的路径长度相等,则创建时间最早的排在最前面。

参数
object details

用于筛选出要想获取的 Cookie 的信息。

string (可选)
url

将返回结果限制为匹配给定 URL 的 Cookie。

string (可选)
name

通过名称筛选 Cookie。

string (可选)
domain

将返回结果限制为匹配指定域名或者是指定域名的子域名的 Cookie。

string (可选)
path

将返回结果限制为路径完全匹配该属性的 Cookie。

boolean (可选)
secure

根据 Secure(安全)属性筛选 Cookie。

boolean (可选)
session

筛选出会话或持久 Cookie。

string (可选)
storeId

指定从哪一个存储区获取 Cookie。如果省略该属性,则使用当前执行环境的 Cookie 存储区。

function callback

callback 参数应该是一个如下形式的函数:

function(array of Cookie cookies) {...};
array of Cookie cookies

存在、未过期并且匹配给定信息的所有 Cookie。

set

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

用给定的数据设置 Cookie,如果同样的 Cookie 已存在则会覆盖。

参数
object details

有关要设置的 Cookie 的详情。

string url

与要设置的 Cookie 相关联的请求 URI,它的值会影响到创建的 Cookie 的默认域名和路径。如果这一 URL 的主机权限没有在清单文件中指定,则这一API调用会失败。

string (可选)
name

Cookie 的名称,如果省略的话默认为空。

string (可选)
value

Cookie 的值,如果省略的话默认为空。

string (可选)
domain

Cookie 的域名。如果省略的话该 Cookie 仅适用于 URL 中指定的主机。

string (可选)
path

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

boolean (可选)
secure

该 Cookie 是否应该标记为 Secure(安全的),默认为 false。

boolean (可选)
httpOnly

该 Cookie 是否应该标记为 HttpOnly(仅用于 HTTP),默认为 false。

double (可选)
expirationDate

Cookie 的过期日期,以自从 UNIX 纪元(1970 年 1 月 1 日午夜)开始所经过的秒数表示。如果省略的话,该 Cookie 仅在会话中有效。

string (可选)
storeId

要设置的 Cookie 存储区的唯一标识符。默认情况下,Cookie 在当前执行环境的 Cookie 存储区中设置。

function (可选)
callback

如果您指定了 callback 参数,它应该是一个如下形式的函数:

function( Cookie cookie) {...};
function (可选)
callback

如果您指定了 callback 参数,它应该是一个如下形式的函数:

function(object details) {...};
object (可选)
details

包含已经删除的 Cookie 详情。如果由于任何原因删除操作失败,则该参数为 null,并设置 runtime.lastError

string url

与以删除的 Cookie 相关联的 URL。

string name

已删除的 Cookie 名称。

string storeId

已删除的 Cookie 来自的存储区。

getAllCookieStores

chrome.cookies.getAllCookieStores(function callback)

列举所有存在的 Cookie 存储区。

参数
function callback

callback 参数应该是一个如下形式的函数:

function(array of CookieStore cookieStores) {...};
array of CookieStore cookieStores

所有存在的 Cookie 存储区。

事件

onChanged

当 Cookie 设置或删除时产生。注意更新 Cookie 的属性为特殊情况,实现为两步的过程:首先将要更新的 Cookie 完全删除,产生 cause 属性为 "overwrite"(覆盖)的通知;然后,新的 Cookie 用更新后的值写入,产生 cause 属性为 "explicit" 的第二个通知。

addListener

chrome.cookies.onChanged.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function(object changeInfo) {...};
object changeInfo
boolean removed

如果是删除 Cookie 则为 true。

enum of "evicted", "expired", "explicit", "expired_overwrite", or "overwrite" cause

从 Chrome 12 开始支持。

Cookie 更改的原因。
如果是添加 Cookie 则为 "explicit"。
如果 Cookie 由于过期被自动删除,则为 "expired_overwrite"。如果 Cookie 由于垃圾收集自动删除,则为 "evicted"。
如果 Cookie 由于 cookies.set 方法的调用被覆盖而自动删除,则为 "overwrite"。
您应该根据这一参数作出相应的回应。