Cookies

清单

要使用cookies API, 你必须在你的清单中声明"cookies"权限，以及任何你希望cookie可以访问的主机权限。例如：

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

范例

你可以在examples/api/cookies目录下找到一个使用cookies API的简单范例。对于其他的例子和查看源代码的帮助，参见 示例。

API说明：chrome.cookies

方法

get

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

获取一个cookie的信息。如果对于给定的URL有多个cookie存在，将返回对应于最长路径的cookie。对于路径长度相同的cookies，将返回最早创建的cookie。

参数

details
( Type array of object对象 )
用于识别所收到的cookie的详细信息。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string字符串 )
与所收到的cookie关联的URL。这个参数可以是一个完整的URL，这时候所有跟随在URL上的数据（比如查询字符串）将被忽略。如果清单文件中没有设置这个URL对应的主机权限，那么这个API调用会失败。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
name
( Type array of string字符串 )
收到的cookie名字。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
storeId
( optional Type array of string可选，字符串 )
cookie的存储id，用于从中检索cookie。默认情况下，当前执行上下文的cookie存储将被使用。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( Type array of function 函数 )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

回调函数

如果指定了回调参数，它应该指定一个如下所示函数：

If you specify the callback parameter, it should specify a function that looks like this: 

function(Cookie cookie) {...};
cookie
( optional Cookie array of paramType )
（可选，Cookie）
包含cookie的详细信息。如果没找到cookie，该参数为null。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

getAll

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

从一个cookie存储获取与给定信息匹配的所有cookies。所获取cookies将按照最长路径优先排序。当多个cookies有相同长度路径，最早创建的cookie在前面。

参数

details
( Type array of object )
对cookies进行筛选的信息。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( optional Type array of string可选，字符串 )
限定只查找与给定URL匹配的cookies。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
name
( optional Type array of string可选，字符串 )
根据名称过滤cookies。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
domain
( optional Type array of string可选，字符串 )
限定只查找与给定域名或者子域名匹配的cookies。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
path
( optional Type array of string可选，字符串 )
限定只查找与给定路径完全一致的cookies。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
secure
( optional Type array of boolean可选，Boolean类型 )
根据cookie的Secure属性进行筛选。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
session
( optional Type array of boolean可选，Boolean类型 )
根据cookie的生命周期是会话的还是持久的进行过滤。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
storeId
( optional Type array of string可选，字符串 )
cookie的存储id，用于从中检索cookie。默认情况下，当前执行上下文的cookie存储将被使用。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

回调函数

如果指定了回调参数，它应该指定一个如下所示函数：

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of Cookie cookies) {...};
cookies
( Type array of Cookie array of paramType paramType 可选，cookie列表)
所有与给定cookie信息匹配、存在并未过期的cookie列表。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

getAllCookieStores

void chrome.cookies.getAllCookieStores(, function callback)

列举所有存在的cookie存储。

参数

callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

回调函数

如果指定了回调参数，它应该指定一个如下所示函数：

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of CookieStore cookieStores) {...};
cookieStores
( Type array of CookieStore 可选，cookie存储列表 array of paramType paramType )
所有存在的cookie存储。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

remove

void chrome.cookies.remove(, object details)

根据名称删除cookie。

参数

details
( Type array of object )
用于鉴定待删除cookie的信息。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
与所收到的cookie关联的URL。如果清单文件中没有设置这个URL对应的主机权限，那么这个API调用会失败。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
name
( Type array of string )
待删除cookie的名称。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
storeId
( optional Type array of string )
cookie的存储id，用于从中检索cookie。默认情况下，当前执行上下文的cookie存储将被使用。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

回调函数

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

set

void chrome.cookies.set(, object details)

用给定数据设置一个cookie。如果相同的cookie存在，它们可能会被覆盖。

参数

details
( Type array of object )
待设置cookie的详细信息。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
url
( Type array of string )
与待设置cookie相关的URL。该值影响所创建cookie的默认域名与路径值。如果清单文件中没有设置这个URL对应的主机权限，那么这个API调用会失败。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
name
( optional Type array of string )
cookie名称，默认为空值。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
value
( optional Type array of string )
cookie的值，默认为空值。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
domain
( optional Type array of string )
cookie的域名。如果未指定，则该cookie是host-only cookie。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
path
( optional Type array of string )
cookie的路径。默认是url参数的路径部分。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
secure
( optional Type array of boolean )
是否cookie标记为保密。默认为false。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
httpOnly
( optional Type array of boolean )
是否cookie被标记为HttpOnly。默认为false。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
expirationDate
( optional Type array of number )
cookie的过期时间，用从UNIX epoch开始计的秒数表示。如果未指定，该cookie是一个会话cookie。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
storeId
( optional Type array of string )
用于保存该cookie的存储id。默认情况下，当前执行上下文的cookie存储将被使用。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

事件

onChanged

chrome.cookies.onChanged.addListener(function(object changeInfo) {...});

当一个cookie被设置或者删除时候触发。

参数

changeInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
removed
( Type array of boolean )
True表示一个cookie被删除。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
cookie
( Cookie array of paramType )
被设置或者删除的cookie的信息。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

类型

Cookie

paramName
( Type array of object )
表示一个HTTP cookie的信息。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
name
( Type array of string )
cookie名称。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
value
( Type array of string )
cookie值。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
domain
( Type array of string )
cookie的域名。(例如 "www.google.com", "example.com").
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
hostOnly
( Type array of boolean )
True表示cookie是一个host-only cookie (例如，一个检索的主机必须与cookie的域名完全一致）。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
path
( Type array of string )
cookie的路径。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
secure
( Type array of boolean )
True表示cookie被标记为保密。(例如，它的有效范围被限制于加密频道，最典型是HTTPS).
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
httpOnly
( Type array of boolean )
True表示cookie被标记为HttpOnly (例如cookie在客户端的脚本无法访问)。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
session
( Type array of boolean )
True表示cookie是线程cookie，与有过期时间的持久cookie相对应。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
expirationDate
( optional Type array of number )
cookie的过期时间，用从UNIX epoch（00:00:00 UTC on 1 January 1970）开始计的秒数表示。会话cookie没有该属性。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
storeId
( Type array of string )
包含该cookie的存储id，可通过getAllCookieStores()获取。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

CookieStore

paramName
( Type array of object )
表示浏览器中的cookie存储。那些隐藏模式窗体使用与非隐藏窗体不同的一个独立cookie存储。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
id
( Type array of string )
cookie存储的唯一id。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
tabIds
( Type array of Type array of integer paramType )
共享该cookie存储的浏览器标签集合的id列表。
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.