chrome.cookies

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

清单文件

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

      {
        "name": "我的扩展程序",
        ...
        "permissions": [
          "cookies",
          "*://*.google.com"
        ],
        ...
      }

例子

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

摘要

类型
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)`
remove − `chrome.cookies.remove(object details, function callback)`
getAllCookieStores − `chrome.cookies.getAllCookieStores(function callback)`
事件
onChanged

类型

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

属性
string	name	Cookie 的名称。
string	value	Cookie 的值。
string	domain	Cookie 的域名（例如 “www.google.com”、“example.com”）。
boolean	hostOnly	如果 Cookie 仅用于指定主机则为 true（即请求的主机必须精确匹配 Cookie 的域名）。
string	path	Cookie 的路径。
boolean	secure	如果 Cookie 被标记为安全的则为 true（即它的范围限定在以 HTTPS 为典型的安全通道内）。
boolean	httpOnly	如果 Cookie 被标记为仅用于 HTTP 则为 true（即客户端脚本不能访问该 Cookie）。
boolean	session	如果是会话 Cookie 则为 true，与之相对，如果是具有过期日期的持久 Cookie 则为 false。
double	（可选） expirationDate	Cookie 的过期日期，表示为自从 UNIX 纪元（1970 年 1 月 1 日午夜）开始所经过的秒数。对于会话 Cookie 省略。
string	storeId	包含此 Cookie 的 Cookie 存储区标识符，与 getAllCookieStores() 返回的一致。

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

存在、未过期并且匹配给定信息的所有 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) {...};

remove


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

根据名称删除 Cookie。

参数

object

details

用于标识要删除的Cookie的信息。

string	url	与 Cookie 相关联的 URL。如果该 URL 的主机权限没有在清单文件中指定，则这一 API 调用将会失败。
string	name	要想删除的 Cookie 名称。
string	（可选） storeId	Cookie 存储区的标识符。如果未指定，则在当前执行环境的 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。

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

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

cause

从 Chrome 12 开始支持。

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

示例扩展程序

Cookie API Test Extension – Testing Cookie API