recursal/MDN huggingface dataset:
新增消息來源閱讀工具
==========

從 Firefox 2 起，消息來源（feed）可選用不同的 RSS 或 Atom 閱讀工具訂閱。這份文件提供新增其他閱讀程式支援的方法。

新增 Web 版閱讀工具
------------

新增 Web 版閱讀工具需要三個設定：

`browser.contentHandlers.types.number.title`

閱讀程式的名稱。

`browser.contentHandlers.types.number.type`

這部份必須設定為「application/vnd.mozilla.maybe.feed」。

`browser.contentHandlers.types.number.uri`

閱讀程式的 URI。其中以「%s」標示消息來源 URL 必須插入的地方。

`number` 應該替換成尚未使用的最小自然數。舉例來說，如果要新增一個名為「Easy Reader」的閱讀工具、且目前 0 到 4 皆已使用，則應將 `number` 設定為 5，如下：

* `browser.contentHandlers.types.5.title`: `Easy Reader`
* `browser.contentHandlers.types.5.type`: `application/vnd.mozilla.maybe.feed`
* `browser.contentHandlers.types.5.uri`: `http://www.theeasyreaderurl.com?feed=%s`

你可以用 `about:config` 手動加入這些設定，如果擴充套件要新增閱讀工具則亦可寫程式修改之。

### 從 Web 應用程式新增閱讀工具

使用 JavaScript 也可輕易新增消息來源的閱讀工具，只要用 `navigator.registerContentHandler()` 函式即可，如下：


```js
navigator.registerContentHandler(
  "application/vnd.mozilla.maybe.feed",
  "http://www.theeasyreaderurl.com?feed=%s",
  "Easy Reader",
);
```

新增本機閱讀程式
--------

新增本機閱讀程式時，最簡單的方式便是使用「選項」（或「偏好設定」，名稱視作業系統而定）的「消息來源」面板直接添加。

當然也可以用擴充套件，改以程式方式新增閱讀程式。只要將`browser.feeds.handlers.application` 設定為閱讀程式的路徑即可。
Firefox 3 Dom Improvements
==========================

### Firefox 3 對 DOM 的改善

Firefox 3 對 DOM 做了一些改善，改善重點之一就是加強對於「其他瀏覽器對 DOM 所增加的延伸規格」的支援。

* 支援 IE 的延伸規格 clientTop 與 clientLeft。
* 現在不論在哪裡讀取，wondow.fullScreen (en-US) perperty 可以總是保持正確，即使在 content 內也一樣。先前會錯誤地回報 false (Bug127013) 。
* 支援 IE 的延伸規格 getClientRects (en-US) and getBoundingClientRect (en-US) (Bug 174397).
* 支援 IE 的延伸規格 elementFromPoint (en-US) (Bug 199692)
* 支援 IE 的延伸規格 oncut, oncopy, onpaste, onbeforecut, onbeforecopy and onbeforepaste (Bug 280959)
* 新增可以用於 Node.nodePrincipal, Node.baseURIObject, and document.documentURIObject 的 privileged-code-only getters。Chrome code 絕對不可以在 unwrapped content object (例如： 在 XPCNativeWrapper 的 wrappedJSObject) 上 touch (get or set) 這些 properties，詳見 Bug 324464。
* 支援 The Web Applications 1.0 (HTML5) 的 getElementsByClassName() (en-US)
### 參考資料

* DOM Improvements in Firefox 3 原始網頁 (en-US)
### 延伸閱讀

* Firefox 3 開發人員須知
* DOM
瀏覽器擴充功能
=======

擴充功能（extension）可以擴展和修改瀏覽器的功能。Firefox 的擴充功能是使用 WebExtension API 建立而成，這是一個開發跨瀏覽器擴充功能的系統。這個系統的大部分相容於 Google Chrome 和 Opera 的 擴充功能 API 與 W3C Draft Community Group。這些瀏覽器的擴充功能在大多數的情況下，只需要一點改變就可以在 Firefox 或 Microsoft Edge 中執行。這個 API 也和多處理程序的 Firefox 完全相容。

如果你有任何新點子、問題，或是需要使用 WebExtension API 來移植舊的擴充功能，你可以在 Add-ons Discourse、IRC 上的 #extdev 或 Telegram MozTW dev/add-on 找到我們。

開始入門
----

* 何謂擴充功能？
* 你的第一個 WebExtension
* 你的第二個 WebExtension
* 解析 WebExtension
* WebExtension 範例 (en-US)
如何……
----

* 監看 HTTP 請求 (en-US)
* 修改網頁 (en-US)
* 在工作列增加按鈕 (en-US)
* 建立設定頁面 (en-US)
* 和剪貼簿互動 (en-US)
使用者介面
-----

* 介紹
* 工具列按鈕
* 有彈出框的工具列按鈕 (en-US)
* 網址列按鈕 (en-US)
* 有彈出框的網址列按鈕 (en-US)網址列按鈕 (en-US)
* 側邊欄
* 右鍵選單
* 設定頁面 (en-US)
* 附加頁面 (en-US)
* 通知 (en-US)
* 網址列建議 (en-US)
* 開發者工具面板
概念
--

* JavaScript API 總覽 (en-US)
* 內容腳本
* 觸發條件 (en-US)
* 檔案控制 (en-US)
* 國際化 (en-US)
* 資訊安全聲明 (en-US)
* 原生溝通方式 (en-US)
* 使用開發工具 APIs (en-US)
* UX 範例
移植
--

* 移植 Google Chrome 的擴充功能
* 移植舊的 Firefox 附加元件
* 嵌入式 WebExtensions
* 與附加元件 SDK 比較
* 與 XUL/XPCOM 比較
* Chrome 衝突表 (en-US)
* 桌面版與 Android 版的差異
Firefox 工作流程
------------

* UX
* 安裝
* 除錯
* 在 Firefox for Android 上開發
* 開始使用 web-ext
* web-ext 指令參考
* WebExtensions 和附加元件 ID
* 發布你的 WebExtension (en-US)
參考資料
----

#### JavaScript API

* JavaScript API 總覽 (en-US)
* JavaScript API 在各種瀏覽器的相容表 (en-US)

#### Manifest keys

* manifest.json 總覽
* manifest.json 在各種瀏覽器的相容表 (en-US)
* applications
* background
* homepage\_url
* options\_ui
* 作者
你的第一個 WebExtension
==================

我們會在這篇文章詳細講解 Firefox 的 WebExtension 的製作。這支附加元件會在 "mozilla.org" 網域底下的所有網頁，增加紅色外框。

範例的原始碼也放在 GitHub 喔：https://github.com/mdn/webextensions-examples/tree/main/borderify。

首先勒，你需要 Firefox 45.0 或以上的版本。

撰寫 WebExtension
---------------

新增一個資料夾，然後進到裡面：


```bash
mkdir borderify
cd borderify
```

### manifest.json

現在新增一個檔案 "manifest.json"，直接放在 "borderify" 目錄底下就行，然後把下面的程式碼塞進去：


```json
{
  "manifest\_version": 2,
  "name": "Borderify",
  "version": "1.0",

  "description": "Adds a red border to all webpages matching mozilla.org.",

  "icons": {
    "48": "icons/border-48.png"
  },

  "content\_scripts": [
    {
      "matches": ["\*://\*.mozilla.org/\*"],
      "js": ["borderify.js"]
    }
  ]
}
```


* 最前面的三個 key：`manifest_version`、`name`、`version` 必須寫進去，它包含了附加元件的基本詮釋資料（metadata）。
* `description` 是可選、但最好要有：它會在附加元件管理員內標示。
* `icons` 也是可選、但最好要有：它允許附加元件指定圖示、也會在附加元件的管理員顯示。

這裡最有趣的 key 是 `content_scripts`：它告訴 Firefox 說：符合特定型態的 URL 會載入網頁的腳本。在此我們告訴 Firefox 說：所有由 "mozilla.org" 或其子域名服務的 HTTP 或 HTTPS 頁面，都要載入 "borderify.js"。

* 深入理解 content script
* 深入理解 about match pattern

**警告：** 某些情況下，你需要給附加元件指定 ID。如果需要指定附加元件 ID，請在 `manifest.json` 引入 `applications` key，並設定 `gecko.id` 屬性：


```json
"applications": {
  "gecko": {
    "id": "borderify@example.com"
  }
}
```


### icons/border-48.png

附加元件要有一個圖標。它會在附加元件管理員的附加元件清單旁邊列出來。我們的 manifest.json 已經說好了，要在 "icons/border-48.png" 那邊會有個圖標。

在 "borderify" 目錄下直接建立 "icons" 目錄，並儲存一個叫 "border-48.png" 的圖標檔。你可以用範例的這張圖標，它是從 Google Material Design 圖標集抓下來的，並使用創用 CC：姓名標示-相同方式分享授權。

如果你要用自己的圖標，它應該是 48x48 像素。你也可以針對高解析度提供 96x96 像素的圖標，這樣的話它在 manifest.json 會被指定為 `icons` 物件內的 `96` property：


```json
"icons": {
  "48": "icons/border-48.png",
  "96": "icons/border-96.png"
}
```


要不然，你也能提供 SVG 檔，它就會等比縮放。

* 深入理解指定圖標。
### borderify.js

最後，新增一個檔案叫 "borderify.js"，直接放在 "borderify" 目錄底下即可，然後一樣把下面的 code 塞進去：


```js
document.body.style.border = "5px solid red";
```


一旦網址符合 manifest.json 中 content\_scripts 所設定的模式，這段 script 就會載入，並且就像該頁自己讀入的程式碼一樣、能夠直接存取該頁上的東西。

* 深入了解 content scripts.
測試看看
----

首先，仔細檢查這些檔案是否在正確的位置：
```

borderify/
    icons/
        border-48.png
    borderify.js
    manifest.json
```

### 安裝

在 Firefox 打開 about:debugging，點選 Load Temporary Add-on 然後選擇你的 manifest.json 檔案：

現在這個附加元件就要安裝起來，但它要在你重新啟動 Firefox 後才開始。

又或者，你可以從命令列利用 web-ext 工具執行 WebExtension。

### 測試

現在去看一下 mozilla.org 還有它下面的所有網頁。你應該會看到有個紅色外框圍繞著網頁。

![Border displayed on mozilla.org](/zh-TW/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension/border_on_mozilla_org.png)

**備註：** 不過，別把這招用在 addons.mozilla.org 上，該網域目前會阻擋 content scripts。

再做點小實驗吧。改一下腳本讓外框顏色改變，或是做其他更動。接著存檔，並按下 about:debugging 的 Reload 鍵重啟附加元件。現在你能看到更動了：

* 多了解一點附加元件的載入
打包並發送
-----

想讓別人用你的附加元件，就要把元件遞交給 Mozilla 簽署之。想獲得更多資訊，請參見 發布你的 WebExtension (en-US)。

接下來咧？
-----

現在你針對 Firefox 的 WebExtension 開發有點子的話，來看看：

* reading more about the anatomy of WebExtensions
* 再寫個更進階的 WebExtension
* 了解 WebExtensions 所提供的 JavaScript API
manifest.json
=============

manifest.json 是所有採用 WebExtension API 的擴充功能中、唯一一個必須包含的檔案。

你可透過 manifest.json 為擴充功能指定名稱（name）、版本（version）這類的基本元資料（metadata），也可指定擴充功能的一些相關功能，例如像是背景腳本（background scripts）、內容腳本（content scripts）、瀏覽器動作（browser actions）等等。

這是個採用 JSON 格式的檔案，但有個例外：它可接受含有 "`//`" 這種格式的註解文字。

manifest.json 可採用的鍵值如下所列：

* action
* author
* background
* browser\_action
* browser\_specific\_settings
* chrome\_settings\_overrides
* chrome\_url\_overrides
* commands
* content\_scripts
* content\_security\_policy
* declarative\_net\_request
* default\_locale
* description
* developer
* devtools\_page
* dictionaries
* externally\_connectable
* homepage\_url
* host\_permissions
* icons
* incognito
* manifest\_version
* name
* offline\_enabled
* omnibox
* optional\_permissions
* options\_page
* options\_ui
* page\_action
* permissions
* protocol\_handlers
* short\_name
* sidebar\_action
* storage
* theme
* theme\_experiment
* user\_scripts
* version
* version\_name
* web\_accessible\_resources

`"manifest_version"`、`"version"` 和 `"name"` 是一定要設定的鍵值。另外，如果有設定 "\_locales" directory ，就一定要設定 `"default_locale"` ，否則就是這兩個鍵值都不做設定。 Google Chrome, 並不支援 `"applications"` ，但針對 Firefox 48 之前及 Android 的版本，則必須設置這個鍵值。

你可透過擴充功能中的 JavaScript，藉由 `runtime.getManifest()` (en-US) 這個函式來存取擴充功能裡的 manifest ：


```js
browser.runtime.getManifest().version;
```

範例
--

以下程式碼顯示的是一般 manifest 鍵值的基本語法。請注意，這個範例並不是讓你用來直接複製貼上的，你必須根據所開發的擴充功能，填入相應的鍵值、關於擴充功能的完整範例，請參見 擴充功能範例 (en-US)。


```json
{
  "applications": {
    "gecko": {
      "id": "addon@example.com",
      "strict\_min\_version": "42.0"
    }
  },

  "background": {
    "scripts": ["jquery.js", "my-background.js"],
    "page": "my-background.html"
  },

  "browser\_action": {
    "default\_icon": {
      "19": "button/geo-19.png",
      "38": "button/geo-38.png"
    },
    "default\_title": "Whereami?",
    "default\_popup": "popup/geo.html"
  },

  "commands": {
    "toggle-feature": {
      "suggested\_key": {
        "default": "Ctrl+Shift+Y",
        "linux": "Ctrl+Shift+U"
      },
      "description": "Send a 'toggle-feature' event"
    }
  },

  "content\_security\_policy": "script-src 'self' https://example.com; object-src 'self'",

  "content\_scripts": [
    {
      "exclude\_matches": ["\*://developer.mozilla.org/\*"],
      "matches": ["\*://\*.mozilla.org/\*"],
      "js": ["borderify.js"]
    }
  ],

  "default\_locale": "en",

  "description": "...",

  "icons": {
    "48": "icon.png",
    "96": "icon@2x.png"
  },

  "manifest\_version": 2,

  "name": "...",

  "page\_action": {
    "default\_icon": {
      "19": "button/geo-19.png",
      "38": "button/geo-38.png"
    },
    "default\_title": "Whereami?",
    "default\_popup": "popup/geo.html"
  },

  "permissions": ["webNavigation"],

  "version": "0.1",

  "web\_accessible\_resources": ["images/my-image.png"]
}
```

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

若想對所有的 manifest 鍵值及其子健有個完整的概念，可參見 完整 manifest.json 瀏覽器相容表 (en-US)。
用戶介面
====

套件 APIs 提供了幾種介面來完成對用戶的功能。下方是那些介面的概述，每種用戶介面都有更詳細的資訊可以查閱。

**備註：** 爲了使用這些 UI 元件在套件裡提供優秀的用戶體驗，建議閱讀用戶體驗最佳實踐文章。


| 可用介面 | 敘述 | 範例 |
| --- | --- | --- |
| 工具列按鈕 | 一個瀏覽器工具列上的按鈕，被點擊時會送出事件給套件。預設的情況下在所有頁籤都能看到此按鈕。 | Example showing a toolbar button (browser action). |
| 附帶彈出視窗 (en-US)的工具列按鈕 | 一個按鈕上的彈出視窗，當按鈕被點擊時展開。彈出視窗被一個HTML文件來定義。 | Example of the pop-up on a toolbar button |
| 網址列按鈕 | 一個網址列上的按鈕，點擊時傳送事件給套件。預設的情況下，在所有的頁籤中此按鈕都會被隱藏。 | Example showing an address bar button (page action)  |
| 附帶彈出視窗 (en-US)的網址列按鈕 | 網址列按鈕上的一個按鈕，當按鈕被點擊時展開，彈出視窗被一個HTML文件來定義。 | Example of a popup on the address bar button |
| 快捷選單 | 在一個或多個瀏覽器快捷選單中的選單項目、核取方塊、選項按鈕。另外，選單可以透過增加分隔線來組成。當選單項目被點擊時傳送一個事件給套件。 | Example of content menu items added by a WebExtension, from the context-menu-demo example |
| 側邊欄 | 一個顯示在網頁旁邊的HTML文件，每頁可以顯示獨立的內容。側邊欄會在用戶安裝套件時打開，然後根據用戶對側邊欄的可視選項開關。側邊欄裡的用戶互動由它的HTML文件來控制。 | Example of a sidebar |
| 選項頁面 (en-US) | 一個使你可以定義用戶能修改的偏好設定的頁面。用戶可以透過瀏覽器的套件管理畫面進到這裡。 | Example showing the options page content added in the favorite colors example. |
| 套件頁面 | 透過套件裡的網頁來在視窗或頁籤內提供表單、幫助訊息或任何需要的內容。 | Example of a simple bundled page displayed as a detached panel. |
| 通知 (en-US) | 透過作業系統的機制顯示的短暫的通知。當用戶點擊通知或通知關閉時（不論自動關閉或用戶手動關閉）時傳送事件給套件。 | Example of an extension triggered system notification |
| 網址列建議 (en-US) | 當用戶輸入關鍵字時提供自訂的網址列建議。 | Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions. |
| 開發者工具面板 | 一個包含相關HTML文件的頁籤顯示在瀏覽器的開發者工具裡。 | Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions. |

下面是一些關於建立這些用戶介面的詳細教學：

* 在工具列加入一個按鈕 (en-US)
* 建立設定頁面 (en-US)
* 擴充開發者工具 (en-US)
何謂附加元件？
=======

附加元件（Add-ons）擴展並修改了瀏覽器的功能。他們使用標準的網路技術 ──JavaScript、HTML、以及 CSS、還有一些專用的 JavaScript API── 寫成。除此之外，附加元件可以給瀏覽器添加新功能、或是改變特定網站的外觀或內容。

Firefox 的附加元件開發基於能跨瀏覽器的 WebExtensions APIs ，在很大的程度上相容於和 Google Chrome 與 Opera 瀏覽器所支持的 extension API 。大多數情況下，針對這些瀏覽器所撰寫的 Extension 只要些許修改就能在 Firefox 或是 Microsoft Edge 執行，也與 multiprocess Firefox 完全相容。

在過去，你可以使用三種系統開發 Firefox 附加元件： XUL/XPCOM overlays、bootstrapped extensions、或是 Add-on SDK。但 2017 年 11 月底之後，WebExtensions 將成為唯一開發 Firefox 附加元件的方式，而其他方式會被廢棄。

如果你有任何想法或問題，甚至是需要協助轉換舊附加元件到新系統，你可以在 Add-ons Discourse、IRC 的 #webextensions 或 Telegram MozTW dev/add-on 找到我們。

接下來呢？
-----

* 一些附加元件的範例，請參看 Example WebExtensions。
* 學習附加元件的結構，請參看 解析 WebExtension.
* 一個簡單的附加元件開發流程，請參看 你的第一個 WebExtension。
cookies
=======

讓擴充套件可以取得、設定 cookies 資訊，並監控其變動。
使用此 API 前，必須先在 manifest.json 檔案中加入「cookies」這項 API 權限宣告，也必須以 host 權限宣告將要存取 Cookies 的網站列入。參見 Cookie 權限一節。

型別
--

`cookies.Cookie` (en-US)

代表一個 HTTP cookie 的相關資訊。

`cookies.CookieStore`

代表瀏覽器中的 cookie 存放空間。

`cookies.OnChangedCause`

代表觸發 cookie 資料變動的原因。

方法
--

`cookies.get()` (en-US)

取回單一 cookie 的相關資訊。

`cookies.getAll()` (en-US)

取回符合設定條件的所有 cookies 資訊。

`cookies.set()` (en-US)

為 cookie 設定資料。如果目前已有相同的 cookies，則會覆寫原本的 cookie 資料。

`cookies.remove()` (en-US)

刪除某特定名稱的 cookie。

`cookies.getAllCookieStores()` (en-US)

列出目前所有的 cookie 存放空間。

事件處理程序
------

`cookies.onChanged`

當 cookie 設定或刪除時觸發。

權限
--

使用此 API 前，擴充套件應於 manifest.json 設定檔中指明需要「cookies」API 權限，亦須以 host 權限宣告指明需要存取 cookies 的網站清單。此後，符合 host 權限宣告的 URL 所能讀寫的任何 cookies，該擴充套件即可讀取。比方說：

`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。

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### Edge 不相容資訊

Edge 不支援 promises，請使用回呼（callback）函式處理。

Example extensions
------------------

* cookie-bg-picker
* list-cookies

**備註：** 此 API 基於 Chromium 的 `chrome.cookies` API 而來，文件改作自 Chromium 程式碼裡的 `cookies.json`。

Microsoft Edge 的相容資訊來自微軟公司，原文以創用 CC 姓名標示 3.0 美國版條款授權大眾使用。
storage
=======

讓套件可以存讀資料以及監聽儲存項目的更動。

儲存系統基於 Web Storage API (en-US)，有一些不同，包括：

* 非同步
* 值的作用域在套件而不是某個特定的網域（後端的所有腳本與內容腳本都可用同樣的鍵值）。
* 儲存的值可以是任何的 JSON-ifiable 值而並非只能是 `String`。這包括了： `陣列`、`物件` (en-US)。但只有在內容可以被以 JSON 表示的時候，這表示不包含 DOM 節點。你不需要特地把值轉爲 JSON `Strings`來儲存它們，它們在內部就是以 JSON 來表示的。
* 同一個 API 呼叫中可以設置或取得複數鍵值。

要使用這個 API 你必須在 manifest.json 裡面加入 "storage" 的權限 (en-US)。

每個套件都有自己的儲存空間，它們可以被切分爲不同種類的儲存。

雖然這個 API 與`Window.localStorage`很相似，建議你不要在套件裡使用 `Window.localStorage` 儲存套件相關資料。Firefox 在用戶由於隱私問題清除歷史記錄與資料時會清除 localStorage API 儲存的資料，而 `storage.local` API 儲存的則會留著。

**備註：** 儲存空間不會被加密，所以你不應該把它們用來儲存用戶的機密資料。

型別
--

`storage.StorageArea` (en-US)

表示儲存空間的物件。

`storage.StorageChange` (en-US)

表示儲存空間變化的物件。

屬性
--

`storage` 有三個屬性，各自表示不同種類的儲存空間。

`storage.sync` (en-US)

表示 `sync` 儲存空間。`sync` 儲存空間裡的項目會被瀏覽器同步，所以可以跨裝置在所有已登入瀏覽器實例裡面使用。

`storage.local`

表示 `local` 儲存空間。`local` 儲存空間裡的項目會被侷限在安裝套件的機器上。

`storage.managed` (en-US)

表示 `managed` 儲存空間。`managed` 儲存空間的項目由網域管理者設置而且對套件唯讀，修改這項會導致錯誤。

事件
--

`storage.onChanged` (en-US)

當儲存空間裡的一個或更多項目被修改時觸發。

瀏覽器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* annotate-page
* favourite-colour
* forget-it
* navigation-stats
* proxy-blocker
* quicknote
* stored-credentials

**備註：** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.
cookies.OnChangedCause
======================

`cookies` API 的 `OnChangedCause` 型別，代表觸發 cookie 資料變動的原因。

型別
--

此型別的所有值都是字串（string）。可用值包括：

`evicted`

由於垃圾回收（garbage collection）而被刪除的 cookie。

`expired`

由於過期而被刪除的 cookie。

`explicit`

透過顯式呼叫（explicit call）`cookies.remove()` (en-US) 而被插入或刪除的 cookie。

`expired_overwrite`

被已過期（already-expired expiration date）cookie 所覆寫的 cookie。

`overwrite`

A call to `cookies.set()` (en-US) overwrote this cookie with a different one.

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

示例
--

你可以在 cookie 變更的時候監聽被通知的 `cookies.onChanged` 事件。此監聽器 passed 含有 `cause` 屬性，值為 `OnChangeCaused` 字串的 `changeInfo` 物件：


```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,
  );
});
```


**備註：** 此 API 基於 Chromium 的 `chrome.cookies` API 而來，文件改作自 Chromium 程式碼裡的 `cookies.json`。

Microsoft Edge 的相容資訊來自微軟公司，原文以創用 CC 姓名標示 3.0 美國版條款授權大眾使用。
cookies.onChanged
=================

`cookies` API 的 `onChanged` 事件會在 cookie 設定或刪除時觸發。

請注意，更新 cookie 的屬性要透過以下兩個步驟實做：

1. 首先，要更新的 cookie 會先被刪掉，並產生一個 `overwrite` 的 `cookies.OnChangedCause` 提醒。
2. 接著，帶著更新數值的新 cookie 會被寫進去，並產生第二個 `explicit` 的 `cookies.OnChangedCause` 提醒。
語法
--


```js
browser.cookies.onChanged.addListener(listener);
browser.cookies.onChanged.removeListener(listener);
browser.cookies.onChanged.hasListener(listener);
```


此 API 也能以 `browser.cookies.onChanged.*` 運行。

此事件有以下函式：

`addListener(callback)`

給此事件添加監聽器（listener）。

`removeListener(listener)`

停止監聽此事件。`listener` 參數是要移除的監聽器。

`hasListener(listener)`

檢查此事件的 `listener` 是否被監聽了。若有監聽，回傳 `true`，否則回傳 `false`。

addListener 語法
--------------

### 參數

`callback`

能被呼叫的 callback 函式會在此事件發生的時候觸發。函式會 passed 以下參數：

`changeInfo`

一個含有觸發事件資訊的 `object`。它有兩個屬性：

`removed`

一個 `boolean`。如果 cookie 被刪除則為 `true`，否則為 `false`。

`cookie`

一個 `cookies.Cookie` (en-US) 物件。含有被設定、或被刪除的 cookie 資訊。

`cause`

一個 `cookies.OnChangedCause` 數值。含有 cookie 被改變的潛在原因。


瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

示例
--

本範例監聽 `onChanged` 事件並紀錄由 `changeInfo` 參數傳來的資訊：


```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,
  );
});
```

### Example extensions

* cookie-bg-picker

**備註：** 此 API 基於 Chromium 的 `chrome.cookies` API 而來，文件改作自 Chromium 程式碼裡的 `cookies.json`。

Microsoft Edge 的相容資訊來自微軟公司，原文以創用 CC 姓名標示 3.0 美國版條款授權大眾使用。
cookies.CookieStore
===================

`cookies` API 的 `CookieStore` 型別代表瀏覽器中的 cookie 存放空間。

不同瀏覽模式（browsing mode）的視窗，有不同的 cookie 存放空間：例如隱私/隱身模式的視窗，會使用來自非隱私/隱身模式視窗的個別 cookie 存放空間。

型別
--

此型別的值都是物件，並包含以下屬性：

`id`

`string`，代表 cookie 存放空間內的唯一識別號（identifier）。

`tabIds`

`integers` 的 `array`，識別所有分享此 cookie 存放空間的瀏覽頁籤。

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

示例
--

在以下程式碼片段內，`cookies.getAllCookieStores()` (en-US) 用來查找瀏覽器內，所有目前能用 cookie 存放空間，並列出每個 cookie 存放空間的 ID、還有分享此 cookie 存放空間的頁籤。


```js
function logStores(cookieStores) {
  for (store of cookieStores) {
    console.log(`Cookie store: ${store.id}\n Tab IDs: ${store.tabIds}`);
  }
}

var getting = browser.cookies.getAllCookieStores();
getting.then(logStores);
```


**備註：** 此 API 基於 Chromium 的 `chrome.cookies` API 而來，文件改作自 Chromium 程式碼裡的 `cookies.json`。

Microsoft Edge 的相容資訊來自微軟公司，原文以創用 CC 姓名標示 3.0 美國版條款授權大眾使用。
storage.local
=============

代表 `local` 儲存空間。通常 `local` 裡面的東西，會放在套件安裝的地方。

瀏覽器可能會限制套件本地可儲存的資料數量：

* Chrome 限制套件內用到此 API 資料的上限為 5MB，除非有 unlimitedStorage 權限。
* 56 版以後的 Firefox 將能要求 unlimitedStorage 權限。目前 Firefox 還沒有限制套件內的資料上限，但這功能會在未來引入：因此，如果可能會儲存大容量的資料，最好要實做 unlimitedStorage 的請求。

如果套件被移除、相關的儲存資料也會一併移除。

在 Firefox 內，你可以透過 about:config 內設定 keepUuidOnUninstall 與 keepStorageOnUninstall 為 `true` 以避免瀏覽器在移除套件時，一併移除相關的儲存資料。這個功能是為了方便開發者除錯，套件本身無法改變這個設定。

雖然這 API 與 `Window.localStorage` 相似，但不建議在套件內使用 `Window.localStorage`。在某些情況下，用戶會出於隱私上的理由，要求 Firefox 清理瀏覽紀錄與資料，這其中就包含使用 localStorage API 的資料。另一方面，storage.local API 的資料，在這種情況下會予以保留。

方法
--

`local` 物件實做了定義於 `storage.StorageArea` (en-US) 類別的方法：

`storage.StorageArea.get()` (en-US)

取得一個或多個源自儲存空間的項目。

`storage.StorageArea.getBytesInUse()` (en-US)

取得儲存空間內，一個或多個已為項目所使用的容量。單位為 byte。

`storage.StorageArea.set()` (en-US)

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 `storage.onChanged` (en-US) event will fire.

`storage.StorageArea.remove()` (en-US)

刪除一個或多個儲存空間內的項目。

`storage.StorageArea.clear()` (en-US)

刪除所有儲存空間內的項目。

瀏覽器相容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### Example extensions

* annotate-page
* forget-it
* navigation-stats
* proxy-blocker
* quicknote
* stored-credentials

**備註：** This API is based on Chromium's `chrome.storage` API. This documentation is derived from `storage.json` in the Chromium code.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.
開發工具面板
======

**備註：** Firefox 54 以後可以使用這個功能。

當套件提供開發者使用的工具時，可以以一個瀏覽器開發工具的新面板的形式在開發者工具裡添加一個 UI。

![Simple example showing the addition of "My panel" to the Developer Tools tabs.](/zh-TW/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels/developer_panel_tab.png)

指定開發工具面板
--------

開發工具面板可以透過 `devtools.panels` (en-US) API 添加，因此這必須在特別的開發工具頁面執行。

透過在套件的 manifest.json 添加 `devtools_page` (en-US) 鍵並提供 HTML 檔案來添加開發工具頁面：


```json
"devtools\_page": "devtools-page.html"
```


在開發工具頁面，呼叫腳本會添加開發工具面板：


```html
<body>
  <script src="devtools.js"></script>
</body>
```


在腳本裡，藉由指定面板標題、圖示、HTML 檔案來建立開發工具：


```js
function handleShown() {
  console.log("panel is being shown");
}

function handleHidden() {
  console.log("panel is being hidden");
}

browser.devtools.panels
  .create(
    "My Panel", // title
    "icons/star.png", // icon
    "devtools/panel/panel.html", // content
  )
  .then((newPanel) => {
    newPanel.onShown.addListener(handleShown);
    newPanel.onHidden.addListener(handleHidden);
  });
```


套件現在可以在檢測器視窗透過 `devtools.inspectedWindow.eval()` (en-US) 或透過後端腳本傳送訊息來插入內容腳本兩種方式執行。你可以在擴充開發者工具 (en-US)找到更多相關訊息。

開發面板設計
------

更多關於如何設計符合 Firefox 風格的開發者面板，請查看文件光子設計系統。

圖示
--

更多關於建立開發者工具面板圖示的細節，請查看文件光子設計系統的圖示學。

範例
--

GitHub 上的 webextensions-examples 程式庫包含了建立開發工具面板的 devtools-panels 範例。
側邊欄
===

側邊欄是一個顯示在瀏覽器視窗上、網頁旁邊的面板。瀏覽器提供能讓用戶看見目前可用的側邊欄並且擇一顯示的 UI。例如，Firefox 有一個 "檢視 > 側邊欄" 的選單。一次只能有一個側邊欄顯示，而那個側邊欄會顯示在所有的頁籤以及瀏覽器視窗。

瀏覽器可能包含了一些內建的側邊欄。例如，Firefox 包含了一個可以跟書籤互動的側邊欄：

![](/zh-TW/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars/bookmarks-sidebar.png)在 manifest.json 裡用 `sidebar_action` 鍵可以替瀏覽器添加側邊欄。它會被列在內建的側邊欄旁邊，而用戶可以透過與內建側邊欄一模一樣的機制來打開它。

就像工具列按鈕一樣，你藉由 HTML 文件指定側邊欄的內容。當用戶打開側邊欄，側邊欄的文件會被讀取到每個開著的瀏覽器視窗。每個視窗都各自獲取文件的實例，當新的視窗被開啓，他們也會獲取自己的側邊欄實例。

你可以用`sidebarAction.setPanel()` (en-US)函數設置某個頁籤專屬的文件。側邊欄會透過`windows.getCurrent()` (en-US) API 找出它隸屬的視窗 :


```js
// sidebar.js
browser.windows.getCurrent({ populate: true }).then((windowInfo) => {
  myWindowId = windowInfo.id;
});
```


如果側邊欄要在不同的視窗顯示不同內容這會很有用。範例請看 "annotate-page" 範例。

側邊欄文件與後端腳本以及彈出視窗享有一樣的權限。他們可以透過`runtime.getBackgroundPage()` (en-US)直接讀取後端頁面（只要側邊欄隸屬於隱私模式的視窗），並且可以透過一些 messaging APIs 與內容腳本或原生應用互動，像是`tabs.sendMessage()` (en-US)與`runtime.sendNativeMessage()` (en-US)。

側邊欄文件會在瀏覽器視窗關閉或用戶關閉側邊欄時被卸載。這代表不像後端腳本，側邊欄文件並不總是保持讀入的狀態。但是不像工具列按鈕，他們可以在用戶與網頁互動時保持讀入。

當定義著側邊欄的套件被首次安裝時，側邊欄 2 會自動開啓。這是爲了幫助用戶瞭解這個套件包含了一個側邊欄。註：套件無法程式化地開啓側邊欄，側邊欄只能由用戶開啓。

指定側邊欄
-----

要指定側邊欄，在 manifest.json 裡透過 `sidebar_action` 鍵定義文件、標題以及圖示：


```json
"sidebar\_action": {
  "default\_title": "My sidebar",
  "default\_panel": "sidebar.html",
  "default\_icon": "sidebar\_icon.png"
}
```


你可以透過`sidebarAction` (en-US) API 程式化地更改標題、面板以及圖示。

標題與圖示會在任一個瀏覽器提供的 UI 中顯示，像是 Firefox 裡的 "檢視 > 側邊欄" 選單。

側邊欄設計
-----

更多如何設計符合 Firefox 風格的側邊欄網頁細節，請查看文件光子設計系統。

範例
--

GitHub 上的 webextensions-examples 程式庫包含了建立側邊欄的 annotate-page 範例。