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
代表一个 HTTP Cookie 的有关信息。
-
name
(
string
)
-
Cookie 的名称。
-
value
(
string
)
-
Cookie 的值。
-
domain
(
string
)
-
Cookie 的域名（例如 “www.google.com”、“example.com”）。
-
hostOnly
(
boolean
)
-
如果 Cookie 仅用于指定主机则为 true（即请求的主机必须精确匹配 Cookie 的域名）。
-
path
(
string
)
-
Cookie 的路径。
-
secure
(
boolean
)
-
如果 Cookie 被标记为安全的则为 true（即它的范围限定在以 HTTPS 为典型的安全通道内）。
-
httpOnly
(
boolean
)
-
如果 Cookie 被标记为仅用于 HTTP 则为 true（即客户端脚本不能访问该 Cookie）。
-
session
(
boolean
)
-
如果是会话 Cookie 则为 true，与之相对，如果是具有过期日期的持久 Cookie 则为 false。
-
expirationDate
(
optional
double
)
-
Cookie 的过期日期，表示为自从 UNIX 纪元（1970 年 1 月 1 日午夜）开始所经过的秒数。对于会话 Cookie 省略。
-
storeId
(
string
)
-
包含此 Cookie 的 Cookie 存储区标识符，与 getAllCookieStores() 返回的一致。
CookieStore
代表浏览器中的一个 Cookie 存储区。例如隐身窗口使用与非隐身窗口不同的单独的 Cookie 存储区。
-
id
(
string
)
-
Cookie 存储区的标识符。
-
tabIds
(
array of integer
)
-
共享这一 Cookie 存储区的所有浏览器标签页的标识符。
方法
get
chrome.cookies.get(object details, function callback)
获得单个 Cookie 的有关信息。如果给定的 URL 具有多个名称相同的 Cookie，将返回路径最长的一个。如果路径长度相同，将返回创建时间最早的一个。
参数
-
details
(
object
)
-
需要获得的Cookie详情。
-
属性
-
url
(
string
)
-
与需要获取的 Cookie 相关联的 URL。该参数可以是一个完整的 URL，这种情况下 URL 路径后的任何数据（例如查询字符串）将被忽略。如果该 URL 的主机权限没有在清单文件中指定，该 API 将会失败。
-
name
(
string
)
-
需要获取的 Cookie 的名称。
-
storeId
(
optional
string
)
-
需要搜索的 Cookie 存储区的标识符。默认情况下，将使用当前执行环境的 Cookie 存储区。
callback 参数应该指定一个如下形式的函数：
function(Cookie cookie) {...};
-
cookie
(
optional
Cookie
)
-
有关 Cookie 的详情。如果没有找到，则该参数为 null。
getAll
chrome.cookies.getAll(object details, function callback)
返回一个 Cookie 存储区中符合给定条件的所有 Cookie。返回的 Cookie 将按照路径长度从大到小排序，如果多个 Cookie 的路径长度相等，则创建时间最早的排在最前面。
参数
-
details
(
object
)
-
用于筛选出要想获取的 Cookie 的信息。
-
属性
-
url
(
optional
string
)
-
将返回结果限制为匹配给定 URL 的 Cookie。
-
name
(
optional
string
)
-
通过名称筛选 Cookie。
-
domain
(
optional
string
)
-
将返回结果限制为匹配指定域名或者是指定域名的子域名的 Cookie。
-
path
(
optional
string
)
-
将返回结果限制为路径完全匹配该属性的 Cookie。
-
secure
(
optional
boolean
)
-
根据 Secure（安全）属性筛选 Cookie。
-
session
(
optional
boolean
)
-
筛选出会话或持久 Cookie。
-
storeId
(
optional
string
)
-
指定从哪一个存储区获取 Cookie。如果省略该属性，则使用当前执行环境的 Cookie 存储区。
callback 参数应该指定一个如下形式的函数：
function(array of Cookie cookies) {...};
-
cookies
(
array of Cookie
)
-
存在、未过期并且匹配给定信息的所有 Cookie。
set
chrome.cookies.set(object details, function callback)
用给定的数据设置 Cookie，如果同样的 Cookie 已存在则会覆盖。
参数
-
details
(
object
)
-
有关要设置的 Cookie 的详情。
-
属性
-
url
(
string
)
-
与要设置的 Cookie 相关联的请求 URI，它的值会影响到创建的 Cookie 的默认域名和路径。如果这一 URL 的主机权限没有在清单文件中指定，则这一API调用会失败。
-
name
(
optional
string
)
-
Cookie 的名称，如果省略的话默认为空。
-
value
(
optional
string
)
-
Cookie 的值，如果省略的话默认为空。
-
domain
(
optional
string
)
-
Cookie 的域名。如果省略的话该 Cookie 仅适用于 URL 中指定的主机。
-
path
(
optional
string
)
-
Cookie 的路径，默认为 url 参数的路径部分。
-
secure
(
optional
boolean
)
-
该 Cookie 是否应该标记为 Secure（安全的），默认为 false。
-
httpOnly
(
optional
boolean
)
-
该 Cookie 是否应该标记为 HttpOnly（仅用于 HTTP），默认为 false。
-
expirationDate
(
optional
double
)
-
Cookie 的过期日期，以自从 UNIX 纪元（1970 年 1 月 1 日午夜）开始所经过的秒数表示。如果省略的话，该 Cookie 仅在会话中有效。
-
storeId
(
optional
string
)
-
要设置的 Cookie 存储区的唯一标识符。默认情况下，Cookie 在当前执行环境的 Cookie 存储区中设置。
-
callback
(
optional
function
)
-
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function(Cookie cookie) {...};
remove
chrome.cookies.remove(object details, function callback)
根据名称删除 Cookie。
参数
-
details
(
object
)
-
用于标识要删除的Cookie的信息。
-
属性
-
url
(
string
)
-
与 Cookie 相关联的 URL。如果该 URL 的主机权限没有在清单文件中指定，则这一 API 调用将会失败。
-
name
(
string
)
-
要想删除的 Cookie 名称。
-
storeId
(
optional
string
)
-
Cookie 存储区的标识符。如果未指定，则在当前执行环境的 Cookie 存储区中寻找 Cookie。
-
callback
(
optional
function
)
-
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function(object details) {...};
-
details
(
optional
object
)
-
包含已经删除的 Cookie 详情。如果由于任何原因删除操作失败，则该参数为 null，并设置 runtime.lastError。
-
属性
-
url
(
string
)
-
与以删除的 Cookie 相关联的 URL。
-
name
(
string
)
-
已删除的 Cookie 名称。
-
storeId
(
string
)
-
已删除的 Cookie 来自的存储区。
getAllCookieStores
chrome.cookies.getAllCookieStores(function callback)
列举所有存在的 Cookie 存储区。
参数
callback 参数应该指定一个如下形式的函数：
function(array of CookieStore cookieStores) {...};
-
cookieStores
(
array of CookieStore
)
-
所有存在的 Cookie 存储区。
事件
onChanged
当 Cookie 设置或删除时产生。注意更新 Cookie 的属性为特殊情况，实现为两步的过程：首先将要更新的 Cookie 完全删除，产生 cause 属性为 "overwrite"（覆盖）的通知；然后，新的 Cookie 用更新后的值写入，产生 cause 属性为 "explicit" 的第二个通知。
addListener
chrome.cookies.onChanged.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(object changeInfo) {...};
-
changeInfo
(
object
)
-
-
属性
-
removed
(
boolean
)
-
如果是删除 Cookie 则为 true。
-
cause
(
enum of "evicted", "expired", "explicit", "expired_overwrite", or "overwrite"
)
-
Cookie 更改的原因。
如果是添加 Cookie，或者通过显式调用 remove 方法删除，则为 "explicit"。
如果 Cookie 由于过期被自动删除，则为 "expired_overwrite"。如果 Cookie 由于垃圾收集自动删除，则为 "evicted"。
如果 Cookie 由于 set 方法的调用被覆盖而自动删除，则为 "overwrite"。
您应该根据这一参数作出相应的回应。
chrome