Cookies · Chrome 扩展开发文档

# Cookies ## 内容 1. [清单](#manifest) 1. <a>h3Name</a> 2. [范例](#examples) 1. <a>h3Name</a> 3. [API 参考: chrome.cookies](#apiReference) 1. [属性](#properties) 1. [propertyName](#property-anchor) 2. [方法](#methods) 1. [get](#method-get) 2. [getAll](#method-getAll) 3. [getAllCookieStores](#method-getAllCookieStores) 4. [remove](#method-remove) 5. [set](#method-set) 3. [事件](#events) 1. [onChanged](#event-onChanged) 4. [类型](#types) 1. [Cookie](#type-Cookie) 2. [CookieStore](#type-CookieStore) For information on how to use experimental APIs, see the [chrome.experimental.* APIs](experimental.html) page. Cookies ## 清单要使用cookies API, 你必须在你的清单中声明"cookies"权限，以及任何你希望cookie可以访问的主机权限。例如： ``` { "name": "My extension", ... **"permissions": [ "cookies", "*://*.google.com" ]**, ... } ``` ## 范例你可以在[examples/api/cookies](http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/cookies/)目录下找到一个使用cookies API的简单范例。对于其他的例子和查看源代码的帮助，参见 [示例](samples.html)。 ## API 参考: chrome.cookies ### 属性 <a></a> #### getLastError chrome.extensionlastError ### 方法 #### get void chrome.cookies.get(, object `details`, function `callback`) Undocumented. 获取一个cookie的信息。如果对于给定的URL有多个cookie存在，将返回对应于最长路径的cookie。对于路径长度相同的cookies，将返回最早创建的cookie。 #### 参数 `details`_( optional enumerated Type array of object对象 )_ Undocumented. 用于识别所收到的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `url`_( optional enumerated Type array of string字符串 )_ Undocumented. 与所收到的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `name`_( optional enumerated Type array of string字符串 )_ Undocumented. 收到的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `storeId`_( optional enumerated Type array of string可选，字符串 )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `callback`_( optional enumerated 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](manifest.html#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 enumerated [Cookie](cookies.html#type-Cookie) array of paramType )_（可选，Cookie） Undocumented. 包含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](manifest.html#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](manifest.html#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`) Undocumented. 从一个cookie存储获取与给定信息匹配的所有cookies。所获取cookies将按照最长路径优先排序。当多个cookies有相同长度路径，最早创建的cookie在前面。 #### 参数 `details`_( optional enumerated Type array of object )_ Undocumented. 对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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `url`_( optional enumerated Type array of string可选，字符串 )_ Undocumented. 限定只查找与给定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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `name`_( optional enumerated Type array of string可选，字符串 )_ Undocumented. 根据名称过滤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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `domain`_( optional enumerated Type array of string可选，字符串 )_ Undocumented. 限定只查找与给定域名或者子域名匹配的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `path`_( optional enumerated Type array of string可选，字符串 )_ Undocumented. 限定只查找与给定路径完全一致的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `secure`_( optional enumerated Type array of boolean可选，Boolean类型 )_ Undocumented. 根据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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `session`_( optional enumerated Type array of boolean可选，Boolean类型 )_ Undocumented. 根据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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `storeId`_( optional enumerated Type array of string可选，字符串 )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `callback`_( optional enumerated 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](manifest.html#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`_( optional enumerated Type array of [Cookie](cookies.html#type-Cookie) array of paramType paramType _可选，[cookie](cookies.html#type-Cookie)列表_)_ Undocumented. 所有与给定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](manifest.html#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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### getAllCookieStores void chrome.cookies.getAllCookieStores(, function `callback`) Undocumented. 列举所有存在的cookie存储。 #### 参数 `callback`_( optional enumerated 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](manifest.html#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`_( optional enumerated Type array of [CookieStore](cookies.html#type-CookieStore) _可选，[cookie存储](cookies.html#type-CookieStore)列表_ array of paramType paramType )_ Undocumented. 所有存在的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](manifest.html#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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### remove void chrome.cookies.remove(, object `details`) Undocumented. 根据名称删除cookie。 #### 参数 `details`_( optional enumerated Type array of object )_ Undocumented. 用于鉴定待删除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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `url`_( optional enumerated Type array of string )_ Undocumented. 与所收到的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `name`_( optional enumerated Type array of string )_ Undocumented. 待删除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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `storeId`_( optional enumerated Type array of string )_ Undocumented. 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](manifest.html#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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### set void chrome.cookies.set(, object `details`) Undocumented. 用给定数据设置一个cookie。如果相同的cookie存在，它们可能会被覆盖。 #### 参数 `details`_( optional enumerated Type array of object )_ Undocumented. 待设置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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `url`_( optional enumerated Type array of string )_ Undocumented. 与待设置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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `name`_( optional enumerated Type array of string )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `value`_( optional enumerated Type array of string )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `domain`_( optional enumerated Type array of string )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `path`_( optional enumerated Type array of string )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `secure`_( optional enumerated Type array of boolean )_ Undocumented. 是否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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `httpOnly`_( optional enumerated Type array of boolean )_ Undocumented. 是否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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `expirationDate`_( optional enumerated Type array of number )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `storeId`_( optional enumerated Type array of string )_ Undocumented. 用于保存该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](manifest.html#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](manifest.html#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) {...}); Undocumented. 当一个cookie被设置或者删除时候触发。 #### 参数 `changeInfo`_( optional enumerated 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `removed`_( optional enumerated Type array of boolean )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `cookie`_( optional enumerated [Cookie](cookies.html#type-Cookie) array of paramType )_ Undocumented. 被设置或者删除的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. ### 类型 #### Cookie `paramName`_( optional enumerated Type array of object )_ Undocumented. 表示一个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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `name`_( optional enumerated Type array of string )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `value`_( optional enumerated Type array of string )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `domain`_( optional enumerated Type array of string )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `hostOnly`_( optional enumerated Type array of boolean )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `path`_( optional enumerated Type array of string )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `secure`_( optional enumerated Type array of boolean )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `httpOnly`_( optional enumerated Type array of boolean )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `session`_( optional enumerated Type array of boolean )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `expirationDate`_( optional enumerated Type array of number )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `storeId`_( optional enumerated Type array of string )_ Undocumented. 包含该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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. #### CookieStore `paramName`_( optional enumerated Type array of object )_ Undocumented. 表示浏览器中的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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `id`_( optional enumerated Type array of string )_ Undocumented. 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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version. `tabIds`_( optional enumerated Type array of Type array of integer paramType )_ Undocumented. 共享该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](manifest.html#minimum_chrome_version) can ensure that your extension won't be run in an earlier browser version.