diff options
Diffstat (limited to 'files/zh-tw/mozilla/add-ons/webextensions/api/storage')
4 files changed, 394 insertions, 0 deletions
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> |