1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
---
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>
|
