diff options
Diffstat (limited to 'files/zh-tw/mozilla/add-ons/webextensions/api')
9 files changed, 890 insertions, 0 deletions
diff --git a/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/cookiestore/index.html b/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/cookiestore/index.html new file mode 100644 index 0000000000..b8ab73dc3f --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/cookiestore/index.html @@ -0,0 +1,80 @@ +--- +title: cookies.CookieStore +slug: Mozilla/Add-ons/WebExtensions/API/cookies/CookieStore +translation_of: Mozilla/Add-ons/WebExtensions/API/cookies/CookieStore +--- +<div>{{AddonSidebar()}}</div> + +<p>{{WebExtAPIRef("cookies")}} API 的 <code>CookieStore</code> 型別代表瀏覽器中的 cookie 存放空間。</p> + +<p>不同瀏覽模式（browsing mode）的視窗，有不同的 cookie 存放空間：例如隱私/隱身模式的視窗，會使用來自非隱私/隱身模式視窗的個別 cookie 存放空間。</p> + +<h2 id="型別">型別</h2> + +<p>此型別的值都是物件，並包含以下屬性：</p> + +<dl class="reference-values"> + <dt><code>id</code></dt> + <dd><code>string</code>，代表 cookie 存放空間內的唯一識別號（identifier）。</dd> + <dt><code>tabIds</code></dt> + <dd><code>integers</code> 的 <code>array</code>，識別所有分享此 cookie 存放空間的瀏覽頁籤。</dd> +</dl> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.cookies.CookieStore")}}</p> + +<h2 id="示例">示例</h2> + +<p>在以下程式碼片段內，{{WebExtAPIRef("cookies.getAllCookieStores()")}} 用來查找瀏覽器內，所有目前能用 cookie 存放空間，並列出每個 cookie 存放空間的 ID、還有分享此 cookie 存放空間的頁籤。</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">function</span> <span class="function token">logStores</span><span class="punctuation token">(</span>cookieStores<span class="punctuation token">)</span> <span class="punctuation token">{</span> + <span class="keyword token">for</span><span class="punctuation token">(</span>store <span class="keyword token">of</span> cookieStores<span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span><span class="template-string token"><span class="string token">`Cookie store: </span><span class="interpolation token"><span class="interpolation-punctuation punctuation token">${</span>store<span class="punctuation token">.</span>id<span class="interpolation-punctuation punctuation token">}</span></span><span class="string token">\n Tab IDs: </span><span class="interpolation token"><span class="interpolation-punctuation punctuation token">${</span>store<span class="punctuation token">.</span>tabIds<span class="interpolation-punctuation punctuation token">}</span></span><span class="string token">`</span></span><span class="punctuation token">)</span><span class="punctuation token">;</span> + <span class="punctuation token">}</span> +<span class="punctuation token">}</span> + +<span class="keyword token">var</span> getting <span class="operator token">=</span> browser<span class="punctuation token">.</span>cookies<span class="punctuation token">.</span><span class="function token">getAllCookieStores</span><span class="punctuation token">(</span><span class="punctuation token">)</span><span class="punctuation token">;</span> +getting<span class="punctuation token">.</span><span class="function token">then</span><span class="punctuation token">(</span>logStores<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>致謝</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 的相容資訊來自微軟公司，原文以創用 CC 姓名標示 3.0 美國版條款授權大眾使用。</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> diff --git a/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/index.html b/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/index.html new file mode 100644 index 0000000000..34da08932c --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/index.html @@ -0,0 +1,163 @@ +--- +title: cookies +slug: Mozilla/Add-ons/WebExtensions/API/cookies +tags: + - API + - Add-ons + - Cookies + - Extensions + - Interface + - Non-standard + - Reference + - WebExtensions + - 介面 + - 參考文件 + - 擴充套件 + - 附加元件 + - 非標準 +translation_of: Mozilla/Add-ons/WebExtensions/API/cookies +--- +<div>{{AddonSidebar}}</div> + +<div>讓擴充套件可以取得、設定 cookies 資訊，並監控其變動。</div> + +<div> </div> + +<p>使用此 API 前，必須先在 <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">host 權限宣告</a>將要存取 Cookies 的網站列入。參見 <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 設定資料。如果目前已有相同的 cookies，則會覆寫原本的 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.json 設定檔中指明需要「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">host 權限宣告</a>指明需要存取 cookies 的網站清單。此後，符合 host 權限宣告的 URL 所能讀寫的任何 cookies，該擴充套件即可讀取。比方說：</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>但<em>不能</em>：</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> + +<p>譯者按：該文件會持續更新，不建議翻譯。</p> +</div> + +<h3 id="Edge_不相容資訊">Edge 不相容資訊</h3> + +<p>Edge 不支援 promises，請使用回呼（callback）函式處理。</p> + +<p> {{WebExtExamples("h2")}}</p> + +<div class="note"><strong>致謝</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 的相容資訊來自微軟公司，原文以創用 CC 姓名標示 3.0 美國版條款授權大眾使用。</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> diff --git a/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/onchanged/index.html b/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/onchanged/index.html new file mode 100644 index 0000000000..7558105bcc --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/onchanged/index.html @@ -0,0 +1,118 @@ +--- +title: cookies.onChanged +slug: Mozilla/Add-ons/WebExtensions/API/cookies/onChanged +translation_of: Mozilla/Add-ons/WebExtensions/API/cookies/onChanged +--- +<div>{{AddonSidebar()}}</div> + +<p>{{WebExtAPIRef("cookies")}} API 的 <code>onChanged</code> 事件會在 cookie 設定或刪除時觸發。</p> + +<p>請注意，更新 cookie 的屬性要透過以下兩個步驟實做：</p> + +<ol> + <li>首先，要更新的 cookie 會先被刪掉，並產生一個 <code>overwrite</code> 的 {{WebExtAPIRef("cookies.OnChangedCause")}} 提醒。</li> + <li>接著，帶著更新數值的新 cookie 會被寫進去，並產生第二個 <code>explicit</code> 的 {{WebExtAPIRef("cookies.OnChangedCause")}} 提醒。</li> +</ol> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox brush:js">browser.cookies.onChanged.addListener(listener) +browser.cookies.onChanged.removeListener(listener) +browser.cookies.onChanged.hasListener(listener) +</pre> + +<p>此 API 也能以 <code>browser.cookies.onChanged.*</code> 運行。</p> + +<p>此事件有以下函式：</p> + +<dl> + <dt><code>addListener(callback)</code></dt> + <dd>給此事件添加監聽器（listener）。</dd> + <dt><code>removeListener(listener)</code></dt> + <dd>停止監聽此事件。<code>listener</code> 參數是要移除的監聽器。</dd> + <dt><code>hasListener(listener)</code></dt> + <dd>檢查此事件的 <code>listener</code> 是否被監聽了。若有監聽，回傳 <code>true</code>，否則回傳 <code>false</code>。</dd> +</dl> + +<h2 id="addListener_語法">addListener 語法</h2> + +<h3 id="參數">參數</h3> + +<dl> + <dt><code>callback</code></dt> + <dd> + <p>能被呼叫的 callback 函式會在此事件發生的時候觸發。函式會 passed 以下參數：</p> + + <dl class="reference-values"> + <dt><code>changeInfo</code></dt> + <dd>一個含有觸發事件資訊的 <code>object</code>。它有兩個屬性：</dd> + <dd> + <dl class="reference-values"> + <dt><code>removed</code></dt> + <dd>一個 <code>boolean</code>。如果 cookie 被刪除則為 <code>true</code>，否則為 <code>false</code>。</dd> + <dt><code>cookie</code></dt> + <dd>一個 {{WebExtAPIRef('cookies.Cookie')}} 物件。含有被設定、或被刪除的 cookie 資訊。</dd> + <dt><code>cause</code></dt> + <dd>一個 {{WebExtAPIRef('cookies.OnChangedCause')}} 數值。含有 cookie被改變的潛在原因。</dd> + </dl> + </dd> + </dl> + </dd> +</dl> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p class="hidden">本相容性表格由結構化資料產生。若要貢獻資料，請參考 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 並給一個 pull request。</p> + +<p>{{Compat("webextensions.api.cookies.onChanged")}}</p> + +<h2 id="示例">示例</h2> + +<p>本範例監聽 <code>onChanged</code> 事件並紀錄由 <code>changeInfo</code> 參數傳來的資訊：</p> + +<pre class="brush: js line-numbers language-js">browser.cookies.onChanged.addListener(function(changeInfo) { + console.log('Cookie changed: ' + + '\n * Cookie: ' + JSON.stringify(changeInfo.cookie) + + '\n * Cause: ' + changeInfo.cause + + '\n * Removed: ' + changeInfo.removed); +});</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>致謝</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 的相容資訊來自微軟公司，原文以創用 CC 姓名標示 3.0 美國版條款授權大眾使用。</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> diff --git a/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/onchangedcause/index.html b/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/onchangedcause/index.html new file mode 100644 index 0000000000..592aaf7d6d --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/api/cookies/onchangedcause/index.html @@ -0,0 +1,82 @@ +--- +title: cookies.OnChangedCause +slug: Mozilla/Add-ons/WebExtensions/API/cookies/OnChangedCause +translation_of: Mozilla/Add-ons/WebExtensions/API/cookies/OnChangedCause +--- +<div>{{AddonSidebar()}}</div> + +<p>{{WebExtAPIRef("cookies")}} API 的 <code>OnChangedCause</code> 型別，代表觸發 cookie 資料變動的原因。</p> + +<h2 id="型別">型別</h2> + +<p>此型別的所有值都是字串（string）。可用值包括：</p> + +<dl> + <dt><code>evicted</code></dt> + <dd>由於垃圾回收（garbage collection）而被刪除的 cookie。</dd> + <dt><code>expired</code></dt> + <dd>由於過期而被刪除的 cookie。</dd> + <dt><code>explicit</code></dt> + <dd>透過顯式呼叫（explicit call）{{WebExtAPIRef("cookies.remove()")}} 而被插入或刪除的 cookie。</dd> + <dt><code>expired_overwrite</code></dt> + <dd>被已過期（already-expired expiration date）cookie 所覆寫的 cookie。</dd> + <dt><code>overwrite</code></dt> + <dd>A call to {{WebExtAPIRef("cookies.set()")}} overwrote this cookie with a different one.</dd> +</dl> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.cookies.OnChangedCause")}}</p> + +<h2 id="示例">示例</h2> + +<p>你可以在 cookie 變更的時候監聽被通知的 {{WebExtAPIRef("cookies.onChanged")}} 事件。此監聽器 passed 含有 <code>cause</code> 屬性，值為 <code>OnChangeCaused</code> 字串的 <code>changeInfo</code> 物件：</p> + +<pre class="brush: js">browser.cookies.onChanged.addListener(function(changeInfo) { + console.log('Cookie changed: ' + + '\n * Cookie: ' + JSON.stringify(changeInfo.cookie) + + '\n * Cause: ' + changeInfo.cause + + '\n * Removed: ' + changeInfo.removed); +});</pre> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>致謝</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 的相容資訊來自微軟公司，原文以創用 CC 姓名標示 3.0 美國版條款授權大眾使用。</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> diff --git a/files/zh-tw/mozilla/add-ons/webextensions/api/index.html b/files/zh-tw/mozilla/add-ons/webextensions/api/index.html new file mode 100644 index 0000000000..955086de10 --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/api/index.html @@ -0,0 +1,53 @@ +--- +title: JavaScript APIs +slug: Mozilla/Add-ons/WebExtensions/API +tags: + - NeedsTranslation + - TopicStub + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>JavaScript APIs for WebExtensions can be used inside the extension's <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">background scripts</a> and in any other documents bundled with the extension, including <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_action">browser action</a> or <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Page_actions">page action</a> popups, <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Sidebars">sidebars</a>, <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Options_pages">options pages</a>, or <a href="/en-US/Add-ons/WebExtensions/manifest.json/chrome_url_overrides">new tab pages</a>. A few of these APIs can also be accessed by an extension's <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Content_scripts">content scripts</a> (see the <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Content_scripts#WebExtension_APIs">list in the content script guide</a>).</p> + +<p>To use the more powerful APIs you need to <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/permissions">request permission</a> in your extension's manifest.json.</p> + +<p>You can access the APIs using the <code>browser</code> namespace:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">function</span> <span class="function token">logTabs</span><span class="punctuation token">(</span>tabs<span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>tabs<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +browser<span class="punctuation token">.</span>tabs<span class="punctuation token">.</span><span class="function token">query</span><span class="punctuation token">(</span><span class="punctuation token">{</span>currentWindow<span class="punctuation token">:</span> <span class="keyword token">true</span><span class="punctuation token">}</span><span class="punctuation token">,</span> logTabs<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> +</div> + +<div> +<p>Many of the APIs are asynchronous, returning a <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>:</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js"><span class="keyword token">function</span> <span class="function token">logCookie</span><span class="punctuation token">(</span>c<span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">log</span><span class="punctuation token">(</span>c<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="keyword token">function</span> <span class="function token">logError</span><span class="punctuation token">(</span>e<span class="punctuation token">)</span> <span class="punctuation token">{</span> + console<span class="punctuation token">.</span><span class="function token">error</span><span class="punctuation token">(</span>e<span class="punctuation token">)</span><span class="punctuation token">;</span> +<span class="punctuation token">}</span> + +<span class="keyword token">var</span> setCookie <span class="operator token">=</span> browser<span class="punctuation token">.</span>cookies<span class="punctuation token">.</span><span class="keyword token">set</span><span class="punctuation token">(</span> + <span class="punctuation token">{</span>url<span class="punctuation token">:</span> <span class="string token">"https://developer.mozilla.org/"</span><span class="punctuation token">}</span> +<span class="punctuation token">)</span><span class="punctuation token">;</span> +setCookie<span class="punctuation token">.</span><span class="function token">then</span><span class="punctuation token">(</span>logCookie<span class="punctuation token">,</span> logError<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre> +</div> + +<div> +<p>Note that this is different from Google Chrome's extension system, which uses the <code>chrome</code> namespace instead of <code>browser</code>, and which uses callbacks instead of promises for asynchronous functions. As a porting aid, the Firefox implementation of WebExtensions APIs supports <code>chrome</code> and callbacks as well as <code>browser</code> and promises. Mozilla has also written a polyfill which enables code that uses <code>browser</code> and promises to work unchanged in Chrome: <a class="external external-icon" href="https://github.com/mozilla/webextension-polyfill">https://github.com/mozilla/webextension-polyfill</a>.</p> + +<p>Firefox also implements these APIs under the <code>chrome</code> namespace using callbacks. This allows code written for Chrome to run largely unchanged in Firefox for the APIs documented here.</p> + +<p>Microsoft Edge uses the <code>browser</code> namespace, but doesn't yet support promise-based asynchronous APIs. In Edge, for the time being, asynchronous APIs must use callbacks.</p> + +<p>Not all browsers support all the APIs: for the details, see <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs">Browser support for JavaScript APIs</a>.</p> +</div> + +<div>{{SubpagesWithSummaries}}</div> diff --git a/files/zh-tw/mozilla/add-ons/webextensions/api/storage/index.html b/files/zh-tw/mozilla/add-ons/webextensions/api/storage/index.html new file mode 100644 index 0000000000..8e1d68894d --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/api/storage/index.html @@ -0,0 +1,103 @@ +--- +title: storage +slug: Mozilla/Add-ons/WebExtensions/API/storage +tags: + - API + - 擴充套件 +translation_of: Mozilla/Add-ons/WebExtensions/API/storage +--- +<div> +<div>{{AddonSidebar}}</div> + +<p>讓套件可以存讀資料以及監聽儲存項目的更動。</p> + +<p>儲存系統基於 <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API">Web Storage API</a>，有一些不同，包括：</p> + +<ul> + <li>非同步</li> + <li>值的作用域在套件而不是某個特定的網域（後端的所有腳本與內容腳本都可用同樣的鍵值）。</li> + <li>儲存的值可以是任何的 JSON-ifiable 值而並非只能是 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code>。這包括了： <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">陣列</a></code>、<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">物件</a></code>。但只有在內容可以被以JSON表示的時候，這表示不包含DOM節點。你不需要特地把值轉爲JSON <code>Strings</code>來儲存它們，它們在內部就是以JSON來表示的。</li> + <li>同一個API呼叫中可以設置或取得複數鍵值。</li> +</ul> + +<p>要使用這個 API 你必須在 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> 裡面加入 "storage" 的<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">權限</a>。</p> + +<p>每個套件都有自己的儲存空間，它們可以被切分爲不同種類的儲存。</p> + +<p>雖然這個 API 與{{domxref("Window.localStorage")}}很相似，建議你不要在套件裡使用 <code>Window.localStorage</code> 儲存套件相關資料。Firefox 在用戶由於隱私問題清除歷史記錄與資料時會清除 localStorage API 儲存的資料，而 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage/local">storage.local</a></code> API 儲存的則會留著。</p> + +<div class="note">儲存空間不會被加密，所以你不應該把它們用來儲存用戶的機密資料。</div> + +<h2 id="型別">型別</h2> + +<dl> + <dt>{{WebExtAPIRef("storage.StorageArea")}}</dt> + <dd>表示儲存空間的物件。</dd> + <dt>{{WebExtAPIRef("storage.StorageChange")}}</dt> + <dd>表示儲存空間變化的物件。</dd> +</dl> + +<h2 id="屬性">屬性</h2> + +<p><code>storage</code> 有三個屬性，各自表示不同種類的儲存空間。</p> + +<dl> + <dt>{{WebExtAPIRef("storage.sync")}}</dt> + <dd>表示 <code>sync</code> 儲存空間。<code>sync</code> 儲存空間裡的項目會被瀏覽器同步，所以可以跨裝置在所有已登入瀏覽器實例裡面使用。</dd> + <dt>{{WebExtAPIRef("storage.local")}}</dt> + <dd>表示 <code>local</code> 儲存空間。<code>local</code> 儲存空間裡的項目會被侷限在安裝套件的機器上。</dd> + <dt>{{WebExtAPIRef("storage.managed")}}</dt> + <dd>表示 <code>managed</code> 儲存空間。<code>managed</code> 儲存空間的項目由網域管理者設置而且對套件唯讀，修改這項會導致錯誤。</dd> +</dl> + +<h2 id="事件">事件</h2> + +<dl> + <dt>{{WebExtAPIRef("storage.onChanged")}}</dt> + <dd>當儲存空間裡的一個或更多項目被修改時觸發。</dd> +</dl> + +<h2 id="瀏覽器兼容性">瀏覽器兼容性</h2> +</div> + +<p>{{Compat("webextensions.api.storage")}}</p> + +<p>{{WebExtExamples("h2")}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/storage"><code>chrome.storage</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/storage.json"><code>storage.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the 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> diff --git a/files/zh-tw/mozilla/add-ons/webextensions/api/storage/local/index.html b/files/zh-tw/mozilla/add-ons/webextensions/api/storage/local/index.html new file mode 100644 index 0000000000..3cdc3ab140 --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/api/storage/local/index.html @@ -0,0 +1,84 @@ +--- +title: storage.local +slug: Mozilla/Add-ons/WebExtensions/API/storage/local +translation_of: Mozilla/Add-ons/WebExtensions/API/storage/local +--- +<div>{{AddonSidebar()}}</div> + +<p>代表 <code>local</code> 儲存空間。通常 <code>local</code> 裡面的東西，會放在套件安裝的地方。</p> + +<p>瀏覽器可能會限制套件本地可儲存的資料數量：</p> + +<ul> + <li>Chrome 限制套件內用到此 API 資料的上限為 5MB，除非有 <a href="/zh-TW/Add-ons/WebExtensions/manifest.json/permissions#Unlimited_storage">unlimitedStorage</a> 權限。</li> + <li>56 版以後的 Firefox 將能要求 unlimitedStorage 權限。目前 Firefox 還沒有限制套件內的資料上限，但這功能會在未來引入：因此，如果可能會儲存大容量的資料，最好要實做 unlimitedStorage 的請求。</li> +</ul> + +<p>如果套件被移除、相關的儲存資料也會一併移除。</p> + +<p>在 Firefox 內，你可以透過 about:config 內設定 keepUuidOnUninstall 與 keepStorageOnUninstall 為 <code>true</code> 以避免瀏覽器在移除套件時，一併移除相關的儲存資料。這個功能是為了方便開發者除錯，套件本身無法改變這個設定。</p> + +<p>雖然這 API 與 {{domxref("Window.localStorage")}} 相似，但不建議在套件內使用 <code>Window.localStorage</code>。在某些情況下，用戶會出於隱私上的理由，要求 Firefox 清理瀏覽紀錄與資料，這其中就包含使用 localStorage API 的資料。另一方面，storage.local API 的資料，在這種情況下會予以保留。</p> + +<h2 id="方法">方法</h2> + +<p><code>local</code> 物件實做了定義於 {{WebExtAPIRef("storage.StorageArea")}} 類別的方法：</p> + +<dl> + <dt>{{WebExtAPIRef("storage.StorageArea.get()")}}</dt> + <dd>取得一個或多個源自儲存空間的項目。</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.getBytesInUse()")}}</dt> + <dd>取得儲存空間內，一個或多個已為項目所使用的容量。單位為 byte。</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.set()")}}</dt> + <dd>Stores one or more items in the storage area. If the item already exists, its value will be updated. When you set a value, the {{WebExtAPIRef("storage.onChanged")}} event will fire.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.remove()")}}</dt> + <dd>刪除一個或多個儲存空間內的項目。</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.clear()")}}</dt> + <dd>刪除所有儲存空間內的項目。</dd> +</dl> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.storage.local")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>致謝</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/storage#property-local"><code>chrome.storage</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/storage.json"><code>storage.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the 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> diff --git a/files/zh-tw/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.html b/files/zh-tw/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.html new file mode 100644 index 0000000000..744cc6ed8b --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.html @@ -0,0 +1,122 @@ +--- +title: StorageArea.get() +slug: Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/get +translation_of: Mozilla/Add-ons/WebExtensions/API/storage/StorageArea/get +--- +<div>{{AddonSidebar()}}</div> + +<p>從儲存空間內檢查一個或多個單元（item）。</p> + +<p>這個非同步函式會回傳 <code><a href="https://developer.mozilla.org/zh-TW/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>。</p> + +<h2 id="語法">語法</h2> + +<pre class="syntaxbox">let gettingItem = browser.storage.<storageType>.get( + keys // null, string, object or array of strings +) +</pre> + +<p><code><storageType></code> 會是以下可覆寫的儲存類型之一：{{WebExtAPIRef("storage.sync")}} 或 {{WebExtAPIRef("storage.local")}}。</p> + +<h3 id="參數">參數</h3> + +<dl> + <dt><code>keys</code></dt> + <dd>用來識別要檢查單元的 key（單個為字串；多個為陣列、或指定預設值的物件）。如果把這裡留空（空字串、空陣列、空物件都可以），就會取得空物件。如果是 <code>null</code> 或 undefined，則會取得所有儲存的內容。</dd> +</dl> + +<h3 id="回傳值">回傳值</h3> + +<p><code><a href="https://developer.mozilla.org/zh-TW/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> that will be fulfilled with a <code>results</code> object containing every object in <code>keys</code> that was found in the storage area. If the operation failed, the promise will be rejected with an error message.</p> + +<div class="warning"> +<p>When used within a content script in Firefox versions prior to 52, the Promise returned by <code>browser.storage.local.get()</code> is fulfilled with an Array containing one Object. The Object in the Array contains the <code>keys</code> found in the storage area, as described above. The Promise is correctly fulfilled with an Object when used in the background context (background scripts, popups, options pages, etc.). When this API is used as <code>chrome.storage.local.get()</code>, it correctly passes an Object to the callback function.</p> +</div> + +<h2 id="瀏覽器相容性">瀏覽器相容性</h2> + +<p>{{Compat("webextensions.api.storage.StorageArea.get")}}</p> + +<h2 id="示例">示例</h2> + +<p>假設儲存空間有以下單元：</p> + +<pre class="brush: js">// 兩個單元：「kitten」與「monster」 +browser.storage.local.set({ + kitten: {name:"Mog", eats:"mice"}, + monster: {name:"Kraken", eats:"people"} +});</pre> + +<p>Define success and failure handlers for the promise:</p> + +<pre class="brush: js">function onGot(item) { + console.log(item); +} + +function onError(error) { + console.log(`Error: ${error}`); +}</pre> + +<p>With no <code>keys</code> argument, retrieve everything:</p> + +<pre class="brush: js">let gettingItem = browser.storage.local.get(); +gettingItem.then(onGot, onError); + +// -> Object { kitten: Object, monster: Object }</pre> + +<p>With an empty keys argument, return nothing:</p> + +<pre class="brush: js">// with an empty array, retrieve nothing +let gettingItem = browser.storage.local.get([]); +gettingItem.then(onGot, onError); + +// -> Object { }</pre> + +<p>With the name of an object, retrieve the match:</p> + +<pre class="brush: js">let gettingItem = browser.storage.local.get("kitten"); +gettingItem.then(onGot, onError); + +// -> Object { kitten: Object }</pre> + +<p>With an array of object names, retrieve all matches:</p> + +<pre class="brush: js">let gettingItem = browser.storage.local.get(["kitten", "monster", "grapefruit"]); +gettingItem.then(onGot, onError); + +// -> Object { kitten: Object, monster: Object } </pre> + +<p>With an object with object names as keys and the default value as value:</p> + +<pre class="brush: js">let gettingItem = browser.storage.local.get({ + kitten: "no kitten", + monster: "no monster", + grapefruit: { + name: "Grape Fruit", + eats: "Water" + } +}); + +// -> Object { kitten: Object, monster: Object, grapefruit: Object } +</pre> + +<p>{{WebExtExamples}}</p> + +<h3 id="Chrome_示例">Chrome 示例</h3> + +<pre class="brush: js">chrome.storage.local.get("kitten", function(items){ + console.log(items.kitten); // -> {name:"Mog", eats:"mice"} +});</pre> + +<p class="brush: js">Or with an arrow function</p> + +<pre class="brush: js">chrome.storage.local.get("kitten", items=>{ + console.log(items.kitten); // -> {name:"Mog", eats:"mice"} +});</pre> + +<div class="note"><strong>致謝</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/storage"><code>chrome.storage</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/storage.json"><code>storage.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p> +</div> diff --git a/files/zh-tw/mozilla/add-ons/webextensions/api/storage/storagearea/index.html b/files/zh-tw/mozilla/add-ons/webextensions/api/storage/storagearea/index.html new file mode 100644 index 0000000000..088e8b5a79 --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/api/storage/storagearea/index.html @@ -0,0 +1,85 @@ +--- +title: storage.StorageArea +slug: Mozilla/Add-ons/WebExtensions/API/storage/StorageArea +tags: + - API + - Add-ons + - Extensions + - NeedsTranslation + - Non-standard + - Reference + - Storage + - StorageArea + - TopicStub + - Type + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API/storage/StorageArea +--- +<div>{{AddonSidebar()}}</div> + +<p>StorageArea is an object representing a storage area.</p> + +<h2 id="Type">Type</h2> + +<p>Values of this type are objects.</p> + +<h2 id="Methods">Methods</h2> + +<dl> + <dt>{{WebExtAPIRef("storage.StorageArea.get()")}}</dt> + <dd>Retrieves one or more items from the storage area.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.getBytesInUse()")}}</dt> + <dd>Gets the amount of storage space (in bytes) used one or more items being stored in the storage area.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.set()")}}</dt> + <dd>Stores one or more items in the storage area. If an item already exists, its value will be updated.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.remove()")}}</dt> + <dd>Removes one or more items from the storage area.</dd> + <dt>{{WebExtAPIRef("storage.StorageArea.clear()")}}</dt> + <dd>Removes all items from the storage area.</dd> +</dl> + +<h2 id="Browser_compatibility">Browser compatibility</h2> + +<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> + +<p>{{Compat("webextensions.api.storage.StorageArea")}}</p> + +<p>{{WebExtExamples}}</p> + +<div class="note"><strong>Acknowledgements</strong> + +<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/storage#type-StorageArea"><code>chrome.storage</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/storage.json"><code>storage.json</code></a> in the Chromium code.</p> + +<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the 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> |