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.