cookies

使用 WebExtensions 获取或设置 cookies, 并且在修改时能够获得通知。

你需要在 manifest.json 文件中开启“cookies”API 权限,并且需要对应站点的 主机权限 才能设置指定站点的cookie。详细信息查看 cookie 权限.

类型

cookies.Cookie
代表一个HTTP cookie的信息。
cookies.CookieStore
代表一个保存在浏览器中的 cookie。
cookies.OnChangedCause
代表 cookie 改变的原因。

方法

cookies.get()
返回一个单独的 cookie 的信息。
cookies.getAll()
返回所有符合筛选条件的 cookies。
cookies.set()
根据给定cookie数据设置一个cookie;如果同样的cookie存在讲会覆盖。
cookies.remove()
根据名字删除cookie。
cookies.getAllCookieStores()
列出所有保存的cookie。

事件句柄

cookies.onChanged
当设置或删除cookie时触发。

权限

为了使用这个API,插件必须在它的manifest中指定"cookies" API 权限,和它想要使用cookie的任何网站的 host 权限 。插件将能读取或写入host权限中所匹配的URL可以读取或写入的任何cookie。例如:

http://*.example.com/

拥有这个host权限的插件将可以:

  • 读取一个www.example.com任意路径下的不安全cookie。
  • 写入一个www.example.com任意路径下的不安全cookie。

它不能:

  • 读取www.example.com的安全cookie。
http://www.example.com/

拥有这个host权限的插件将可以:

  • 读取 www.example.com任意路径下的不安全cookie。
  • 读取 .example.com 任意路径下的不安全cookie。
  • 写入 www.example.com 任意路径下的安全和不安全cookie。
  • 写入 .example.com 任意路径下的安全和不安全cookie。

它不能:

  • 读取或写入 foo.example.com 的cookie。
  • 读取或写入 foo.www.example.com 的cookie。
*://*.example.com/

拥有这个host权限的插件将可以:

  • 读取或写入 www.example.com 任意路径下安全的和不安全的cookie。

浏览器兼容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaSafariFirefox for Android
CookieChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesSafari Full support 14Firefox Android Full support 48
CookieStoreChrome Full support YesEdge Full support 14Firefox Full support 45Opera Full support YesSafari Full support 14Firefox Android Full support 48
OnChangedCauseChrome Full support YesEdge Full support 79Firefox Full support 45Opera Full support YesSafari No support NoFirefox Android Full support 48
getChrome Full support YesEdge Full support 14Firefox Full support 45
Notes
Full support 45
Notes
Notes Provides access to cookies from private browsing mode and container tabs since version 52.
Opera Full support YesSafari Full support 14
Notes
Full support 14
Notes
Notes HTTPOnly cookies are not retrieved.
Firefox Android Full support 48
getAllChrome Full support YesEdge Full support 14
Notes
Full support 14
Notes
Notes If no URL is provided, cookies are retrieved only for URLs in currently opened tabs. In Chrome, this gets all cookies on a user's machine.
Firefox Full support 45
Notes
Full support 45
Notes
Notes Before version 52, the 'tabIds' list was empty and only cookies from the default cookie store were returned. From version 52 onwards, this has been fixed and the result includes cookies from private browsing mode and container tabs.
Opera Full support YesSafari Full support 14
Notes
Full support 14
Notes
Notes Only the cookies in the default cookie store are retrieved.
Notes HTTPOnly cookies are not retrieved.
Firefox Android Full support 48
getAllCookieStoresChrome Full support YesEdge Full support 14
Notes
Full support 14
Notes
Notes Always returns the same default cookie store with ID 0. All cookies belong to this store.
Firefox Full support 45
Notes
Full support 45
Notes
Notes Before version 52, only the default cookie store was visible. From version 52 onwards, the cookie stores for private browsing mode and container tabs are also readable.
Opera Full support YesSafari Full support 14
Notes
Full support 14
Notes
Notes Always returns the same default cookie store with ID 0.
Firefox Android Full support 48
onChangedChrome Full support YesEdge Full support 79Firefox Full support 45Opera Full support YesSafari No support NoFirefox Android Full support 48
removeChrome Full support YesEdge Full support 14Firefox Full support 45
Notes
Full support 45
Notes
Notes Before version 56, this function did not remove cookies from private browsing mode. From version 56 onwards this is fixed.
Opera Full support YesSafari Full support 14Firefox Android Full support 48
Notes
Full support 48
Notes
Notes Before version 56, this function did not remove cookies from private browsing mode. From version 56 onwards this is fixed.
sameSiteStatusChrome Full support YesEdge Full support 79Firefox Full support 63Opera No support NoSafari Full support 14
Notes
Full support 14
Notes
Notes Only supports explicit.
Firefox Android Full support 63
setChrome Full support YesEdge Full support 14Firefox Full support 45
Notes
Full support 45
Notes
Notes Before version 56, this function did not modify cookies in private browsing mode. From version 56 onwards this is fixed.
Opera Full support YesSafari Full support 14Firefox Android Full support 48
Notes
Full support 48
Notes
Notes Before version 56, this function did not modify cookies in private browsing mode. From version 56 onwards this is fixed.

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

Edge 不兼容

在 Edge 中不支持 Promises,使用 callbacks 代替。

Example extensions

Acknowledgements

这个API 基于 Chromium 的 chrome.cookies API. 这篇文档来源于Chromium 代码的 cookies.json

Microsoft Edge 兼容性数据由 Microsoft Corporation 提供,并包含在 Creative Commons Attribution 3.0 United States License.