---
title: cookies
slug: Mozilla/Add-ons/WebExtensions/API/cookies
tags:
  - API
  - Add-ons
  - Cookies
  - Extensions
  - WebExtensions
translation_of: Mozilla/Add-ons/WebExtensions/API/cookies
---
<div>{{AddonSidebar}}</div>

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

<p>你需要在 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> 文件中开启“cookies”<a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API 权限</a>，并且需要对应站点的 <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">主机权限</a> 才能设置指定站点的cookie。详细信息查看 <a href="/en-US/Add-ons/WebExtensions/API/cookies#Permissions">cookie 权限</a>.</p>

<h2 id="类型">类型</h2>

<dl>
 <dt>{{WebExtAPIRef("cookies.Cookie")}}</dt>
 <dd>代表一个HTTP cookie的信息。</dd>
 <dt>{{WebExtAPIRef("cookies.CookieStore")}}</dt>
 <dd>代表一个保存在浏览器中的 cookie。</dd>
 <dt>{{WebExtAPIRef("cookies.OnChangedCause")}}</dt>
 <dd>代表 cookie 改变的原因。</dd>
</dl>

<h2 id="方法">方法</h2>

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

<h2 id="事件句柄">事件句柄</h2>

<dl>
 <dt>{{WebExtAPIRef("cookies.onChanged")}}</dt>
 <dd>当设置或删除cookie时触发。</dd>
</dl>

<h2 id="权限">权限</h2>

<p>为了使用这个API，插件必须在它的manifest中指定"cookies" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API 权限</a>，和它想要使用cookie的任何网站的 <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host 权限</a> 。插件将能读取或写入host权限中所匹配的URL可以读取或写入的任何cookie。例如：</p>

<dl>
 <dt><code>http://*.example.com/</code></dt>
 <dd>
 <p>拥有这个host权限的插件将可以：</p>

 <ul>
  <li>读取一个<code>www.example.com</code>任意路径下的不安全cookie。</li>
  <li>写入一个<code>www.example.com</code>任意路径下的不安全cookie。</li>
 </ul>

 <p><em>它不能：</em></p>

 <ul>
  <li>读取<code>www.example.com</code>的安全cookie。</li>
 </ul>
 </dd>
 <dt><code>http://www.example.com/</code></dt>
 <dd>
 <p>拥有这个host权限的插件将可以：</p>

 <ul>
  <li>读取 <code>www.example.com</code>任意路径下的不安全cookie。</li>
  <li>读取 <code>.example.com</code> 任意路径下的不安全cookie。</li>
  <li>写入 <code>www.example.com</code> 任意路径下的安全和不安全cookie。</li>
  <li>写入 <code>.example.com</code> 任意路径下的安全和不安全cookie。</li>
 </ul>

 <p>它不能：</p>

 <ul>
  <li>读取或写入 <code>foo.example.com</code> 的cookie。</li>
  <li>读取或写入 <code>foo.www.example.com</code> 的cookie。</li>
 </ul>
 </dd>
 <dt><code>*://*.example.com/</code></dt>
 <dd>
 <p>拥有这个host权限的插件将可以：</p>

 <ul>
  <li>读取或写入 <code>www.example.com</code> 任意路径下安全的和不安全的cookie。</li>
 </ul>
 </dd>
</dl>

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<p>{{Compat("webextensions.api.cookies")}}</p>

<div class="hidden note">
<p>The "Chrome incompatibilities" section is included from <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities"> https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a> using the <a href="/en-US/docs/Template:WebExtChromeCompat">WebExtChromeCompat</a> macro.</p>

<p>If you need to update this content, edit <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities">https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities</a>, then shift-refresh this page to see your changes.</p>
</div>

<h3 id="Edge_不兼容">Edge 不兼容</h3>

<p>在 Edge 中不支持 Promises，使用 callbacks 代替。</p>

<p>{{WebExtExamples("h2")}}</p>

<div class="note"><strong>Acknowledgements</strong>

<p>这个API 基于 Chromium 的 <a href="https://developer.chrome.com/extensions/cookies"><code>chrome.cookies</code></a> API. 这篇文档来源于Chromium 代码的 <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/cookies.json"><code>cookies.json</code></a> 。</p>

<p>Microsoft Edge 兼容性数据由 Microsoft Corporation 提供，并包含在 Creative Commons Attribution 3.0 United States License.</p>
</div>

<div class="hidden">
<pre>// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//    * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//    * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//    * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>
</div>