国际化 - Mozilla

国际化
===

WebExtensions API 有一个相当方便的模块可用于附加组件的国际化（i18n）。我们将在本文中探讨其功能，并为它的运作方式提供一个实例。WebExtensions 的 i18n 系统类似常见的 i18n 用途 JavaScript 库，例如 i18n.js。

**备注：** 本文中的 WebExtension 实例 notify-link-clicks-i18n 可在 GitHub 上查阅。在阅读下列章节时，可参照它的代码。

剖析一个国际化的 WebExtension
---------------------

一个国际化的 WebExtension 与其他 WebExtension 一样可以包含各类功能，如后台脚本、内容脚本等，但它也有些额外的部分，从而允许它适应不同的语言区域。目录树大致如下：

* webextension-根目录/
    + \_locales
        - en
            * messages.json
                + 英语消息（字符串）
        - de
            * messages.json
                + 德语消息（字符串）
        - 等其他语言
    + manifest.json
        - 含按语言区域而定的元数据
    + myJavascript.js
        - 含用于检索浏览器语言区域、特定语言环境的消息等的 JavaScript。
    + myStyles.css
        - 含按语言区域而定的 CSS

让我们逐项探讨这些新特性，因为下列每个章节都是你在国际化 WebExtension 时所要遵循的步骤。

在 \_locales 中提供本地化的字符串
----------------------

你可以使用Language subtag lookup page上的查找工具查询语言子标签。请注意，你需要搜索语言的英语名称。

每个 i18n 系统都需要你提供想支持的各语言区域的已翻译字符串。在 WebExtensions 中，这些字符串放在一个名为 `_locales` 的目录中，`_locales` 目录则位于扩展的根目录。每个语言区域都有一个名叫 `messages.json` 的文件，其中包含相应的字符串（在 WebExtension 中称作“消息”），这个文件放在 `_locales` 的子目录下，子目录以对应语言区域的语言子标签来命名。

注意，如果子标签包含一个基本语言和一个区域变种，那么语言与变种之间通常会以连字号隔开，例如 "en-US"。但作为 `_locales` 的子目录，**它必须采用下划线来分隔**，如 "en\_US"。

因此在我们这个示例应用中，我们有如下几个目录："en"（英语）、"de"（德语）、"nl"（荷兰语）以及 "ja"（日语）。每个目录都包含一个 `messages.json` 文件。

现在我们来看其中一个文件（\_locales/en/messages.json）的结构：

```json
{
  "extensionName": {
    "message": "Notify link clicks i18n",
    "description": "Name of the extension."
  },

  "extensionDescription": {
    "message": "Shows a notification when the user clicks on links.",
    "description": "Description of the extension."
  },

  "notificationTitle": {
    "message": "Click notification",
    "description": "Title of the click notification."
  },

  "notificationContent": {
    "message": "You clicked $URL$.",
    "description": "Tells the user which link they clicked.",
    "placeholders": {
      "url": {
        "content": "$1",
        "example": "https://developer.mozilla.org"
      }
    }
  }
}
```

这个文件是一个标准的 JSON — 其中每个成员都是一个带有名称的对象，里面包含一个 `message`（消息）和一个 `description`（描述）。这些项目都是字符串。`$URL$` 是一个占位符，在 WebExtension 调用 `notificationContent` 成员时将被一个子字符串替换。你将在接下来的从 JavaScript 检索消息字符串章节中了解如何使用。

**备注：** 你可以在 Locale-Specific Message reference (en-US) 里找到更多有关 `messages.json` 文件中内容的信息。

国际化 manifest.json
-----------------

要国际化你的 manifest.json，有几项任务要完成。

### 在 manifests 中检索本地化的字符串

你的 manifest.json 包含显示给用户的字符串，例如附加组件的名称和描述。如果你将这些字符串国际化，并将合适的翻译放到 messages.json 中，则用户将根据当前语言区域看到适当的字符串翻译。

要将这些字符串国际化，按如下格式指定：

```json
"name": "\_\_MSG\_extensionName\_\_",
"description": "\_\_MSG\_extensionDescription\_\_",
```

我们在在这里检索到消息字符串依赖于浏览器的语言区域，而不仅仅是一个静态字符串。

要这样调用消息字符串，你需要用的方式为：

1. 两个下划线，接着是
2. 字符串 "MSG"，接着是
3. 一个下划线，接着是
4. 你想调用的在 `messages.json` 中定义的消息名称，接着是
5. 两个下划线
```

 __MSG_ + messageName + __
```

### 指定默认语言区域

你还必须在你的 manifest.json 中指定另一个字段，它就是 default\_locale：

```json
"default\_locale": "en"
```

如果扩展没有包含浏览器当前语言区域的本地化字符串，则会使用该字段所指定的默认语言区域。任何浏览器语言区域下不可用的消息字符串都将用默认语言区域的字符串替换。有关浏览器如何选择字符串，还有一些细节需要注意 — 详见选择本地化的字符串。

依赖语言区域的 CSS
-----------

你还可以在扩展的 CSS 文件中检索本地化的字符串。例如，你可能想构建一个依赖于语言区域的 CSS 规则，如下所示：

```css
header {
  background-image: url(../images/\_\_MSG\_extensionName\_\_/header.png);
}
```

这很有用，不过在这种情况下使用预定义消息来处理或许会更好。

从 JavaScript 检索消息字符串
--------------------

所以，你应该已经建立起你的消息字符串和 manifest。现在只需开始从 JavaScript 调用这些消息字符串，以便你的扩展尽可能多地表述适合的语言。实际上 i18n API 相当简单，只需包含以下四个主要的方法（method）：

* 你最常用的很可能是 `i18n.getMessage()` (en-US) — 使用此方法可以检索一个指定的语言字符串。下方有特定的用法示例。
* `i18n.getAcceptLanguages()` (en-US) 和 `i18n.getUILanguage()` (en-US) 这两个方法可以在你需要根据语言区域自定义用户界面时使用 — 或许你希望根据用户想要的语言在首选项列表更高层显示首选项，或只显示和特定语言有关的文化信息，又或是按浏览器语言显示格式化过的日期。
* `i18n.detectLanguage()` (en-US) 这个方法可以用来检测用户提交内容的语言，并将其正确格式化。

在我们的 notify-link-clicks-i18n 示例中，后台脚本包含下列代码：

```js
var title = browser.i18n.getMessage("notificationTitle");
var content = browser.i18n.getMessage("notificationContent", message.url);
```

第一行是从最适合当前语言区域的可用 `messages.json` 文件中检索 `notificationTitle` `message` 字段。第二行与第一行类似，但它被传递了一个 URL 作为第二参数。怎么一回事？它就是你所指定的要替代 `notificationContent` 消息字段里 `$URL$` 占位符的内容：

```json
"notificationContent": {
  "message": "你点击了 $URL$。",
  "description": "告诉用户点击了哪个链接。",
  "placeholders": {
    "url" : {
      "content" : "$1",
      "example" : "https://developer.mozilla.org"
    }
  }
}
```

`"placeholders"` 这个成员定义了所有的占位符，以及它们所检索的来源。`"url"` 这个占位符指定了其内容取自 $1，它就是 `getMessage()` 第二个参数里的第一个值。由于占位符就叫做 `"url"`，我们就在实际的消息字符串中用 `$URL$` 调用它（`"name"` 用 `$NAME$` 调用也是一样的，以此类推）。对于多个占位符，你可以将其置于数组内，并作为第二个参数传递到 `i18n.getMessage()` (en-US) —`[a, b, c]`可替换为`$1`, `$2`, and `$3`，以此类推，并置于 `messages.json` 内。

接下来我们看一个例子：在 `en/messages.json` 文件中原始的 `notificationContent` 消息字符串如下：in the `en/messages.json` file is
```

你点击了 $URL$。
```

我们可以看到链接点击后会打开 `https://developer.mozilla.org`。在 `i18n.getMessage()` (en-US) 调用后，第二个参数的内容就变成了 messages.json 里的 `$1`，并替换定义在 `"url"` 占位符里的 `$URL$` 这个占位符。所以最后的消息字符串就变成了：
```

你点击了 https://developer.mozilla.org。
```

### 直接占位符的使用

你可以直接将变量`（$1`, `$2`, `$3` 等）插入消息字符串，例如我们可以将上述的 `"notificationContent"` 成员重写为：

```json
"notificationContent": {
  "message": "你点击了 $1。",
  "description": "告诉用户点击了哪个链接。"
}
```

这么做看起来似乎更快捷，也没那么复杂，但另一种方法（使用 `"placeholders"）更切实际，因为提供一个占位符名`（例如 `"url"`）和 example 可帮你记住占位符是什么 — 在你代码写了一个礼拜后，你很可能忘了 `$1`–`$8` 表示什么，但你或许记得起来占位符名表示什么。

### 替换硬编码

也可以在占位符中包含硬编码的字符串，从而每次都使用相同的值，而不是从代码中的变量获取值。例如：

```json
"mdn\_banner": {
  "message": "For more information on web technologies, go to $MDN$.",
  "description": "Tell the user about MDN",
  "placeholders": {
    "mdn": {
      "content": "https://developer.mozilla.org/"
    }
  }
}
```

在本例中我们只是硬编码了占位符的内容，而不是从 `$1` 这样的变量值中获取它。有时候你会遇到消息文件非常复杂，或者如果你想将文件里的不同值分离开来以便字符串可读性更好，这种情况下它会很有用，这些值可通过编程来访问。

此外，你可使用这样的替代方式指定不想被翻译的一部分字符串，例如人名或公司名。

选择本地化的字符串
---------

语言区域可以仅使用语言代码指定，例如 `fr` 或 `en`，也可以进一步限定区域代码，例如 `en_US` 或 `en_GB`，其描述了使用相同基础语言的区域变体。当你向 i18n 系统询问一个字符串时，它将使用以下算法选择一个字符串：

1. 如果有精确匹配当前语言区域的 `messages.json` 文件，并且它包含该字符串，则返回它。
2. 否则，如果当前语言区域有合格区域（例如 `en_US`）并且有一个无区域限定的 `messages.json` 文件（例如 `en`）且包含该字符串，则返回它。
3. 否则，如果 `manifest.json` 里包含 `default_locale` 所对应的 `messages.json` 文件且包含该字符串，则返回它。
4. 否则，返回一个空字符串。

参见下列示例：

* webextension-root-directory/
    + \_locales
        - en\_GB
            * messages.json
                + `{ "colorLocalised": { "message": "colour", "description": "Color." }, ... }`en
            * messages.json
                + `{ "colorLocalised": { "message": "color", "description": "Color." }, ... }`
        - fr
            * messages.json
                + `{ "colorLocalised": { "message": "couleur", "description": "Color." }, ...}`

假设 `default_locale` 是设为 `fr`，而浏览器的语言环境为 `en_GB`：

* 如果该附加组件调用 `getMessage("colorLocalised")`，它将返回 "colour"。
* 如果 "colorLocalised" 没有在 `en_GB` 中提供，那么 `getMessage("colorLocalised")` 将返回 "color" 而不是 "couleur".
预定义消息
-----

i18n 模块为我们提供了一些预定义的消息，我们可以用之前在 在 manifests 中检索本地化的字符串 中看到的相同的方式调用。例如：
```

__MSG_extensionName__
```

预定义的消息使用完全相同的语法，例如在消息名称之前使用 `@@`
```

__MSG_@@ui_locale__
```

下表显示了各个可用的预定义消息。

| 消息名 | 描述 |
| --- | --- |
| `@@extension_id` |
 扩展的 UUID。你可以使用该字符串构建
 URL，用于扩展内部的资源。甚至未本地化的扩展也可以使用该消息。

该消息无法在 manifest 文件中使用。

 此外，此 ID *不是* `runtime.id` (en-US)
 返回的附加组件 ID，附加组件 ID 可以使用 manifest.json 中的
 applications
 键进行设置。这是生成的、出现在附加组件 URL 中的
 UUID。这意味着你不能将此值用作
 `runtime.sendMessage()` 的
 `extensionId` 参数，也不能使用它检查
 `runtime.MessageSender` (en-US) 对象的 id
 属性。
  |
| `@@ui_locale` | 当前的语言区域；你可以使用该字符串构建语言区域特有的 URL。 |
| `@@bidi_dir` |
 当前语言区域对应的文本书写方向，可以是
 "ltr"，例如英语这样的从左到右书写的语言，或"rtl"，例如阿拉伯语这样的从右到左书写的语言。
  |
| `@@bidi_reversed_dir` | 如果 `@@bidi_dir` 是 "ltr"，则是 "rtl"，否则是 "ltr"。 |
| `@@bidi_start_edge` | 如果 `@@bidi_dir` 是 "ltr"，则是 "left"，否则是 "right"。 |
| `@@bidi_end_edge` | 如果 `@@bidi_dir` 是 "ltr"，则是 "right"，否则是 "left"。 |

回到我们之前的例子，像下面这样写更有意义：

```css
header {
  background-image: url(../images/\_\_MSG\_@@ui\_locale\_\_/header.png);
}
```

现在我们可以保存本地指定的图片，目录则可以根据所支持的不同语言区域进行匹配，例如 en、de 等 — 这样显得更有意义多了。

让我们看看一个在 CSS 文件中使用 `@@bidi_*` 消息的例子：

```css
body {
  direction: __MSG_@@bidi\_dir\_\_;
}

div#header {
  margin-bottom: 1.05em;
  overflow: hidden;
  padding-bottom: 1.5em;
  padding-__MSG_@@bidi\_start\_edge\_\_: 0;
  padding-__MSG_@@bidi\_end\_edge\_\_: 1.5em;
  position: relative;
}
```

对于从左到右语言（例如英语、中文），该 CSS 声明调用在上面预定义的消息，最终转换为下列代码：

```css
direction: ltr;
padding-left: 0;
padding-right: 1.5em;
```

而对于从右到左语言（如阿拉伯语），则将得到：

```css
direction: rtl;
padding-right: 0;
padding-left: 1.5em;
```

测试你的 WebExtension
-----------------

从 Firefox 45 开始，你可以临时安装磁盘上的 WebExtensions — 另见从磁盘加载。按上述步骤操作，然后尝试我们的 notify-link-clicks-i18n WebExtension。访问你喜欢的任何网站，然后点一下链接，查看是否有通知出现来显示所点击的链接网址。

接下来，将 Firefox 的语言区域更改为你想测试的扩展支持的某个语言区域。

1. 在 Firefox 中打开 "about:config"，找到 `general.useragent.locale` 首选项。
2. 双击该首选项（或按回车）以选择它，输入你想测试的语言环境的语言代码，然后点击“确定”（或按回车）。我们的示例扩展支持“en”（英语）、“de”德语（）、“nl”（荷兰语）和“ja”日语。
3. 重启你的浏览器以完成更改。

**备注：** 这个方法可以用来修改浏览器的语言区域，即使你未安装过该语言区域对应的语言包。这样的话你就可以将浏览器用户界面调整显示为你的默认语言。

再次从磁盘临时加载该扩展，然后测试你的新语言区域：

* 再次访问 "about:addons" — 你现在应该看到该附加组件已列出其图标，以及相应语言的名称和描述。
* 再次测试你的 WebExtension。在我们的例子中，你会转到另一个网站并点击一个链接，以查看该通知现在是否以相应语言显示。


下一步是什么？ - Mozilla

下一步是什么？
=======

现在你可以将你对浏览器扩展的想法变成现实了。在开始这个过程之前，值得了解一些有助于使其顺利进行的事情。

你可以在扩展工坊上找到更多本页讨论的相关内容，这是一个致力于帮助编写、测试、发布和分发 Firefox 扩展的网站。

你的开发环境
------

你不需要任何特殊的开发或构建环境工具来创建浏览器扩展：只需要一个简单的文本编辑器就可以创建出很好的浏览器扩展。当然，你可能一直在做 web 开发，有一套你想去配置的开发工具和环境。如果是这样，你需要意识到一些事情。

如果你使用了打包压缩工具来交付你最终的代码，你需要提交你的源码到 AMO 审查程序。此外，用于压缩、混淆、构建的工具需要是开源的 (或提供无限的免费使用), 并且可以在审阅者的计算机（Windows、Mac 或 Linux）上运行。主要是，我们的审查员无法使用商业或基于 web 的工具。

在 Extension Workshop 上了解更多关于开发工具的信息

第三方库
----

第三方库是快速为你的浏览器扩展添加复杂的特性或功能的一个好方法。当你向 AMO 审查程序提交扩展时，AMO 审查程序也会考虑任何使用的第三方库。为了简化审查，请确保你总是从第三方库的官方网站或仓库下载，如果该库已被压缩，请提供源代码的链接。请注意，第三方库不能以任何方式修改。

在 Extension Workshop 上了解更多关于提交源代码的信息

火狐浏览器附加组件分发协议
-------------

浏览器扩展需要经过签名才能安装到火狐（Firefox）的发行版或测试版。签名是在 addons.mozilla.org（AMO）进行的，并且要遵守《火狐浏览器附加组件分发协议》的条款和条件。该协议的目的是确保火狐用户能够获得支持良好的优质附加组件，以提高火狐的体验。

在 Extension Workshop 上阅读协议

在 Extension Workshop 上了解更多关于签名的信息

审查程序
----

当一个浏览器扩展被提交签名时，它将接受自动审查。当自动审查决定需要进行人工审查时，它也可能会受到人工审查。你的浏览器扩展在通过自动审查之前不会被签名，而且如果未能通过人工审查，可能会被撤销签名。审查过程遵循一套严格的准则，因此很容易检查和避免任何可能的审查问题。

在 Extension Workshop 上查看审查政策和指南

AMO 特色浏览器扩展
-----------

如果你选择在 AMO 上公开你的浏览器扩展，你的扩展可能会在 AMO 网站、火狐浏览器的附加组件管理器或 Mozilla 网站的其他地方出现。我们已经编撰了一份关于如何选择扩展程序进行推荐的指南，通过遵循这些指南，你的扩展程序会有最好的机会被推荐。

在 Extension Workshop 上了解更多关于让你的附加组件获得推荐的信息

继续你的学习经历
--------

现在你知道接下来会发生什么，是时候深入了解有关浏览器扩展开发的更多细节了。在接下来的部分中，你将发现：

* 更多关于浏览器扩展背后的基本概念，从如何使用 JavaScript API 的细节开始。
* 可供浏览器扩展使用的用户界面组件的指南。
* 一系列关于如何在扩展中实现关键任务与运用 JavaScript API 的指南。
* JavaScript API 的完整参考指南。
* Manifest 键的完整参考指南。

你还能在扩展工坊找到创建 Firefox 扩展所需要了解的所有东西，包括：

* Firefox 扩展特性一览
* 用于开发及测试的工具和工序的详细介绍
* 如何在 addons.mozilla.org 上发布你的扩展以及如何自行分发扩展
* 如何管理你发布的扩展
* 面向企业的开发与使用扩展的指南
* 如何为 Firefox 开发主题
* Firefox 开发者社区的详细介绍


扩展示例 - Mozilla

扩展示例
====

为帮助了解如何开发扩展，我们维护了一个包含简单扩展示例的代码仓库在 https://github.com/mdn/webextensions-examples。本文描述了仓库代码中所使用的 WebExtension API。

这些示例工作在 Firefox Nightly 下：大部分示例在 Firefox 的早期版本中也能够运行，请检查扩展 manifest.json 文件中的 strict\_min\_version 键。

**警告：** 有些示例只能在特定的域或页面下运行。每个示例的限制都已在其自述文件中详述。默认情况下，这些示例都不能在浏览器的隐私浏览窗口中运行，参阅隐私浏览下的扩展了解详情。

如果你想尝试这些示例，请克隆仓库，然后使用以下选项之一安装并运行扩展：

* 通过“临时加载附加组件”特性直接从源代码文件夹中载入扩展。
* 安装 `web-ext`，在命令行打开扩展的源代码文件夹，然后使用 `web-ext run`。

该扩展会在你重新启动 Firefox 之前保持加载状态。

**警告：** 不要提交这些关于 WebExtension 例子的示例到 AMO（addons.mozilla.org）上去，你无需为附加组件签名就能运行 WebExtension 的示例。只要按照上面的步骤来就可以了。

如果你想对代码仓库贡献，给我们发送 pull request。

| Name | Description | JavaScript APIs |
| --- | --- | --- |
| annotate-page | Displays a sidebar that lets you take notes on web pages. | `storage.local``tabs.onActivated``tabs.onUpdated``tabs.query``tabs.Tab``windows.getCurrent``windows.Window` |
| apply-css | Adds a page action to the toolbar. Click the button to apply a red border using injected CSS. Click the button again to remove the CSS. | `pageAction.getTitle``pageAction.onClicked``pageAction.setIcon``pageAction.setTitle``pageAction.show``tabs.insertCSS``tabs.onUpdated``tabs.query``tabs.removeCSS``tabs.Tab` |
| beastify | Adds a browser action icon to the toolbar. Click the button to choose a beast. The active tab's body content is then replaced with a picture of the chosen beast. | `extension.getURL``runtime.onMessage``tabs.executeScript``tabs.insertCSS``tabs.query``tabs.removeCSS``tabs.sendMessage``tabs.Tab` |
| bookmark-it | Adds a bookmark button to the toolbar. Click the button to toggle a bookmark for the current page. | `bookmarks.create``bookmarks.onCreated``bookmarks.onRemoved``bookmarks.remove``bookmarks.search``browserAction.onClicked``browserAction.setIcon``browserAction.setTitle``tabs.onActivated``tabs.onUpdated``tabs.query``tabs.Tab``windows.onFocusChanged` |
| borderify | Adds a solid red border to all webpages matching mozilla.org. |  |
| chill-out | Show a page action after a period of inactivity. Show cat gifs when the page action is clicked. | `alarms.clearAll``alarms.create``alarms.onAlarm``pageAction.hide``pageAction.onClicked``pageAction.show``tabs.get``tabs.onActivated``tabs.onUpdated``tabs.query``tabs.update` |
| commands | Demonstrates using the commands API to set up a keyboard shortcut. The shortcut created is accessed using Ctrl+Shift+U (Command+Shift+U on a Mac). | `commands.getAll``commands.onCommand``commands.reset``commands.update``tabs.create` |
| content-script-register | Illustrates how an extension can register URL-matching content scripts at runtime. | `contentScripts.register``runtime.onMessage``runtime.sendMessage` |
| context-menu-copy-link-with-types | Add a context menu option to links to copy the link to the clipboard, as plain text and as a link in rich HTML. | `contextMenus.create``contextMenus.onClicked``tabs.executeScript` |
| contextual-identities | List, create, and remove contextual identities. | `contextualIdentities.query``tabs.create``tabs.query``tabs.remove` |
| cookie-bg-picker | Allows the user to customize the background color and tiled pattern on sites they visit, and also saves their preferences via a cookie, reapplying them whenever they revisit a site they previously customized. | `cookies.get``cookies.onChanged``cookies.remove``cookies.set``extension.getURL``runtime.onMessage``tabs.onActivated``tabs.onUpdated``tabs.query``tabs.Tab``tabs.sendMessage` |
| devtools-panels | Demonstrates some of the devtools APIs. | `devtools.inspectedWindow``devtools.panels``runtime.getURL``runtime.onMessage``runtime.sendMessage``tabs.executeScript` |
| discogs-search | Demonstrates adding a custom search engine with the chrome\_settings\_overrides key. |  |
| dnr-block-only | Demonstrates how to block network requests without host permissions using the declarativeNetRequest API with the `declarative\_net\_request` manifest key. | `declarativeNetRequest.Rule``declarativeNetRequest.RuleAction``declarativeNetRequest.RuleCondition` |
| dnr-dynamic-with-options | Demonstrates a generic way to request host permissions and register declarativeNetRequest rules to modify network requests, without any install-time permission warnings. The options\_ui page offers a way to request permissions and register DNR rules. | `declarativeNetRequest.Rule``declarativeNetRequest.getDynamicRules``declarativeNetRequest.getSessionRules``declarativeNetRequest.updateDynamicRules``declarativeNetRequest.updateSessionRules``permissions.getAll``permissions.remove``permissions.request` |
| dnr-redirect-url | Demonstrates multiple ways to redirect requests using the declarativeNetRequest API through the `declarative\_net\_request` manifest key. Demonstrates aspects of Manifest Version 3 (MV3): action, host\_permissions, and web\_accessible\_resources, and includes a comparison with Manifest Version 2 (MV2). | `declarativeNetRequest.Redirect``declarativeNetRequest.Rule``declarativeNetRequest.RuleAction``declarativeNetRequest.RuleCondition``declarativeNetRequest.URLTransform``permissions.contains``permissions.remove``permissions.request` |
| dynamic-theme | Dynamic theme example | `alarms.create``alarms.onAlarm``theme.update` |
| emoji-substitution | Replaces words with emojis. |  |
| eslint-example | Demonstrates how to configure an extension with eslint. |  |
| export-helpers | Demonstrates how to use export helpers like cloneInto to share objects with page scripts. | `notifications.create``runtime.onMessage``runtime.sendMessage` |
| favourite-colour | An example options page, letting you store your favourite colour. | `browserAction.onClicked``runtime.openOptionsPage``storage.managed``storage.sync` |
| find-across-tabs | Demonstration of the find API. | `browserAction.onClicked``extension.getBackgroundPage``find.find``find.highlightResults``runtime.getURL``runtime.onMessage``runtime.sendMessage``tabs.create``tabs.query``tabs.Tab` |
| firefox-code-search | Demonstrates how to use the omnibox API. | `omnibox.onInputChanged``omnibox.onInputEntered``omnibox.setDefaultSuggestion``tabs.create``tabs.update` |
| forget-it | Demonstrates how to use the browsingData API. | `browserAction.onClicked``browsingData.remove``notifications.create``storage.local` |
| google-userinfo | Demonstrates how to use the identity API. | `browserAction.onClicked``identity.getRedirectURL``identity.launchWebAuthFlow``notifications.create` |
| history-deleter | History API demo: deletes history items for a given domain | `history.deleteUrl``history.search``pageAction.show``tabs.onUpdated``tabs.query` |
| http-response | Demonstrates how to rewrite HTTP responses using the webRequest.filterResponseData() API. | `webRequest.filterResponseData``webRequest.onBeforeRequest` |
| imagify | Using a sidebar, illustrates the use of file picker and drag and drop. A content script replaces the current page content with the chosen image. | `extension.getURL``runtime.onMessage``tabs.executeScript``tabs.query``tabs.sendMessage` |
| latest-download | Shows the last downloaded item, and lets you open or delete it. | `downloads.erase``downloads.getFileIcon``downloads.open``downloads.removeFile``downloads.search` |
| list-cookies | This extensions list the cookies in the active tab. | `cookies.getAll``tabs.query` |
| menu-accesskey-visible | Shows how to set up a single letter access key for a menu item. | `i18n.getMessage``menus.update``menus.create``menus.onClicked` |
| menu-demo | Demonstrates adding and manipulating menu items using the menus API. | `i18n.getMessage``menus.create``menus.onClicked``menus.remove``menus.update``runtime.lastError``tabs.executeScript` |
| menu-labelled-open | Shows how an extension can listen for the display of a menu and then add, remove, or update its menu items. | `menus.create``menus.onClicked``menus.onShown``menus.refresh``menus.update``tabs.update` |
| menu-remove-element | Shows how to detect the page element at the cursor position and remove that element, or a parent element, from the page. This example includes use of the polyfill, illustrating cross-browser extension development. | `menus.create``menus.onClicked``menus.getTargetElement``pageAction.openPopup``pageAction.show``tabs.executeScript` |
| menu-search | Illustrates how to retrieve a list of search engines and issue a search request, using search engine details added to the context menu for selected text. | `search.search``search.get``menus.create``menus.onClicked` |
| mocha-client-tests | This example shows two methods of testing an extension: running tests from within the extension, and running tests from the command line using Karma. | `runtime.onMessage``runtime.sendMessage` |
| native-messaging | Example of native messaging, including a Python application and an extension which exchanges messages with it. | `browserAction.onClicked``runtime.connectNative` |
| navigation-stats | Demonstration of the webNavigation API, showing basic stats about which pages you've visited. | `storage.local``webNavigation.onCommitted``webNavigation.onCompleted` |
| notify-link-clicks-i18n | Shows a localized notification when the user clicks on links. | `extension.getURL``i18n.getMessage``notifications.create``runtime.onMessage``runtime.sendMessage` |
| open-my-page-button | Adds a browser action icon to the toolbar. When the browser action is clicked, the add-on opens a page that was packaged with it. | `browserAction.onClicked``tabs.create` |
| page-to-extension-messaging | Demonstrates how a web page and a content script can exchange messages. Visit https://mdn.github.io/webextensions-examples/content-script-page-script-messaging.html for the demo. |  |
| permissions | Demonstrates optional permissions using the permissions API. | `browserAction.onClicked``permissions.getAll``permissions.remove``permissions.request``runtime.getURL``tabs.create` |
| private-browsing-theme | Example dynamic theme: sets a dark theme for private windows. | `theme.reset``theme.update``windows.getAll``windows.onCreated` |
| proxy-blocker | Uses the proxy API to block requests to hosts specified on a list. | `extension.getURL``proxy.onRequest``proxy.onError``storage.local``storage.onChanged` |
| quicknote | Allows the user to make quick notes by clicking a button and entering text into the resulting popup. The notes are saved in storage. | `storage.local` |
| root-cert-stats | Shows how to get details about a request's TLS connection. | `webRequest.getSecurityInfo` |
| runtime-examples | Demo of various runtime APIs. | `browserAction.onClicked``notifications.create``runtime.getManifest``runtime.onInstalled``runtime.reload` |
| selection-to-clipboard | Demonstrates how to write to the clipboard from a content script |  |
| session-state | Demonstrates how to retrieve extension-defined state from restored tabs. | `menus.create``menus.onClicked``sessions.getTabValue``sessions.setTabValue``tabs.insertCSS``tabs.onCreated``tabs.onUpdated``tabs.query` |
| store-collected-images | Demonstrates how to use the idb-file-storage library to store and manipulate files in an extension. | `browserAction.onClicked``contextMenus.create``contextMenus.onClicked``runtime.onMessage``runtime.sendMessage``tabs.create``windows.create` |
| stored-credentials | Performs basic authentication by supplying stored credentials. | `storage.local``webRequest.onAuthRequired``webRequest.onCompleted``webRequest.onErrorOccurred` |
| tabs-tabs-tabs | Demonstrates tab manipulation: opening, closing, moving, zooming tabs. | `browserAction.setBadgeBackgroundColor``browserAction.setBadgeText``tabs.create``tabs.duplicate``tabs.getZoom``tabs.move``tabs.onCreated``tabs.onMoved``tabs.onRemoved``tabs.query``tabs.reload``tabs.remove``tabs.setZoom``tabs.Tab``tabs.update` |
| theme-integrated-sidebar | A sidebar that integrates with the current theme. | `theme.getCurrent``theme.onUpdated``windows.getCurrent` |
| theme-switcher | An example of how to use the management API for themes. | `management.getAll``management.setEnabled` |
| themes | A collection of themes illustrating:* weta\_fade: a basic theme employing a single image specified in `theme_frame:`.
* weta\_fade\_chrome: the weta\_fade theme implemented with Chrome compatible manifest keys.
* weta\_tiled: a theme using a tiled image.
* weta\_mirror: a theme using multiple images and aligning those images in the header.
* animated: use of an animated PNG.
 |  |
| top-sites | Demonstration of the topSites API. | `topSites.get` |
| user-agent-rewriter | Demonstrates using the webRequest API to rewrite the User-Agent HTTP header. | `extension.getBackgroundPage``webRequest.onBeforeSendHeaders` |
| user-script-register | Illustrates how an extension can register URL-matching user scripts at runtime. | `userScripts.register``runtime.onMessage``runtime.sendMessage` |
| webpack-modules | Demonstrates how to use webpack to package npm modules in an extension. | `runtime.onMessage``runtime.sendMessage` |
| window-manipulator | Demonstrates how to manipulate windows: opening, closing, resizing windows. | `windows.create``windows.getAll``windows.getCurrent``windows.remove``windows.update``windows.Window` |
| open-irc-links | Demonstrates the use of protocol handlers. |  |


Browser styles - Mozilla

Browser styles
==============

扩展程序包含的某些 UI 组件，例如： popups (en-US), sidebars (en-US), options pages ，实际上可以用如下方式统一定义：

1. 创建一个 HTML 文件用于描述该 UI 组件的页面结构
2. 在 manifest.json 中添加字段 (`browser_action`, `page_action` (en-US), `sidebar_action` (en-US), 或 `options_ui` (en-US)) 以指向其对应的页面

这种方式面临的一个挑战是如何使用浏览器自带的样式，以使得组件的 UI 表现与浏览器的 UI 风格相符。要解决这个问题，可以在该字段的配置中增加一个可字段 `browser_sytle` ，如果设置了这个字段并且值为 `true` , 那么该 UI 组件的 HTML 将会被插入一个或多个样式表，样式表会使你的扩展程序的 UI 表现与浏览器的风格一致 (并且与其他同样应用了这个字段的扩展程序一致)。

若使用了 `browser_style: true` , 你需要在不同的浏览器主题中测试你的扩展程序，以确保其 UI 表现和期望的一致。

**备注：** 谷歌浏览器 **Google Chrome** 和 欧朋浏览器 **Opera** 使用字段名 `chrome_style` 而非`browser_style`, 因此如果要适配它们，你需要同时添加这两个字段。

在火狐浏览器中，这个样式文件可以在 `chrome://browser/content/extension.css`查看。为 Mac OS X 系统额外准备的样式文件也可以在 `chrome://browser/content/extension-mac.css` 查看。

大多数样式是自动应用的，但是某些元素需要添加非标准的类名 `browser-style` 来获得其样式，如下表所示：

| Element | Example |
| --- | --- |
| `<button>` |
```html
<button class="browser-style">Click me</button>
```
 |
| `<select>` |
```html
<select class="browser-style" name="select">
  <option value="value1">Value 1</option>
  <option value="value2" selected>Value 2</option>
  <option value="value3">Value 3</option>
</select>
```
 |
| `<textarea>` |
```html
<textarea class="browser-style">Write here</textarea>
```
 |
|
 Parent of an
 `<input>` |
```html
<div class="browser-style">
  <input type="radio" id="op1" name="choices" value="op1"/>
  <label for="op1">Option 1</label>
<input type="radio" id="op2" name="choices" value="op2"/>
<label for="op2">Option 2</label>
</div>
```

 |

**备注：** 查看 Firefox bug 1465256 以了解相关修订

浏览器兼容性
------

### webextensions.manifest.action

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

### webextensions.manifest.browser\_action

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

### webextensions.manifest.page\_action

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

### webextensions.manifest.sidebar\_action

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

### webextensions.manifest.options\_ui

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

火狐面板组件 Firefox Panel Components
-------------------------------

**备注：** 此功能不是通用标准，仅支持在 firefox 中使用

`chrome://browser/content/extension.css` 样式文件中也包含了火狐面板组件的样式

legacy Firefox Style Guide 使用示例

| Element | Example |
| --- | --- |
| Header |
```html
<header class="panel-section panel-section-header">
  <div class="icon-section-header"><img src="image.svg"/></div>
  <div class="text-section-header">Header</div>
</header>
```
 |
| Footer |
```html
<footer class="panel-section panel-section-footer">
  <button class="panel-section-footer-button">Cancel</button>
  <div class="panel-section-footer-separator"></div>
  <button class="panel-section-footer-button default">Confirm</button>
</footer>
```
 |
| Tabs |
```html
<div class="panel-section panel-section-tabs">
  <button class="panel-section-tabs-button selected">Tab</button>
  <div class="panel-section-tabs-separator"></div>
  <button class="panel-section-tabs-button">Tab</button>
  <div class="panel-section-tabs-separator"></div>
  <button class="panel-section-tabs-button">Tab</button>
</div>
```
 |
| Form |
```html
<div class="panel-section panel-section-formElements">
  <div class="panel-formElements-item">
    <label for="name01">Label:</label>
    <input type="text" value="Name" id="name01" />
  </div>
  <div class="panel-formElements-item">
    <label for="picker01">Label:</label>
    <select id="picker01">
      <option value="value1" selected="true">Dropdown</option>
      <option value="value2">List Item</option>
      <option value="value3">List Item</option>
    </select>
  </div>
  <div class="panel-formElements-item">
    <label for="placeholder01">Label:</label>
    <input type="text" placeholder="Placeholder" id="placeholder01" />
    <button name="expander" class="expander"></button>
  </div>
</div>
```
 |
| Menu |
```html
<div class="panel-section panel-section-list">
  <div class="panel-list-item">
    <div class="icon"></div>
    <div class="text">List Item</div>
    <div class="text-shortcut">Ctrl-L</div>
  </div>
<div class="panel-list-item">
<div class="icon"></div>
<div class="text">List Item</div>
<div class="text-shortcut"></div>
</div>
<div class="panel-section-separator"></div>
<div class="panel-list-item disabled">
<div class="icon"></div>
<div class="text">Disabled List Item</div>
<div class="text-shortcut"></div>
</div>
<div class="panel-section-separator"></div>
<div class="panel-list-item">
<div class="icon"></div>
<div class="text">List Item</div>
<div class="text-shortcut"></div>
</div>
<div class="panel-list-item">
<div class="icon"></div>
<div class="text">List Item</div>
<div class="text-shortcut"></div>
</div>
</div>
```

 |

### 示例

#### HTML

```html
<header class="panel-section panel-section-header">
  <div class="icon-section-header"><!-- An image goes here. --></div>
  <div class="text-section-header">Header</div>
</header>

<div class="panel-section panel-section-list">
  <div class="panel-list-item">
    <div class="icon"></div>
    <div class="text">List Item</div>
    <div class="text-shortcut">Ctrl-L</div>
  </div>

  <div class="panel-list-item">
    <div class="icon"></div>
    <div class="text">List Item</div>
    <div class="text-shortcut"></div>
  </div>

  <div class="panel-section-separator"></div>

  <div class="panel-list-item disabled">
    <div class="icon"></div>
    <div class="text">Disabled List Item</div>
    <div class="text-shortcut"></div>
  </div>

  <div class="panel-section-separator"></div>

  <div class="panel-list-item">
    <div class="icon"></div>
    <div class="text">List Item</div>
    <div class="text-shortcut"></div>
  </div>

  <div class="panel-list-item">
    <div class="icon"></div>
    <div class="text">List Item</div>
    <div class="text-shortcut"></div>
  </div>
</div>

<footer class="panel-section panel-section-footer">
  <button class="panel-section-footer-button">Cancel</button>
  <div class="panel-section-footer-separator"></div>
  <button class="panel-section-footer-button default">Confirm</button>
</footer>
```

```
/\* Global \*/
html,
body {
  background: white;
  box-sizing: border-box;
  color: #222426;
  cursor: default;
  display: flex;
  flex-direction: column;
  font: caption;
  margin: 0;
  padding: 0;
  -moz-user-select: none;
}

body \* {
  box-sizing: border-box;
  text-align: start;
}

button.panel-section-footer-button,
button.panel-section-tabs-button {
  color: inherit;
  background-color: unset;
  font: inherit;
  text-shadow: inherit;
  -webkit-appearance: none;
  -moz-appearance: none;
  appearance: none;
  border: none;
}

/\* Panel Section \*/
.panel-section {
  display: flex;
  flex-direction: row;
}

.panel-section-separator {
  background-color: rgba(0, 0, 0, 0.15);
  min-height: 1px;
}

/\* Panel Section - Header \*/
.panel-section-header {
  border-bottom: 1px solid rgba(0, 0, 0, 0.15);
  padding: 16px;
}

.panel-section-header > .icon-section-header {
  background-position: center center;
  background-repeat: no-repeat;
  height: 32px;
  margin-right: 16px;
  position: relative;
  width: 32px;
}

.panel-section-header > .text-section-header {
  align-self: center;
  font-size: 1.385em;
  font-weight: lighter;
}

/\* Panel Section - List \*/
.panel-section-list {
  flex-direction: column;
  padding: 4px 0;
}

.panel-list-item {
  align-items: center;
  display: flex;
  flex-direction: row;
  height: 24px;
  padding: 0 16px;
}

.panel-list-item:not(.disabled):hover {
  background-color: rgba(0, 0, 0, 0.06);
  border-bottom: 1px solid rgba(0, 0, 0, 0.1);
  border-top: 1px solid rgba(0, 0, 0, 0.1);
}

.panel-list-item:not(.disabled):hover:active {
  background-color: rgba(0, 0, 0, 0.1);
}

.panel-list-item.disabled {
  color: #999;
}

.panel-list-item > .icon {
  flex-grow: 0;
  flex-shrink: 0;
}

.panel-list-item > .text {
  flex-grow: 10;
}

.panel-list-item > .text-shortcut {
  color: #808080;
  font-family: "Lucida Grande", caption;
  font-size: 0.847em;
  justify-content: flex-end;
}

.panel-section-list .panel-section-separator {
  margin: 4px 0;
}

/\* Panel Section - Footer \*/
.panel-section-footer {
  background-color: rgba(0, 0, 0, 0.06);
  border-top: 1px solid rgba(0, 0, 0, 0.15);
  color: #1a1a1a;
  display: flex;
  flex-direction: row;
  height: 41px;
  margin-top: -1px;
  padding: 0;
}

.panel-section-footer-button {
  flex: 1 1 auto;
  height: 100%;
  margin: 0 -1px;
  padding: 12px;
  text-align: center;
}

.panel-section-footer-button > .text-shortcut {
  color: #808080;
  font-family: "Lucida Grande", caption;
  font-size: 0.847em;
}

.panel-section-footer-button:hover {
  background-color: rgba(0, 0, 0, 0.06);
}

.panel-section-footer-button:hover:active {
  background-color: rgba(0, 0, 0, 0.1);
}

.panel-section-footer-button.default {
  background-color: #0996f8;
  box-shadow: 0 1px 0 #0670cc inset;
  color: #fff;
}

.panel-section-footer-button.default:hover {
  background-color: #0670cc;
  box-shadow: 0 1px 0 #005bab inset;
}

.panel-section-footer-button.default:hover:active {
  background-color: #005bab;
  box-shadow: 0 1px 0 #004480 inset;
}

.panel-section-footer-separator {
  background-color: rgba(0, 0, 0, 0.1);
  width: 1px;
  z-index: 99;
}
```

```
/\* Example specific – not part of chrome://browser/content/extension.css \*/
body {
  background: #fcfcfc;
  background-clip: padding-box;
  border: 1px solid rgba(24, 26, 27, 0.2);
  box-shadow:
    0 3px 5px rgba(24, 26, 27, 0.1),
    0 0 7px rgba(24, 26, 27, 0.1);
  box-sizing: content-box;
  margin: 2em auto 0.5em;
  width: 384px;
}

html {
  min-height: 100vh;
}

html > body {
  margin: auto;
}

.icon-section-header {
  background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgdmlld0JveD0iMCAwIDMyIDMyIj48Y2lyY2xlIGZpbGw9IiMzNjM5NTkiIGN4PSIxNSIgY3k9IjE1IiByPSIxNSIvPjwvc3ZnPg==");
}
```

#### 结果


地址栏按钮 - Mozilla

地址栏按钮
=====

通常来说的 page action，是添加到浏览器地址栏中的按钮。用户通过点击这个按钮与你的扩展进行交互。

![](/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions/address_bar_button.png)

地址栏按钮（Page actions）和工具栏按钮（browser actions）
------------------------------------------

地址栏按钮 (或 page action) 与工具栏按钮 (或 browser action) 非常相似。

其不同之处为：

* 位置：
    + 地址栏按钮是显示在浏览器的地址栏内；
    + 工具栏按钮不是显示在地址栏内，而是在浏览器的工具栏上。
* 可见性：
    + 地址栏按钮默认是隐藏的（尽管可以通过 manifest 中“show\_matches 和 hide\_matches 来改变），而你可以在特定 tabs 中调用 pageAction.show() 和 pageAction.hide() 来显示或隐藏它。
    + 工具栏按钮总是可见的。

当动作（行为）与当前页面关联时，使用地址栏按钮，而当动作（行为）与浏览器相关或与多个页面相关时使用工具栏按钮。例如：

| 类型 | 书签动作 | 内容动作 | 标签操作 |
| --- | --- | --- | --- |
| page action | 将本页面保存到书签 | Reddit enhancement | Send tab |
| browser action | 显示所有书签 | 使能 ad-blocking | 同步所有打开的标签 |

定义地址栏按钮
-------

你可以在 manifest.json 中使用 page\_action 键定义地址栏按钮的属性：

```json
"page\_action": {
  "browser\_style": true,
  "default\_icon": {
    "19": "button/geo-19.png",
    "38": "button/geo-38.png"
  },
  "default\_title": "Whereami?"
}
```

仅 default\_icon 是强制（必需）的。

有两种方式定义地址栏按钮：带 popup 窗口和无 popup 窗口。如果你没有指定一个 popup，则当用户点击此按钮时，事件被派送到使用pageAction.onClicked (en-US)侦听器的扩展：

```js
browser.pageAction.onClicked.addListener(handleClick);
```

如果你指定了一个 popup，则点击事件不被派送，在用户点击按钮时显示 popup。用户可以与 popup 进行交互，并且当用户点击 popup 以外区域时，popup 自动关闭。参见Popup可获得创建和管理 popups 更详细内容。

注意你的扩展只能有一个地址栏按钮。

通过使用pageAction (en-US) API，你可以以编程方式修改地址栏按钮的任何属性。

Icons
-----

如何创建用于地址栏按钮的 ICONS 的详细内容，请参见Photon Design System文档中的Iconography节。

示例
--

GitHub 上的 webextensions-examples 库中包括了实现无 popup 地址栏按钮的例子 chill-out 。


Toolbar button - Mozilla

Toolbar button
==============

 常说的 浏览器动作（browser action）, 指通过在工具栏上上添加新按钮，提供用户互动选项，用户可点击按钮与你的扩展进行互动。

 ![](/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Toolbar_button/browser-action.png)

工具栏按钮（browser action）与地址栏按钮（page action）极为相似。区分其不同点及使用，请参看 Page actions and browser actions.

指定浏览器动作
-------

通过 manifest.json 里的关键字`browser_action` 来定义浏览器动作的属性：

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

必须定义的键是 `default_icon`.

有两种方法来指定浏览器动作：带弹出框（popup）和不带弹出框（popup）。

如果不指定弹出框，当用户点击按钮时，点击事件将被发送至扩展，而扩展可用以下函数来捕获 `browserAction.onClicked` (en-US):

```js
browser.browserAction.onClicked.addListener(handleClick);
```

如果指定了弹出框，当用户点击按钮时，点击事件将不会被发送，而是显示出弹出框。用户能够通过弹出框进行互动，并且点击框外区域时弹出框会自动关闭。请参看文章 Popup 来了解更多关于创建和管理弹出框的细节。

注意一个扩展只能指定一个浏览器动作。

可通过`browserAction` API 在程序里更改你的浏览器动作的属性。

图标
--

想了解更多关于如何创建浏览器动作图标信息，请参看Photon Design System 文档里的 Iconography 部分。

范例
--

在 Github 上的扩展范例库 webextensions-examples 中有两个实现浏览器动作的例子：

* bookmark-it没有使用 popup 实现了浏览器动作。
* beastify使用 popup 实现了浏览器动作。


通知 - Mozilla

通知
==

通知允许你使用底层操作系统提供的通知服务来传达有关你的扩展或其内容的信息。

![](/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Notifications/notify-shadowed.png)

通知可以包含对动作的代码的调用，在你的扩展中，你可以监听通知的点击或者关闭事件。

声明通知
----

通过 `notifications` (en-US) API，你能够以编程的方式使用通知功能。在此之前，你需要在扩展的 manifest.json 中声明 `notifications` 权限。

```json
"permissions": ["notifications"]
```

接下来，你可以使用 `notifications.create` (en-US) 来创建一个通知，这里有一个来自 notify-link-clicks-i18n 的简单示例：

```js
const title = browser.i18n.getMessage("notificationTitle");
const content = browser.i18n.getMessage("notificationContent", message.url);
browser.notifications.create({
  type: "basic",
  iconUrl: browser.extension.getURL("icons/link-48.png"),
  title,
  message: content,
});
```

上述代码会创建一个带有图标、标题和内容的通知。

倘若通知包含对动作的代码的调用，你可以通过监听通知的点击事件来处理：

```js
browser.notifications.onClicked.addListener(handleClick);
```

如果你需要获取被点击的通知的来源，你可能需要定义通知的 `id`，这样一来，你就能够知道具体是哪个通知被用户点击了。

图标
--

想要了解关于创建通知图标的更多细节，可以参阅 Photon Design System 文档中的 Iconography 章节。

示例
--

GitHub 仓库 webextensions-examples 中包含了通知的实现示例 notify-link-clicks-i18n


history - Mozilla

history
=======

使用 `history` API 与浏览器历史记录进行交互。

**备注：** 下载也被当做一个 `HistoryItem` (en-US) 对象。因此，`history.onVisited` (en-US)等事件也会被下载所触发。

浏览器历史记录是对用户所访问的页面按时间顺序进行的记录和保存。history API 可以帮你实现以下功能：

* 查找浏览器历史记录中出现过的页面
* 移除浏览器历史记录中的单个页面
* 向浏览器历史记录中添加页面
* 移除所有浏览器历史记录中的页面

然而，用户可能多次访问单个页面，因此 API 中有访问集合“visits”的概念。所以，该 API 还可以做如下使用：

* 获取用户对单个页面的所有访问记录的集合
* 移除给定期间内任意页面的访问记录的集合

使用该 API 之前，扩展程序必须在其 `manifest.json` 文件中获取 history 的许可。

类型
--

`history.TransitionType` (en-US)

描述浏览器如何转到特定页面。

`history.HistoryItem` (en-US)

提供浏览器历史记录中单个特定页面的详细信息。

`history.VisitItem` (en-US)

描述对一个页面的单次访问。

方法
--

`history.search()` (en-US)

在浏览器历史记录中查找符合给定条件的`history.HistoryItem` (en-US)

`history.getVisits()` (en-US)

获取指定页面的访问集信息。

`history.addUrl()` (en-US)

为浏览器历史记录添加一个指定页面的访问。

`history.deleteUrl()` (en-US)

移除浏览器历史记录中所有对指定 URL 的访问。

`history.deleteRange()` (en-US)

移除指定时间段内对用户指定页面的访问。

`history.deleteAll()` (en-US)

移除浏览器历史记录中的所有访问。

事件
--

`history.onTitleChanged` (en-US)

当用户访问的页面标题被记录时触发。

`history.onVisited` (en-US)

每次用户访问页面时会触发，并提供该页面的 `history.HistoryItem` (en-US) 数据。

`history.onVisitRemoved` (en-US)

当一个 URL 被彻底从浏览器历史记录中移除时触发。

浏览器兼容性
------

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

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

* history-deleter

**备注：** 该 API 基于 Chromium 的`chrome.history` API。该文档由 Chromium 代码中的`history.json`衍生而来。

微软 Edge 兼容性数据由微软公司提供并包含在如下证书中——Creative Commons Attribution 3.0 United States License.


clipboard - Mozilla

clipboard
=========

WebExtention 的 `clipboard` API 增加了一个将图像复制到剪贴板的函数。目前，这个 API 仅支持复制图像，但我们期望它未来支持复制文本和 HTML（译者注：原文如此，可能是指被支持复制富内容之后的标准剪贴板 API 取代）。

这个 WebExtension API 之所以存在，主要是因为标准的 Web 剪贴板 API Clipboard API 不支持将图像写入剪贴板。一旦标准剪贴板 API 对非文本剪贴板内容的支持进入通用状态，则此 API 可能会被弃用。

Reading from the clipboard is not supported by this API, because the clipboard can already be read using the standard web platform APIs. See Interacting with the clipboard.

This API is based on Chrome's `clipboard` API, but that API is only available for Chrome apps, not extensions.

To use this API you need the `"clipboardWrite"` extension permission.

函数
--

`clipboard.setImageData()`

复制图像到剪切板。

浏览器兼容性
------

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

**备注：** 此 API 基于 Chromium 的 `chrome.clipboard` API.


proxy - Mozilla

proxy
=====

**警告：** 不推荐使用 `proxy.register()` (en-US) 或者 `proxy.unregister()` (en-US) 方法使用 Proxy Auto-Configuration (PAC) file. 这个 API 将会在 Firefox 68 中废弃并且在 Firefox 71 中删除。

使用 proxy API 来代理 web 请求。你可以使用 **``proxy.onRequest` (en-US)`** 事件监听器来拦截 web 请求，并且返回一个可以描述是否代理并且怎样代理它们的对象。

`proxy.onRequest` (en-US)的好处在于，用于实现你拦截策略的代码在你的扩展的后台脚本运行，所以，它可以让 **`WebExtension APIs`** 能够完全的访问你的扩展 (举例来说，可以访问你扩展的`storage`和像 dns 等类似的网络 api)

除了这个 api，扩展也能够使用\*\*`browserSettings.proxyConfig` (en-US)\*\*属性来重新编辑你全局的`proxy`设置

Chrome 浏览器提供了一个叫做`'proxy'的`api 扩展，它的功能跟这个 api 类似，在 chrome 的 api 中也可以用来实现一个拦截策略。然而，Chrome 的 API 的设计跟这个 API 设计完全不同。因为这个 API 跟谷歌的`proxy`的 API 完全不同，这个 API 只能通过'browser'命名空间访问

如果你想用这个 API 你需要得到'`proxy`'的permission.并且，如果你想拦截一个请求，你同样也需要当前拦截请求的 url 的 host permission。

Types
-----

`proxy.ProxyInfo` (en-US)

Describes a proxy.

`proxy.RequestDetails` (en-US)

Contains information about a web request that the browser is about to make.

Properties
----------

`proxy.settings` (en-US)

Get and set proxy settings.

Functions
---------

`proxy.register()` (en-US)
已弃用

Registers the given proxy script.

`proxy.unregister()` (en-US)
已弃用

Unregisters the proxy script.

Events
------

`proxy.onError` (en-US)

Fired when the system encounters an error running the PAC script or the `onRequest` listener.

`proxy.onRequest` (en-US)

Fired when a web request is about to be made, giving the extension an opportunity to proxy it.

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

* proxy-blocker
Browser compatibility
---------------------

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


downloads - Mozilla

downloads
=========

启用与浏览器的下载管理器交互的扩展。你可以使用这个 API 模块来下载文件、取消、暂停、恢复下载和在文件管理器中显示下载的文件。
为使用此 API，你需要在你的 manifest.json 文件中声明 "downloads" API 权限。

Types
-----

`downloads.FilenameConflictAction` (en-US)

定义当一个下载的文件与现存的文件命名冲突时要做什么。

`downloads.InterruptReason` (en-US)

定义一系列中断下载的可能理由。

`downloads.DangerType` (en-US)

定义一组与可下载文件相关的潜在危险的常见警告。

`downloads.State` (en-US)

定义当前下载可能处于的不同状态。

`downloads.DownloadItem`

代表下载的文件。

`downloads.StringDelta` (en-US)

表示两个字符串之间的差异。

`downloads.DoubleDelta` (en-US)

代表两个双精度浮点数之间的差异。

`downloads.BooleanDelta` (en-US)

代表两个布尔数之间的差异。

`downloads.DownloadTime` (en-US)

代表一个下载将会花费的时间。

`downloads.DownloadQuery` (en-US)

定义一组参数，可用于在下载管理器中搜索一组特定的下载。

Functions
---------

`downloads.download()`

下载一个文件，给出它的 URL 和其他可选的参数。

`downloads.search()` (en-US)

查询 `DownloadItems` 是否在浏览器的下载管理器中可用，返回匹配指定的搜索标准的条目。

`downloads.pause()` (en-US)

暂停一个下载。

`downloads.resume()` (en-US)

恢复一个暂停的下载。

`downloads.cancel()` (en-US)

取消一个下载。

`downloads.getFileIcon()` (en-US)

检索指定下载的图标。

`downloads.open()` (en-US)

用下载的文件相关联的程序打开它。

`downloads.show()` (en-US)

打开当前平台的文件管理应用来在它包含的文件夹中显示下载的文件。

`downloads.showDefaultFolder()` (en-US)

用当前平台的文件管理应用显示默认下载文件夹。

`downloads.erase()` (en-US)

擦除浏览器的下载历史中匹配 `DownloadItems` 的下载记录，不会在磁盘中删除文件。

`downloads.removeFile()` (en-US)

从磁盘中移除下载的文件，但不从浏览器的下载历史中去除。

`downloads.acceptDanger()` (en-US)

提示用户接受或取消危险的下载。

`downloads.drag()`

将下载的文件拖动到另一个应用程序。

`downloads.setShelfEnabled()` (en-US)

启用或禁用与当前浏览器配置文件关联的每个窗口底部的灰色架子。只要至少一个扩展名已禁用该架子，它就会被禁用。

Events
------

`downloads.onCreated` (en-US)

当一个下载开始时被 `DownloadItem` 对象触发。

`downloads.onErased` (en-US)

当一个下载从历史中擦除时被 Fires with the `downloadId` 触发。

`downloads.onChanged` (en-US)

当任意一个 `DownloadItem` 的属性期望 `bytesReceived` 改变时，此事件被这个 `downloadId` 和包含了变化属性的对象触发。

Browser compatibility
---------------------

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

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

* latest-download

**备注：** This API is based on Chromium's `chrome.downloads` API.

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


find - Mozilla

find
====

在网页中查找文本，并突出显示匹配项。

要使用此 API，你需要具有“查找” 权限。

功能
--

`find.find()` (en-US)

在网页中查找文本。

`find.highlightResults()` (en-US)

突出显示找到的最后一组匹配项。

`find.removeHighlighting()` (en-US)

删除所有突出显示。

浏览器兼容性
------

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


webRequest - Mozilla

webRequest
==========

为发出的 HTTP 请求在不同阶段添加事件监听器。事件监听器可以接收到请求的详细信息，也可以修改或取消请求。概况
--

每个事件都会在请求的特定阶段触发。事件的顺序大概是这样的：

在请求过程中的任意时间，`onErrorOccurred` (en-US) 可以被触发。虽然有时候触发的事件顺序不同，举个例子，在火狐浏览器中的 HSTS 过程，在 onBeforeRequest 事件执行后，onBeforeRedirect 事件会被立即触发。

所有的事件，接受 `onErrorOccurred` 事件，`addListener()` 有三个参数：

* 监听本身
* 一个 `filter` 对象，所以你仅可以被特定请求或特定的资源类型提醒
* 一个可选的`extraInfoSpec`对象。你可以使用这个对象添加特定的事件命令

这个监听函数接收一个`details`对象，这个对象包含这个请求的信息。他包含一个请求 ID, 在插件中这个 ID 可以关联唯一个请求事件。这个 ID 是浏览器会话和插件上下文中唯一的。他始终在同一个请求中，贯穿着转发和授权等事件中。

在一个给定的主机上使用 webRequest API, 你必须有这个主机的相关权限，包括"webRequest" API permission 和 host permission. 为了使用 "blocking" 特性，你必须有 "webRequestBlocking" API 权限。

这个 webRequest API 不能让你进入一些安全敏感的请求，比如update checks and OCSP checks.

### Modifying requests

在下边这些事件中，你可以修改请求。比如一些特别的操作：

* 取消请求：
    + `onBeforeRequest` (en-US)
    + `onBeforeSendHeaders` (en-US)
    + `onAuthRequired` (en-US)
* 重定向请求：
    + `onBeforeRequest` (en-US)
    + `onHeadersReceived` (en-US)
* 修改请求头：
    + `onBeforeSendHeaders` (en-US)
* 修改响应头：
    + `onHeadersReceived` (en-US)
* 加入认证功能：
    + `onAuthRequired` (en-US)

为了完成这些操作，你需要在`extraInfoSpec`参数中添加"blocking"的值到事件的`addListener()`。这将使得监听器变成同步执行。在监听器中，你可以返回一个表明需要作修改的`BlockingResponse` (en-US)对象：比如说，你想要发送的修改后的请求头。

从 Firefox 52 开始，监听器会返回一个`resolve(BlockingResponse)` 的 `Promise`，而不是直接返回一个`BlockingResponse`。这使得监听器可以异步地处理请求。

Types
-----

`webRequest.ResourceType` (en-US)

Represents a particular kind of resource fetched in a web request.

`webRequest.RequestFilter`

An object describing filters to apply to webRequest events.

`webRequest.HttpHeaders` (en-US)

An array of HTTP headers. Each header is represented as an object with two properties: `name` and either `value` or `binaryValue`.

`webRequest.BlockingResponse` (en-US)

An object of this type is returned by event listeners that have set `"blocking"` in their `extraInfoSpec` argument. By setting particular properties in `BlockingResponse`, the listener can modify network requests.

`webRequest.UploadData` (en-US)

Contains data uploaded in a URL request.

Properties
----------

`webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES` (en-US)

The maximum number of times that `handlerBehaviorChanged()` (en-US) can be called in a 10 minute period.

Functions
---------

`webRequest.handlerBehaviorChanged()` (en-US)

This function can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.

Events
------

`webRequest.onBeforeRequest` (en-US)

Fired when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel or redirect the request.

`webRequest.onBeforeSendHeaders` (en-US)

Fired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers.

`webRequest.onSendHeaders` (en-US)

Fired just before sending headers. If your add-on or some other add-on modified headers in ``onBeforeSendHeaders` (en-US)`, you'll see the modified version here.

`webRequest.onHeadersReceived` (en-US)

Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.

`webRequest.onAuthRequired` (en-US)

Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.

`webRequest.onResponseStarted` (en-US)

Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.

`webRequest.onBeforeRedirect` (en-US)

Fired when a server-initiated redirect is about to occur.

`webRequest.onCompleted` (en-US)

Fired when a request is completed.

`webRequest.onErrorOccurred` (en-US)

Fired when an error occurs.

浏览器兼容性
------

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


contextMenus - Mozilla

contextMenus
============

在浏览器菜单中添加条目。此 API 基于 Chrome 的“contextMenus”API 构建，该 API 可让 Chrome 扩展程序将项目添加到浏览器的上下文菜单中。 `browser.menus` API 为 Chrome 的 API 添加了一些功能，特别是可以将项目添加到浏览器的“工具”菜单以及上下文菜单中。在 Firefox 55 之前，这个 API 最初也被命名为`contextMenus`，并且这个名字被保留为别名，所以你可以使用`contextMenus`编写在 Firefox 和其他浏览器中工作的代码。你需要拥有“menus”（或别名" contextMenus "）权限来使用此 API。创建菜单项
-----

使用 `menus.create()` (en-US)方法创建一个菜单项。你需要传递一个包含条目选项的对象，它包括条目的 id，类型，和需要显示出来的文本值。

绑定一个监听器到`contextMenus.onClicked` (en-US)事件来监听你菜单项目的点击事件。此监听器会传递一个`contextMenus.OnClickData` (en-US)，它包含该事件的详细信息。

你可以根据在调用`create()`时所传递的参数中使用不同的`type`值来创建四种不同类型的菜单：

* "normal"：只显示为一个标签的菜单项
* "checkbox"：一个表示二进制状态的菜单项。它在菜单项旁边显示一个复选标记。点击该菜单项切换复选标记。监听器会被传递两个额外的属性：“checked”，指示当前是否被选中，以及“wasChecked”，指示在此点击事件发生前是否被选中。
* "radio"：表示一组选项之一的上下文菜单项。类似于复选框，它也在菜单项旁边显示一个复选标记，监听它的监听器也会被传递“checked”和“wasChecked”。但是，如果你创建多个单选项，则这些项目将作为一组单选：组内只能选择一项，点击菜单项来选中它。
* "separator"：用于分割菜单的分割线。

如果你创建了多个上下文菜单项目或多个工具菜单项目，则这些项目将被放置在子菜单中。子菜单的父项将标有扩展名。例如，下面是一个名为“Menu Demo”的扩展，添加了两个上下文菜单项：

![](/zh-CN/docs/Mozilla/Add-ons/WebExtensions/API/menus/menus-1.png)

图标
--

如果你使用 "icons" manifest key 为你的扩展指定一个图标，你的菜单项的旁边就会显示一个指定的图标。浏览器会尝试在普通分辨率下使用 16 x 16 像素的图标，在高分辨率下使用 32 x 32 像素的图标：

![](/zh-CN/docs/Mozilla/Add-ons/WebExtensions/API/menus/menus-2.png) 你可以通过调用 `menus.create()` (en-US) 时指定 icons 选项来给子菜单项设置图标。

![](/zh-CN/docs/Mozilla/Add-ons/WebExtensions/API/menus/menus-3.png)

示例
--

下面是一个包含四个项目的菜单，他们分别是：一个普通选项，两个周围有分割线的单选，和一个复选框。单选框使用了自定义图标。

![](/zh-CN/docs/Mozilla/Add-ons/WebExtensions/API/menus/menus-4.png)

你可以使用以下代码创建一个这样的子菜单：

```js
browser.menus.create(
  {
    id: "remove-me",
    title: browser.i18n.getMessage("menuItemRemoveMe"),
    contexts: ["all"],
  },
  onCreated,
);

browser.menus.create(
  {
    id: "separator-1",
    type: "separator",
    contexts: ["all"],
  },
  onCreated,
);

browser.menus.create(
  {
    id: "greenify",
    type: "radio",
    title: browser.i18n.getMessage("menuItemGreenify"),
    contexts: ["all"],
    checked: true,
    icons: {
      16: "icons/paint-green-16.png",
      32: "icons/paint-green-32.png",
    },
  },
  onCreated,
);

browser.menus.create(
  {
    id: "bluify",
    type: "radio",
    title: browser.i18n.getMessage("menuItemBluify"),
    contexts: ["all"],
    checked: false,
    icons: {
      16: "icons/paint-blue-16.png",
      32: "icons/paint-blue-32.png",
    },
  },
  onCreated,
);

browser.menus.create(
  {
    id: "separator-2",
    type: "separator",
    contexts: ["all"],
  },
  onCreated,
);

var checkedState = true;

browser.menus.create(
  {
    id: "check-uncheck",
    type: "checkbox",
    title: browser.i18n.getMessage("menuItemUncheckMe"),
    contexts: ["all"],
    checked: checkedState,
  },
  onCreated,
);
```

类型
--

`contextMenus.ContextType` (en-US)

菜单里可以出现的不同内容。可能的值有："all", "audio", "browser\_action", "editable", "frame", "image", "link", "page", "page\_action", "password", "selection", "tab", "video".

`contextMenus.ItemType` (en-US)

菜单项的类别有："normal", "checkbox", "radio", "separator".

`contextMenus.OnClickData` (en-US)

当菜单项被点击时发送的信息。

属性
--

`contextMenus.ACTION_MENU_TOP_LEVEL_LIMIT` (en-US)

可以被添加进上下文菜单项的顶级扩展项的最大值，其 ContextType 可以是"browser\_action" 或者 "page\_action".

函数
--

`contextMenus.create()` (en-US)

创建一个新的上下文菜单项目。

`contextMenus.update()` (en-US)

更新一个已经创建了的上下文菜单项目。

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

删除一个上下文菜单项目。

`contextMenus.removeAll()` (en-US)

移除该插件创建的所有上下文菜单项目。

事件
--

`contextMenus.onClicked` (en-US)

当一个上下文菜单项被点击时触发。

浏览器兼容性
------

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

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

* menu-accesskey-visible
* menu-demo
* menu-labelled-open
* menu-remove-element
* menu-search
* session-state

**备注：** 此 API 基于 Chromium 的 `chrome.contextMenus` API. 此文档来自于 Chromium 代码中的`context_menus.json`。


contentScripts - Mozilla

contentScripts
==============

使用此 API 以注册内容脚本。“注册内容脚本”意味着浏览器会将给定的内容脚本插入到每个与给定的 URL 模式相匹配的页面中。

此 API 与 `manifest.json` 的 `"content_scripts"` 键非常相似，但 `"content_scripts"` 键所能注册的内容脚本是固定的，自拓展安装后便不可更改。但通过 `contentScripts` API，拓展可以在运行时动态地注册或取消注册脚本。

To use the API, call `contentScripts.register()` (en-US) passing in an object defining the scripts to register, the URL patterns, and other options. This returns a `Promise` that is resolved with a `contentScripts.RegisteredContentScript` (en-US) object.

The `RegisteredContentScript` object represents the scripts that were registered in the `register()` call. It defines an `unregister()` method that you can use to unregister the content scripts. Content scripts are also unregistered automatically when the page that created them is destroyed. For example, if they are registered from the background page they will be unregistered automatically when the background page is destroyed, and if they are registered from a sidebar or a popup, they will be unregistered automatically when the sidebar or popup is closed.

没有与 `contentScripts` API 相关联的权限，但是拓展必须拥有与其试图通过 `register()` 注册的脚本的匹配模式相对应的主机权限，才能实现注入。

类型
--

`contentScripts.RegisteredContentScript` (en-US)

`contentScripts.register()` (en-US) 函数会返回一个持有此类型的对象。它表示被通过调用此函数注册的内容脚本，可被用于取消注册对应的内容脚本。

函数
--

`contentScripts.register()` (en-US)

注册给定的内容脚本。

浏览器兼容性
------

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

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

* content-script-register


alarms - Mozilla

alarms
======

在未来一个特定的时间运行的计划任务代码。这很像`setTimeout()` (en-US)和`setInterval()` (en-US)，不过这些函数仅可以按需使用而不能在后台页面工作。

想要使用这个 API，你需要获取"alarms"的permission。

类型
--

`alarms.Alarm` (en-US)

Information about a particular alarm.

方法
--

`alarms.create()`

创建新的 alarm.

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

通过名称获取指定的 alarm.

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

获取所有的 alarm.

`alarms.clear()` (en-US)

清除指定名称的 alarm.

`alarms.clearAll()` (en-US)

清除所有的 alarm.

事件
--

`alarms.onAlarm` (en-US)

当 alarm 发生的时候触发。

浏览器兼容性
------

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

**备注：** The "Chrome incompatibilities" section is included from https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome\_incompatibilities using the WebExtChromeCompat macro.

If you need to update this content, edit https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome\_incompatibilities, then shift-refresh this page to see your changes.

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

* chill-out
* dynamic-theme

**备注：** This API is based on Chromium's `chrome.alarms` API.

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


browserAction - Mozilla

browserAction
=============

添加按钮到浏览器的工具栏。

你可以为该按钮指派一个弹出窗。弹出窗可采用 HTML、CSS 和 JavaScript 编写，就像是一个普通的网页。运行在该弹出窗中的 JavaScript 可以同你的后台脚本一样访问所有的 WebExtension API，但它的全局上下文是该弹出窗，而不是浏览器中的当前页面。要影响网页，你需要通过消息通信。

如果你指定了弹出窗，它将显示——内容将在用户点击该图标时被加载。如果你没有指定一个弹出窗，用户单击该图标的事件将派发到你的扩展。

你可以用 manifest.json 中的 `browser_action` 键值声明定义大多数浏览器动作属性。

使用 `browserAction` API，你可以：

* 使用 `browserAction.onClicked` (en-US) 监听该图标的点击事件。
* 获取和设置该图标的属性——图标、标题、弹出窗等。You can get and set these globally across all tabs, or for a specific tab by passing the tab ID as an additional argument.

另见用户界面组件 (en-US)中的浏览器动作章节。

类型
--

`browserAction.ColorArray` (en-US)

0-255 范围内的四个整数的数组，定义 RGBA 颜色。

`browserAction.ImageDataType` (en-US)

一个图像的像素数据。必须为一个 `ImageData` 对象（例如，来自一个 `<canvas>` 元素）。

函数
--

`browserAction.setTitle()` (en-US)

设置浏览器动作的标题。这将在工具提示（鼠标悬停时）显示。

`browserAction.getTitle()` (en-US)

获取浏览器动作的标题。

`browserAction.setIcon()` (en-US)

设置浏览器动作的图标。

`browserAction.setPopup()` (en-US)

设置 HTML 文档作为浏览器动作图标被用户点击时显示的弹出窗。

`browserAction.getPopup()` (en-US)

获取作为浏览器动作的弹出窗的 HTML 文档。

`browserAction.setBadgeText()` (en-US)

设置浏览器动作的徽章文本。该徽章显示在图标上方。

`browserAction.getBadgeText()` (en-US)

获取浏览器动作的徽章文本。

`browserAction.setBadgeBackgroundColor()` (en-US)

设置徽章的后台颜色。

`browserAction.getBadgeBackgroundColor()` (en-US)

获取徽章的后台颜色。

`browserAction.enable()` (en-US)

为一个标签页启用浏览器动作。默认情况下，浏览器动作为所有标签页启用。

`browserAction.disable()` (en-US)

为一个标签页禁用浏览器动作，使该标签页为活动时无法单击它。

事件
--

`browserAction.onClicked` (en-US)

在浏览器动作图标点击时被触发。如果浏览器动作有弹出窗，则该事件不会触发。

浏览器兼容性
------

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

**备注：** "Chrome 兼容性"是从 https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome\_incompatibilities 包含，使用WebExtChromeCompat宏。

如果你需要更新此章节，编辑 https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome\_incompatibilities，然后刷新查看更改。

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

* bookmark-it
* favourite-colour
* find-across-tabs
* forget-it
* google-userinfo
* native-messaging
* open-my-page-button
* permissions
* runtime-examples
* store-collected-images
* tabs-tabs-tabs

**备注：** 此 API 基于 Chromium 的 `chrome.browserAction` API。此文档派生自 Chromium 代码中的 `browser_action.json`。

Microsoft Edge 兼容性数据由微软公司提供，并以 知识共享 署名 3.0 美国版 许可。


i18n - Mozilla

i18n
====

国际化扩展的函数。你可以使用这些 api 从与扩展打包在一起的本地化文件中获取本地化字符串，查找浏览器的当前语言，并查找其 Accept-Language header头的值。

有关对扩展使用 i18n 的详细信息，请参阅：

* Internationalization国际化：使用 WebExtension i18n 系统的指南
* Locale-Specific Message reference (en-US): 扩展在 `messages.json`文件中提供特定于语言环境的字符串。此网页介绍`messages.json`
类型
--

`i18n.LanguageCode` (en-US)

一个语言标记 例如 `"en-US"` 或者 "`fr`".

方法
--

`i18n.getAcceptLanguages()` (en-US)

得到浏览器 支持的语言 。这与浏览器使用的区域设置不同。要获得区域设置，请使用`i18n.getUILanguage` (en-US).

`i18n.getMessage()` (en-US)

获取指定消息的本地化字符串。

`i18n.getUILanguage()` (en-US)

获取浏览器的用户界面语言。这与返回首选的用户语言 `i18n.getAcceptLanguages` (en-US) 不同。

`i18n.detectLanguage()` (en-US)

使用 Compact Language Detector属性检测所提供文本的语言。

浏览器兼容性
------

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

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

* menu-accesskey-visible
* menu-demo
* notify-link-clicks-i18n

**备注：** 这个 API 是基于 Chromium 的 `chrome.i18n` API，这个文档源自 Chromium 代码中的 `history.json` 。

微软 Edge 的兼容性数据由微软公司提供，并在这里收录在《知识共享 3.0 美国许可证》中。


bookmarks - Mozilla

bookmarks
=========

此WebExtensions `bookmarks` API 允许一个附加组件和浏览器的书签系统交互和操作。你可以用它给页面加书签，获取已有的书签，以及编辑，移除和管理书签。

欲使用此 API，一个附件组件必须请求"bookmarks" permission在它的`manifest.json`文件当中。

类型
--

`bookmarks.BookmarkTreeNode`

表示在书签树中的一个书签或者文件夹。

`bookmarks.BookmarkTreeNodeType` (en-US)

一个描述在树中的一个节点是否是一个书签，一个文件夹或是一个分割符的 `String` 枚举类型。

`bookmarks.BookmarkTreeNodeUnmodifiable` (en-US)

一个说明了为什么一个书签或者文件夹是不可修改的 `String` 枚举类型。

`bookmarks.CreateDetails` (en-US)

当创建一个新书签时，包含被传递给这个 `bookmarks.create()` (en-US) 函数的信息。

方法
--

`bookmarks.create()` (en-US)

创建一个书签或文件夹。

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

获得一个或者多个`BookmarkTreeNode`，提供一个书签的编号或者一个书签编号的数组。

`bookmarks.getChildren()` (en-US)

获取指定`BookmarkTreeNode`节点的所有子节点。

`bookmarks.getRecent()` (en-US)

获取最近添加的几个书签。

`bookmarks.getSubTree()` (en-US)

获取从指定节点开始的部分书签树。

`bookmarks.getTree()`

获取整个书签树。

`bookmarks.search()` (en-US)

搜索书签树节点，找出匹配的结果。如果以对象方式指定查询，得到的 BookmarkTreeNodes 匹配所有指定的属性。

`bookmarks.create()` (en-US)

在指定的上一级文件夹下创建新的书签或文件夹。如果 url 为 null 或者省略，则创建文件夹。

`bookmarks.move()` (en-US)

将指定的书签树节点移到指定位置

`bookmarks.update()` (en-US)

更新书签或文件夹的属性。只需要指定你需要更改的属性，未指定的属性不会更改。注意：目前只支持“title”和“url”属性。

`bookmarks.remove()`

删除书签或者空文件夹。

`bookmarks.removeTree()` (en-US)

删除整个书签文件夹。

`bookmarks.import()`

从一个 html 书签文件导入书签

`bookmarks.export()`

导出书签为一个 html 书签文件

事件
--

`bookmarks.onCreated` (en-US)

当书签或文件夹创建时产生。

`bookmarks.onRemoved` (en-US)

当删除书签或文件夹时产生。当删除整个文件夹（包括其中所有内容）时，仅为该文件夹发送通知，不为其中任何内容发送通知。

`bookmarks.onChanged` (en-US)

一个书签或文件夹更改时发生。注意：目前只有标题和 URL 更改时会触发这一事件。

`bookmarks.onMoved` (en-US)

当书签或文件夹移动到另一个父文件夹中时产生。

`bookmarks.onChildrenReordered` (en-US)

文件夹中的子节点在用户界面中调整顺序时产生。调用 move() 不会触发该事件。

`bookmarks.onImportBegan` (en-US)

开始导入书签时产生。复杂的事件处理函数在这一事件产生后不应该再处理 onCreated 事件，直到 onImportEnded 事件产生，在此过程中其他事件仍然应该立即处理。

`bookmarks.onImportEnded` (en-US)

书签导入结束时产生。

浏览器兼容性
------

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

**备注：** The "Chrome incompatibilities" section is included from https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome\_incompatibilities using the WebExtChromeCompat macro.

If you need to update this content, edit https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome\_incompatibilities, then shift-refresh this page to see your changes.

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

* bookmark-it

**备注：** This API is based on Chromium's `chrome.bookmarks` API. This documentation is derived from `bookmarks.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.


idle - Mozilla

idle
====

找出用户系统何时处于空闲，锁定或活动状态。

要使用此 API，你需要具有“空闲”权限。

类型
--

`idle.IdleState` (en-US)

描述设备空闲状态的字符串。

函数
--

`idle.queryState()` (en-US)

如果系统被锁定则返回“已锁定”，如果用户未在指定的秒数内生成任何输入，则返回“空闲”，否则返回“活动”。

`idle.setDetectionInterval()` (en-US)

设置用于确定系统何时处于 `idle.onStateChanged` (en-US) 事件的空闲状态的时间间隔。

事件
--

`idle.onStateChanged` (en-US)

当系统改变状态时触发。

浏览器兼容性
------

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

**备注：** 此 API 基于 Chromium 的 `chrome.idle` API。本文档源自 Chromium 代码中的 `idle.json` 。

Microsoft Edge 兼容性数据由 Microsoft Corporation 提供，并包含在 Creative Commons Attribution 3.0 United States License 下。

### 了解更多：

requestIdleCallback...


storage - Mozilla

storage
=======

使浏览器扩展能够储存及获取数据，以及监听储存的数据的变化。
此存储系统 API 基于 Web Storage API, 并有少许不同。

为了使用该 API，你需要在manifest.json文件包含"storage"权限。每一个浏览器扩展有自己的储存区域，每一个储存区域又分为几种不同的存储类型。

虽然此 API 类似于 `Window.localStorage`，但仍建议你不要在插件中使用 `Window.localStorage`。当用户由于隐私原因清除历史浏览记录及数据时，火狐会将在浏览器扩展使用 `localStorage API` 存储的数据一并清除。而使用 `storage.localAPI` 存储的数据将会恰当保留。

类型
--

`storage.StorageArea` (en-US)

代表存储区域的对象

`storage.StorageChange` (en-US)

代表改变一个储存区域的对象

属性
--

storage 有 3 个属性，每一个代表不同的存储区域。

`storage.sync` (en-US)

表示一个同步的储存区域。在此区域的数据通过浏览器进行同步，用户可通过登录使用不同的设备访问到浏览器所有可用的实例对象。

`storage.local` (en-US)

表示一个本地的存储区域。此区域的数据属于其所在的插件。

`storage.managed` (en-US)

表示管理的存储区域。此区域的数据由本域名下的管理员设置且对该插件是只读的。试图修改此区域数据会得到一个错误。

事件
--

`storage.onChanged` (en-US)

当 storage 有数据变化时，此事件将被触发。

浏览器兼容性
------

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

**备注：** "Chrome 不兼容"这部分来源于 https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome\_incompatibilities 使用WebExtChromeCompat macro.

如果需要更新这部分，请编辑 https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome\_incompatibilities, 然后刷新页面即可看见所做更改。

### 在 Edge 中的不兼容

Promises 在 Edge 中不被支持，使用 callbacks 代替。

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

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

**备注：** 这个 API 基于 Chromium 的 `chrome.storage` API. 这篇文档也来源于 Chromium 代码中的 `storage.json`.

Microsoft Edge 的适配数据由 Microsoft Corporation 提供并且被包含在 Creative Commons Attribution 3.0 United States License 许可证下。


windows - Mozilla

windows
=======

与浏览器窗口互动。你可以使用此 API 获取有关已打开窗口的信息，以及打开、修改和关闭窗口。你也可以监听窗口的打开、关闭和其激活事件。

类型
--

`windows.WindowType`

浏览器窗口的类型。

`windows.WindowState`

浏览器窗口的状态。

`windows.Window` (en-US)

有关一个浏览器窗口的信息。

`windows.CreateType` (en-US)

指定要创建的浏览器窗口的类型。

属性
--

`windows.WINDOW_ID_NONE` (en-US)

`windowId` 值表示不存在浏览器窗口。

`windows.WINDOW_ID_CURRENT` (en-US)

`windowId` 值表示当前窗口。

函数
--

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

指定其 ID，获取一个窗口的细节。

`windows.getCurrent()` (en-US)

获取当前窗口。

`windows.getLastFocused()` (en-US)

获取最近获得焦点的窗口，通常它是“顶部”的窗口。

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

获取所有窗口。

`windows.create()`

创建新窗口。

`windows.update()` (en-US)

更新一个窗口的属性。使用此项对移动、调整大小、聚焦/取消聚焦等。

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

关闭一个窗口及其所有标签页。

事件
--

`windows.onCreated` (en-US)

一个窗口创建时触发。

`windows.onRemoved` (en-US)

一个窗口关闭时触发。

`windows.onFocusChanged` (en-US)

当前有焦点的窗口改变时触发。

浏览器兼容性
------

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

### Edge 的不兼容

Edge 中不支持 Promises。需使用回调。

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

* annotate-page
* bookmark-it
* private-browsing-theme
* store-collected-images
* theme-integrated-sidebar
* window-manipulator

**备注：** 此 API 基于 Chromium 的 `chrome.windows` API。此文档基于 Chromium 代码中的 `windows.json`。

Microsoft Edge 兼容性数据由微软公司提供，并包含在创作共用 署名 3.0 美国许可证下。


cookies - Mozilla

cookies
=======

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

你需要在 manifest.json 文件中开启“cookies”API 权限，并且需要对应站点的 主机权限 才能设置指定站点的 cookie。详细信息查看 cookie 权限.

类型
--

`cookies.Cookie`

代表一个 HTTP cookie 的信息。

`cookies.CookieStore` (en-US)

代表一个保存在浏览器中的 cookie。

`cookies.OnChangedCause` (en-US)

代表 cookie 改变的原因。

方法
--

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

返回一个单独的 cookie 的信息。

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

返回所有符合筛选条件的 cookies。

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

根据给定 cookie 数据设置一个 cookie；如果同样的 cookie 存在讲会覆盖。

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

根据名字删除 cookie。

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

列出所有保存的 cookie。

事件句柄
----

`cookies.onChanged` (en-US)

当设置或删除 cookie 时触发。

权限
--

为了使用这个 API，插件必须在它的 manifest 中指定"cookies" API 权限，和它想要使用 cookie 的任何网站的 host 权限 。插件将能读取或写入 host 权限中所匹配的 URL 可以读取或写入的任何 cookie。例如：

`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，使用 callbacks 代替。

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

* cookie-bg-picker
* list-cookies

**备注：** 这个 API 基于 Chromium 的 `chrome.cookies` API. 这篇文档来源于 Chromium 代码的 `cookies.json` 。

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


runtime - Mozilla

runtime
=======

该模块提供关于附加组件以及运行环境的信息。

它提供一组消息通信 API，允许你：

* 在附加组件的不同模块间通信。
* 和其他的附加组件通信。
* 和 native 应用通信。
Types
-----

`runtime.Port` (en-US)

表示两个特定上下文之间的连接的一端，可用于交换消息。

`runtime.MessageSender` (en-US)

包含有关消息或连接请求的发件人的信息。

`runtime.PlatformOs`

标识浏览器的操作系统。

`runtime.PlatformArch`

标识浏览器的处理器架构。

`runtime.PlatformInfo` (en-US)

包含有关浏览器正在运行的平台的信息。

`runtime.RequestUpdateCheckStatus` (en-US)

`runtime.requestUpdateCheck()` (en-US) 的返回结果。

`runtime.OnInstalledReason` (en-US)

`runtime.onInstalled` (en-US) 事件被触发的原因。

`runtime.OnRestartRequiredReason` (en-US)

`runtime.onRestartRequired` (en-US) 事件被触发的原因。

Properties
----------

`runtime.lastError` (en-US)

当异步方法执行时发生了错误，它需要向其调用方报告时，该值会被设置。

`runtime.id` (en-US)

当前扩展的 ID。

Functions
---------

`runtime.getBackgroundPage()` (en-US)

取得当前扩展的后台页的 Window 对象。

`runtime.openOptionsPage()`

打开你的扩展的 选项页面。

`runtime.getManifest()`

获得完整的 manifest.json 声明文件的序列化对象。

`runtime.getURL()` (en-US)

给定某个打包在扩展中的资源的基于 manifest.json 相对路径，返回一个完整有效的 URL。

`runtime.setUninstallURL()` (en-US)

指定一个此扩展被卸载后打开的 URL。

`runtime.reload()` (en-US)

重新加载此扩展。

`runtime.requestUpdateCheck()` (en-US)

检查此扩展的更新。

`runtime.connect()` (en-US)

建立一个页面脚本到扩展主进程，或扩展主进程到页面脚本之间的通信连接。

`runtime.connectNative()`

建立一个浏览器扩展与用户电脑上的原生应用的通信连接。

`runtime.sendMessage()`

发送一条消息到此扩展或其他扩展的事件监听器，类似于 `runtime.connect` (en-US) 但只能发送一条消息，以及可选的响应处理函数。

`runtime.sendNativeMessage()`

从扩展发送一条消息到原生应用。

`runtime.getPlatformInfo()` (en-US)

返回当前所在平台的信息。

`runtime.getBrowserInfo()` (en-US)

返回此扩展所在的浏览器的信息。

`runtime.getPackageDirectoryEntry()` (en-US)

返回此扩展所在目录的 DirectoryEntry。

Events
------

`runtime.onStartup` (en-US)

当一个拥有此扩展的账户第一次启动时触发，注意若处于隐私模式中则不会触发。

`runtime.onInstalled` (en-US)

当扩展第一次安装，扩展更新，浏览器更新后触发。

`runtime.onSuspend` (en-US)

当扩展将被停止前触发，使得扩展可以执行一些清理工作。

`runtime.onSuspendCanceled` (en-US)

在此事件 `runtime.onSuspend` (en-US) 后触发，表明扩展最终没有被停止。

`runtime.onUpdateAvailable` (en-US)

当扩展更新可用时触发，注意若扩展运行中，更新不会马上被安装。

`runtime.onBrowserUpdateAvailable` (en-US)

当浏览器更新可用时触发，注意浏览器需要重启才能安装更新。

`runtime.onConnect`

与扩展进程或页面脚本（content script）建立通信连接时触发。

`runtime.onConnectExternal` (en-US)

与其他扩展建立通信连接时触发。

`runtime.onMessage` (en-US)

当收到扩展进程或页面脚本（content script）的消息时触发。

`runtime.onMessageExternal` (en-US)

当收到其他扩展的消息时触发，不能在页面脚本（content script）中使用。

`runtime.onRestartRequired` (en-US)

当设备要重启时触发。

Browser compatibility
---------------------

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

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

* beastify
* content-script-register
* cookie-bg-picker
* devtools-panels
* export-helpers
* favourite-colour
* find-across-tabs
* imagify
* menu-demo
* mocha-client-tests
* native-messaging
* notify-link-clicks-i18n
* permissions
* runtime-examples
* store-collected-images
* user-script-register
* webpack-modules

**备注：** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.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.


tabs - Mozilla

tabs
====

与浏览器标签系统进行交互。

你可以使用该 API 获取一个已打开标签的列表并且使用各种标准过滤标签，并进行 打开，刷新，移动，重载，移除操作。该 API 不能直接访问标签中的主机内容，但是你可以使用 `tabs.executeScript()` (en-US) 或者 `tabs.insertCSS()` APIs，来插入 javascript 和 CSS。

你可以在不需要任何特殊权限的情况下使用该 APIS 的大部分，除了：

* 获取 `Tab.url`, `Tab.title`, and `Tab.favIconUrl`, 你需要拥有 "tabs" 权限. 在火狐，这也意味着你需要 "tabs" ，来通过 URL 使用 `query`。
* 使用 `tabs.executeScript()` (en-US) 或者 `tabs.insertCSS()` 你必须在目标标签拥有 host permission 。

或者你可以仅仅只为当前的活动标签临时的获取这些权限并且仅仅只响应一个显示的用户行为，请查看 "activeTab" permission.

枚举值
---

`tabs.MutedInfoReason` (en-US)

确定一个标签静音与否的原因（用户修改，扩展修改）。

`tabs.MutedInfo` (en-US)

该对象包含一个布尔值只是该标签是否静音，以及最近一次静音的原因。

`tabs.Tab`

该值包含了一个标签的信息。

`tabs.TabStatus` (en-US)

指示某个标签是否已经加载完成

`tabs.WindowType` (en-US)

包含该标签的窗口类型。

`tabs.ZoomSettingsMode` (en-US)

定义缩放由浏览器控制或是扩展，或者禁用。

`tabs.ZoomSettingsScope` (en-US)

定义缩放将对某个网址持续生效，或者仅仅只针对该标签。

`tabs.ZoomSettings` (en-US)

定义缩放设置。 `mode` (en-US), `scope` (en-US), 和默认缩放比例。

属性
--

`tabs.TAB_ID_NONE` (en-US)

给予非浏览器标签的一个特殊 ID 值（比如，在开发工具中的标签）。

方法
--

`tabs.connect()` (en-US)

在运行于该标签的任何 content scripts 和该扩展的后台脚本（或者其他的比如弹出菜单脚本或者设置页面脚本）间创建一个消息连接。

`tabs.create()` (en-US)

创建一个新标签。

`tabs.captureVisibleTab()` (en-US)

创意一个数据统一资源标识符解码在规定窗口中当前活动标签的可视区域重的一个图片。

`tabs.detectLanguage()` (en-US)

检查在一个标签中的主要语言。

`tabs.duplicate()` (en-US)

复制一个标签

`tabs.executeScript()` (en-US)

向一个页面注入脚本。

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

取回制定标签的详细信息。

`tabs.getAllInWindow()` (en-US)
已弃用

获取指定窗口所有标签的详细信息。

`tabs.getCurrent()` (en-US)

返回一个 `tabs.Tab` 对象包含了该脚本当前的宿主标签的信息。

`tabs.getSelected()` (en-US)
已弃用

获取在指定窗口被选定的标签。

`tabs.getZoom()` (en-US)

获取制定标签的缩放系数。

`tabs.getZoomSettings()` (en-US)

获取指定标签的缩放设置。

`tabs.highlight()` (en-US)

高亮显示一个或多个标签。

`tabs.insertCSS()`

向一个页面注入 CSS。

`tabs.removeCSS()` (en-US)

移除之前调用`tabs.insertCSS()` 注入的一个 css。

`tabs.move()` (en-US)

移动一个或多个标签页到同一窗口的一个新的位置或是到不同窗口。

`tabs.query()`

获取所有包含指定属性的标签，如果没有属性则获取所有标签。

`tabs.reload()` (en-US)

重载一个标签，可选的可以绕过本地缓存。

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

关闭一个或多个标签。

`tabs.sendMessage()` (en-US)

向一个指定标签的 content script 发送单个消息。

`tabs.sendRequest()` (en-US)
已弃用

向一个指定标签的 content script 发送一个单一请求。 **过时**: 请使用 `tabs.sendMessage()` (en-US) 替代。

`tabs.setZoom()` (en-US)

缩放指定标签。

`tabs.setZoomSettings()` (en-US)

为一个制定标签设置缩放选项。

`tabs.update()` (en-US)

导航一个标签到新的地址，或是修改其他的属性。

Events
------

`tabs.onActivated`

当窗口活动标签改变时触发，注意当该消息触发时，标签地址可能没有被设置。

`tabs.onActiveChanged` (en-US)
已弃用

**已过时：** 请使用 `tabs.onActivated` 代替。

`tabs.onAttached` (en-US)

当一个标签被附加到一个窗口时触发，因为他可能在窗口间移动。

`tabs.onCreated` (en-US)

当一个标签被创建时触发，注意当该事件触发时可能没有设置地址。

`tabs.onDetached` (en-US)

当一个标签脱离一个窗口时被触发。

`tabs.onHighlightChanged` (en-US)
已弃用

**过时：** 请使用 `tabs.onHighlighted` (en-US) 代替。

`tabs.onHighlighted` (en-US)

当一个标签被高亮显示或是被选中时触发。

`tabs.onMoved` (en-US)

当一个标签在一个窗口内移动时被触发。

`tabs.onRemoved` (en-US)

当一个标签关闭时被触发。

`tabs.onReplaced` (en-US)

当一个标签因为预载取代另一个标签时被触发。

`tabs.onSelectionChanged` (en-US)
已弃用

**以过时：** 请使用 `tabs.onActivated` 代替。

`tabs.onUpdated` (en-US)

当一个标签被更新时触发。

`tabs.onZoomChange` (en-US)

当一个标签被缩放时触发

Browser compatibility
---------------------

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

**备注：** The "Chrome incompatibilities" section is included from https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome\_incompatibilities using the WebExtChromeCompat macro.

If you need to update this content, edit https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome\_incompatibilities, then shift-refresh this page to see your changes.

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

* annotate-page
* apply-css
* beastify
* bookmark-it
* chill-out
* commands
* context-menu-copy-link-with-types
* contextual-identities
* cookie-bg-picker
* devtools-panels
* find-across-tabs
* firefox-code-search
* history-deleter
* imagify
* list-cookies
* menu-demo
* menu-labelled-open
* menu-remove-element
* open-my-page-button
* permissions
* session-state
* store-collected-images
* tabs-tabs-tabs

**备注：** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.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.


webNavigation.onDOMContentLoaded - Mozilla

webNavigation.onDOMContentLoaded
================================

在页面中触发 DOMContentLoaded 事件时触发。此时，文档被加载和解析，并且 DOM 被完全构造，但链接的资源（例如图像、样式表和子框架）可能尚未被加载。

语法
--

```js
browser.webNavigation.onDOMContentLoaded.addListener(
  listener,                   // 函数
  filter                      // 可选对象
)
browser.webNavigation.onDOMContentLoaded.removeListener(listener)
browser.webNavigation.onDOMContentLoaded.hasListener(listener)
```

事件有三个方法：

`addListener(callback)`

为此事件添加监听方法。

`removeListener(listener)`

停止监听此事件。`listener` 参数为需要移除的监听器。

`hasListener(listener)`

检测是否有 `listener` 被注册在事件上。如有则返回 `true`，否则返回`false`。

addListener 语法
--------------

### 参数

`callback`

为当此事件发生时需要被调用的函数。该函数将传递以下参数：

`details`

`object`。有关导航事件的详细信息。参见 details 小节以获取更多信息。

`filter`可选

`object`。包含单个属性 `url` 的对象，这是一个 `events.UrlFilter` (en-US) `Array` 对象。如果包含此参数，则该事件将仅触发转换为与数组中至少一个 `UrlFilter` 匹配的 URL。如果省略此参数，则该事件将触发所有转换。

额外对象
----

### details

`tabId`

`integer`。发生导航事件的标签页 ID。

`url`

`string`。指定框架导航到的 URL。

`processId`

`integer`。渲染此选项卡的进程的 ID。

`frameId`

`integer`。发生导航的框架。0 表示导航发生在标签页的顶级浏览上下文中，而不是嵌套的 iframe 中。正值表示导航发生在嵌套的 iframe 中。对于给定的标签页和进程，框架 ID 是唯一的。

`timeStamp`

`number`。启动 `DOMContentLoaded` 的时间，单位为自纪元起的毫秒数。

浏览器兼容性
------

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

示例
--

如果目标 URL 的主机名包含“example.com”或以“developer”开头，则记录“onDOMContentLoaded”的目标 URL。

```js
const filter = {
  url: [{ hostContains: "example.com" }, { hostPrefix: "developer" }],
};

function logOnDOMContentLoaded(details) {
  console.log(`onDOMContentLoaded: ${details.url}`);
}

browser.webNavigation.onDOMContentLoaded.addListener(
  logOnDOMContentLoaded,
  filter,
);
```

**备注：** 本 API 基于 Chromium 的 `chrome.webNavigation` API。本文档源自 Chromium 代码中的 `web_navigation.json`。


cookies.Cookie - Mozilla

cookies.Cookie
==============

The `Cookie` type of the `cookies` API represents information about an HTTP cookie.

类型
--

这玩意是一个 Object，可以包含以下的属性：

`domain`

储存这个 cookie 对应网站的字符串 (例如 "www.tengxun.com")。

`expirationDate`可选

A `number` representing the expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.

`firstPartyDomain`

A `string` representing the first-party domain associated with the cookie. This will be an empty string if the cookie was set while first-party isolation was off. See First-party isolation.

`hostOnly`

A `boolean`, `true` if the cookie is a host-only cookie (i.e. the request's host must exactly match the domain of the cookie), or `false` otherwise.

`httpOnly`

A `boolean`, `true` if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts), or `false` otherwise.

`name`

A `string` representing the name of the cookie.

`path`

A `string` representing the path of the cookie.

`secure`

A `boolean`, `true` if the cookie is marked as secure (i.e. its scope is limited to secure channels, typically HTTPS), or `false` otherwise.

`session`

A `boolean`, `true` if the cookie is a session cookie, or `false` if it is a persistent cookie with an expiration date.

`sameSite`

A `cookies.SameSiteStatus` (en-US) value that indicates the SameSite state of the cookie.

`storeId`

A `string` representing the ID of the cookie store containing this cookie, as provided by `cookies.getAllCookieStores()` (en-US).

`value`

代表 cookie 的值的一个字符串。

Browser compatibility
---------------------

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

举例
--

Cookies API 中的大多数方法都将 `Cookie` 对象用作输入参数或用作返回值的一部分。例如调用 `cookies.getAll()` (en-US) 将会返回一个 `Cookie` 对象的数组。

在下面的例子中我们将会获取所有的 cookie，然后 `console.log()` 出这些 `Cookie` 对象所对应的值。

```js
function logCookies(cookies) {
  for (cookie of cookies) {
    console.log(`Domain: ${cookie.domain}`);
    console.log(`Name: ${cookie.name}`);
    console.log(`Value: ${cookie.value}`);
    console.log(`Persistent: ${!cookie.session}`);
  }
}

var gettingAll = browser.cookies.getAll({});
gettingAll.then(logCookies);
```

**备注：** 这 API 是基于 Chromium 的 `chrome.cookies` API 的。这个文档来自于 Chromium code 中的 `cookies.json` 。

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


clipboard.setImageData() - Mozilla

clipboard.setImageData()
========================

将图像复制到剪贴板。在将图像写入剪贴板之前，会对图像进行重新编码。如果图像无效，则不会修改剪贴板。

图像被作为包含经过编码的图像的 `ArrayBuffer` 提供。支持 JPEG 和 PNG 格式。

基于 Chrome 的 `clipboard.setImageData()` API，但存在一些差异：

* Chrome API 仅适用于应用，不适用于扩展程序。
* 此 API 需要 `"clipboardWrite"` 权限，Chrome 版本需要 `"clipboard"` 权限。
* Chrome 的 API 使用回调，此 API 使用 Promise。
* 此 API 不支持 `additionalItems` 参数。

这是一个返回 `Promise` 的异步函数。

语法
--

```js
browser.clipboard.setImageData(imageData, imageType);
```

### 参数

`imageData`

An `ArrayBuffer` containing the encoded image data to copy to the clipboard.

`imageType`

A `DOMString` indicating the type of image contained in `imageData`: `"png"` or `"jpeg"`.

### 返回值

A `Promise` that will be resolved with no arguments if the operation succeeded, or rejected if there was an error (for example, because the data did not represent a valid image).

浏览器兼容性
------

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

示例
--

Copy a remote image:

```js
// requires:
// \* the host permission for "https://cdn.mdn.mozilla.net/\*"
// \* the API permission "clipboardWrite"

fetch("https://cdn.mdn.mozilla.net/static/img/favicon144.png")
  .then((response) => response.arrayBuffer())
  .then((buffer) => browser.clipboard.setImageData(buffer, "png"));
```

Copy an image that was bundled with the extension:

```js
// requires the API permission "clipboardWrite"

fetch(browser.runtime.getURL("image.png"))
  .then((response) => response.arrayBuffer())
  .then((buffer) => browser.clipboard.setImageData(buffer, "png"));
```

**备注：** 此 API 基于 Chromium 的 `chrome.clipboard` API.


tabs.query() - Mozilla

tabs.query()
============

获取具有指定属性的所有标签页，如果未指定任何属性，则获取所有标签页。

这是一个返回 `Promise` 的异步函数。

语法
--

```js
let querying = browser.tabs.query(queryObj)
```

### 参数

`queryObj`

`object`。`query()` 函数将仅获取其属性与此处包含的属性相匹配的标签页。

请参阅 `tabs.Tab` 文档以了解有关这些属性的详细信息。

`active` 可选

`boolean`。标签页是否在窗口中处于活动状态。

`audible` 可选

`boolean`。标签页是否在播放声音。

`autoDiscardable` 可选

`boolean`。浏览器是否可以自动丢弃该标签页。默认值为 `true`。若设置为 `false`，则浏览器将不会自动丢弃该标签页。但是，标签页仍可使用 `tabs.discard` (en-US) 来丢弃。

`cookieStoreId` 可选

`string` 或 `string` 数组。使用它来返回 `tab.cookieStoreId` 与指定的任何 `cookieStoreId` 字符串相匹配的标签页。此选项仅在附加组件具有 `"cookies"` 权限时才可用。

`currentWindow` 可选

`boolean`。标签页是否在当前窗口中。

`discarded` 可选

`boolean`。标签页是否被丢弃。丢弃的标签页是指其内容已从内存中卸载，但仍在标签条中可见的标签页。其内容将下次激活时重新加载。

`hidden` 可选

`boolean`。标签页是否被隐藏。

`highlighted` 可选

`boolean`。标签页是否突出显示。

`index` 可选

`integer`。标签页在其窗口中的位置。

`muted` 可选

`boolean`。标签页是否静音。

`lastFocusedWindow` 可选

`boolean`。标签页是否在最近聚焦的（last focused）窗口中。

`pinned` 可选

`boolean`。标签页是否固定。

`status` 可选

`tabs.TabStatus` (en-US)。标签页是否已完成加载。

`title` 可选

`string`。将页面标题与模式进行匹配。需要“tabs”权限或匹配标签的主机权限。

`url` 可选

`string` 或 `string` 数组。将标签页与一个或多个匹配模式进行匹配。请注意，不会匹配片段标识符。需要“tabs”权限或匹配标签的主机权限。

`windowId` 可选

`integer`。父窗口的 ID，或 `windows.WINDOW_ID_CURRENT` (en-US)（用于当前窗口）。

`windowType` 可选

`tabs.WindowType` (en-US)。标签页所在窗口的类型。

### 返回值

一个将兑现为包含 `tabs.Tab` 对象（其中包含有关每个匹配的标签页的信息）的数组的 `Promise` 对象。

如果发生任何错误，promise 将以一条错误消息被拒绝。

示例
--

获取所有标签页：

```js
function logTabs(tabs) {
  for (const tab of tabs) {
    // tab.url 需要 `tabs` 权限或匹配的主机（host）权限。
    console.log(tab.url);
  }
}

function onError(error) {
  console.error(`错误：${error}`);
}

browser.tabs.query({}).then(logTabs, onError);
```

获取当前窗口中的所有标签页：

```js
function logTabs(tabs) {
  for (let tab of tabs) {
    // tab.url 需要 `tabs` 权限或匹配的主机权限。
    console.log(tab.url);
  }
}

function onError(error) {
  console.log(`错误：${error}`);
}

browser.tabs.query({ currentWindow: true }).then(logTabs, onError);
```

获取当前窗口中的活动标签页：

```js
function logTabs(tabs) {
  // tabs[0].url 需要 `tabs` 权限或匹配的主机权限。
  console.log(tabs[0].url);
}

function onError(error) {
  console.error(`错误：${error}`);
}

browser.tabs
  .query({ currentWindow: true, active: true })
  .then(logTabs, onError);
```

获取 `"mozilla.org"` 及其任何子域下所有 HTTP 和 HTTPS URL 的标签页：

```js
function logTabs(tabs) {
  for (const tab of tabs) {
    // tab.url 需要 `tabs` 权限或匹配的主机权限。
    console.log(tab.url);
  }
}

function onError(error) {
  console.error(`错误：${error}`);
}

browser.tabs.query({ url: "\*://\*.mozilla.org/\*" }).then(logTabs, onError);
```

### Example extensions

* annotate-page
* apply-css
* beastify
* bookmark-it
* chill-out
* contextual-identities
* cookie-bg-picker
* find-across-tabs
* history-deleter
* imagify
* list-cookies
* session-state
* tabs-tabs-tabs
浏览器兼容性
------

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

**备注：** 该 API 基于 Chromium 的 `chrome.tabs` API。本文档衍生自 Chromium 代码中的 `tabs.json`。


tabs.insertCSS() - Mozilla

tabs.insertCSS()
================

向一个页面注入 CSS

使用该 API 前你必须拥有目标页面的权限，可以是 主机权限, 或者使用 activeTab 权限.

你只能向符合 match pattern 的网页注入 CSS: 其形式必定是 "http", "https", "file", "ftp" 之一。你不能向任何浏览器内置页面注入 CSS，比如 about:debugging, about:addons, 或者你打开的一个新的空白页。

当再次调用`tabs.removeCSS()` (en-US) 时，已经注入的 CSS 可能会被清除。

这是一个返回`Promise` 的异步函数。

Syntax
------

```js
var inserting = browser.tabs.insertCSS(
  tabId, // optional integer
  details, // extensionTypes.InjectDetails
);
```

### 参数

`tabId` 可选

`integer`，将要注入 css 的标签 ID。默认为当前窗口的活动标签。

`details`

`extensionTypes.InjectDetails` (en-US). 对注入的描述，包含以下属性：

`allFrames`可选

`boolean`. 如果为真，该 CSS 会被注入到该页面的所有框架，如果为假，Css 只会注入到最顶层框架，默认为假。

`code`可选

`string`. 将要注入的代码。

`file`可选

`string`. 包含将要注入代码的文件路径，在 Firefox 中，相对 URLs 决定于当前页面的 URL，在 Chrome 中，决定于扩展的基础 URL。为了跨浏览器工作，你应该使用一个从扩展根目录开始的绝对路径，比如 : `"/path/to/stylesheet.css"`.

`frameId`可选

`integer`. CSS 应该被注入的框架。默认为 `0` (顶层框架).

`matchAboutBlank`可选

`boolean`. If `true`, the code will be injected into embedded "about:blank" and "about:srcdoc" frames if your add-on has access to their parent document. The code cannot be inserted in top-level about: frames. Defaults to `false`.

`runAt`可选

`extensionTypes.RunAt` (en-US). The soonest that the code will be injected into the tab. Defaults to "document\_idle".

### Return value

`Promise` 将会在 CSS 成功注入时 被填充，如果有任何错误发生，promise 将会被注入一个错误消息。

Browser compatibility
---------------------

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

示例
--

下面例子将通过字符串变量形式向当前活动标签注入一段 CSS 代码

```js
var css = "body { border: 20px dotted pink; }";

browser.browserAction.onClicked.addListener(() => {
  function onError(error) {
    console.log(`Error: ${error}`);
  }

  var insertingCSS = browser.tabs.insertCSS({ code: css });
  insertingCSS.then(null, onError);
});
```

下面例子将以通过加载文件形式向页面注入 CSS。CSS 被注入在 ID 为 2 的 tab 中。

```js
browser.browserAction.onClicked.addListener(() => {
  function onError(error) {
    console.log(`Error: ${error}`);
  }

  var insertingCSS = browser.tabs.insertCSS(2, { file: "content-style.css" });
  insertingCSS.then(null, onError);
});
```

### Example extensions

* apply-css
* beastify
* session-state

**备注：** 本页 API 以谷歌 Chromium 的 `chrome.tabs` API 为基础。该篇文档由 Chromium 代码 `tabs.json`衍变而来。

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


tabs.onActivated - Mozilla

tabs.onActivated
================

当窗体的活动标签变化时触发。请注意事件触发时标签的 URL 可能尚未设置，但是你可以通过监听 `tabs.onUpdated` (en-US) 事件在 URL 被设置后得到通知。

语法
--

```js
browser.tabs.onActivated.addListener(listener);
browser.tabs.onActivated.removeListener(listener);
browser.tabs.onActivated.hasListener(listener);
```

此事件有三个方法：

`addListener(callback)`

向此事件添加一个监听。

`removeListener(listener)`

停止监听此事件。 `listener` 参数是将要移除的监听。

`hasListener(listener)`

检查 `listener` 是否在此事件中注册。如果正在监听返回 `true` ，否则 `false`。

addListener 语法
--------------

### 参数

`callback`

事件发生时被执行的方法。以下参数会被传递至该方法：

`activeInfo`

`object`. 被激活标签的 ID , 以及它的窗体的 ID。

额外的对象
-----

### activeInfo

`tabId`

`integer`. 被激活的标签的 ID。

`windowId`

`integer`. 此标签的窗体的 ID。

浏览器兼容性
------

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

示例
--

监听并记录标签激活事件：

```js
function handleActivated(activeInfo) {
  console.log("Tab " + activeInfo.tabId + " was activated");
}

browser.tabs.onActivated.addListener(handleActivated);
```

### Example extensions

* annotate-page
* bookmark-it
* chill-out
* cookie-bg-picker

**备注：** This API is based on Chromium's `chrome.tabs` API. This documentation is derived from `tabs.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.


tabs.Tab - Mozilla

tabs.Tab
========

**`tabs.Tab`** 包含有关标签页的信息 . 这样可以访问有关标签页中的内容，内容有多大，特殊状态或限制有效的信息等等。

类型
--

这种类型的值是对象。它包含以下属性：

`active`

`boolean`. 该标签页是否在其窗口中处于活动状态。即使标签的窗口当前没有被关注，也可能是 true。

`audible` 可选

`boolean`. 如果标签页没有静音：标签页是否正在发出声音。如果标签页被静音：如果没有静音标签页是否会发出声音。

`autoDiscardable` 可选

`boolean`. 资源不足时浏览器是否可以自动丢弃该标签页。

`cookieStoreId` 可选

`string`. 该标签页的 Cookie 存储。如果不同的标签可以有不同的 cookie 存储 (例如，支持 contextual identity), 你可以将此作为 `storeId` 选项传递给 `cookies` API 的各种方法，设置和获取与此标签页的 Cookie 存储关联的 Cookie。只有在扩展具有“cookies”权限的情况下才会出现。

`discarded` 可选

`boolean`. 是否丢弃的标签页。被丢弃的标签页是其内容已经从内存中卸载的标签页，但在标签页条中仍可见。它的内容在下一次被激活时被重新加载。

`favIconUrl` 可选

`string`. 该标签的图标的网址。只有在扩展具有“cookies”权限的情况下才会出现。如果标签页正在加载中，该值可以为空字符串

`height` 可选

`integer`. 标签页的像素单位高度。

`highlighted`

`boolean`. 标签页是否突出显示。

`id` 可选

`integer`. 标签页的 ID. 标签 ID 在浏览器的会话中是唯一的。在浏览器窗口中不包含内容的标签页 (例如，devtools 窗口),标签 ID 也可以设置为 `tabs.TAB_ID_NONE` (en-US) 。

`incognito`

`boolean`. 该标签页是否在隐私浏览窗口中。

`index`

`integer`. 窗口中的标签页从零开始的索引。

`isArticle`

`boolean`. 如果标签页可以在 Reader 模式下呈现，则返回 true，否则返回 false。

`isInReaderMode`

`boolean`. 如果标签页正在 Reader 模式下呈现，则返回 true，否则返回 false。

`lastAccessed`

`double`. 上次访问该标签页的时间 , 参考 milliseconds since the epoch.

`mutedInfo` 可选

`tabs.MutedInfo` (en-US).标签页的当前静音状态以及上次状态更改的原因。

`openerTabId` 可选

`integer`. 打开此标签页的标签页 ID（如果有）。如果开启者标签页仍然存在，该属性才会出现。

`pinned`

`boolean`. 标签页是否被固定

`selected`
已弃用

`boolean`.标签页是否被选中

`sessionId` 可选

`string`. 从`sessions` (en-US) API 获取的标签页的唯一标识会话 ID.

`status` 可选

`string`.*加载* 或 *完成*.

`title` 可选

`string`. 标签页的标题。只有当扩展具有 `"tabs"` 权限 时才会出现。

`url` 可选

`string`. 该选项卡正在显示的文档的 URL。只有当扩展具有 `"tabs"` 权限 时才会出现。

`width` 可选

`integer`. 标签页的像素单位宽度。

`windowId`

`integer`. 包含此标签页的窗口 ID。

浏览器兼容性
------

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

### Example extensions

* annotate-page
* apply-css
* beastify
* bookmark-it
* cookie-bg-picker
* find-across-tabs
* tabs-tabs-tabs

**备注：** 此 API 基于 Chromium 的 `chrome.tabs` API. 本文档来源于 Chromium 代码中的 `tabs.json`.

Microsoft Edge 兼容性数据由 Microsoft Corporation 提供，并包含在 Creative Commons Attribution 3.0 美国许可证下。


windows.WindowType - Mozilla

windows.WindowType
==================

浏览器窗口的类型。

Type
----

类型的值是字符串类型。可能的值如下：

* `"normal"`
* `"popup"`
* `"panel"`
* `"devtools"`
浏览器适配
-----

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

**备注：** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.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.


windows.WindowState - Mozilla

windows.WindowState
===================

浏览器窗口的状态。

类型
--

类型的值是字符串类型。可能的值如下：

* `"normal"`
* `"minimized"`
* `"maximized"`
* `"fullscreen"`
* `"docked"`
浏览器适配
-----

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

**备注：** 此 API 基于谷歌浏览器 `chrome.windows` API。此文档源于谷歌源码 `windows.json` .

微软 Edge 浏览器兼容性数据由微软公司提供，并包含在美国 Creative Commons Attribution 3.0 许可证下。


windows.create() - Mozilla

windows.create()
================

创建一个新的窗口。

当你创建一个窗口时，你可以：

* 加载一个或多个新的标签到该窗口中。
* 将一个现有窗口的。标签移动到新的窗口中
* 设置窗口的大小和位置
* 创建一个面板样式的窗口，它没有浏览器的默认样式（地址栏，工具栏等）
* 设置窗口的多种属性，像是获得焦点或是为隐私窗口。

这是一个异步的方法返回一个 `Promise`.

语法
--

```js
var creating = browser.windows.create(
  createData, // optional object
);
```

### 参数

`createData`可选

`object`.

`url`可选

字符串或字符串数组。一个 URL 或都 URL 数组要在该窗口中打开成标签页的。完整的需要包括 scheme (像。`http://www.google.com`, not `www.google.com`). 相对路径将相对于该拓展中的当前页。默认为打开新标签页。

`tabId`可选

`integer`. 如果设置了该值，将该 tab 从一个现有的窗口中移到新窗口中。

`left`可选

`integer`. 窗口左边到屏幕左边缘的距离。如果没有设定，新窗口将按上一个焦点窗口定位水平位置。对于 panel 样式窗口，该值不起作用。

`top`可选

窗口顶部到屏幕的顶部距离。如果没有设定，新窗口将按上一个焦点窗口定位垂直位置。对于 panel 样式窗口，该值不起作用。

`width`可选

`integer`. 新窗口的宽度，包含框架。未设定则使用默认宽度。

`height`可选

`integer`. 新窗口的高度，包含框架。未设定则使用默认高度。

`focused`可选

`boolean`.如果 为`true`, 新窗口将获取焦点。否则新窗口当在后台打开并且当前焦点窗口继续保持焦点。默认为 true

`incognito`可选

`boolean`。是否打开为一个隐私窗口。如果设定为隐私窗口并且引入了 `tabId`, 则 tabId 对应的标签必须是一个隐私标签— 即不能把一个不是隐私标签的标签页移动到隐私窗口中。

`type`可选

一`windows.CreateType` (en-US) 值，表示创建窗口的类型。`panel` 或者`popup` 样式将打开一个没有默认浏览器样式的窗口 (地址栏，工具栏等）。

`state`可选

一个 `windows.WindowState` 值，窗口的祲状态。最小化、最大化、全屏状态不能与`left`, `top`, `width`, or `height`属性一起使用。

### 返回值

一个 `Promise` 其中传入一个包含新窗口细节的 `windows.Window` (en-US) 对象。这个`windows.Window` (en-US) 有自己的 tabs 属性集 ,而不像 `windows.get()` (en-US)返回的窗口对象和相似的 API, 如果传递了 populate 项其仅仅包含 tabs. 如果发生了错误 promise will be rejected with an error message.

示例
--

打开一个包含两个标签的窗口

```js
function onCreated(windowInfo) {
  console.log(`Created window: ${windowInfo.id}`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

browser.browserAction.onClicked.addListener((tab) => {
  var creating = browser.windows.create({
    url: ["https://developer.mozilla.org", "https://addons.mozilla.org"],
  });
  creating.then(onCreated, onError);
});
```

当用户点击一个 browser action 打开一个窗口，并且将当前活跃的标签移动其中

```js
function onCreated(windowInfo) {
  console.log(`Created window: ${windowInfo.id}`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

browser.browserAction.onClicked.addListener((tab) => {
  var creating = browser.windows.create({
    tabId: tab.id,
  });
  creating.then(onCreated, onError);
});
```

打开一个小面板样式的窗口，并且加载一个本地包中的文件到其中

```js
function onCreated(windowInfo) {
  console.log(`Created window: ${windowInfo.id}`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

browser.browserAction.onClicked.addListener((tab) => {
  var popupURL = browser.extension.getURL("popup/popup.html");

  var creating = browser.windows.create({
    url: popupURL,
    type: "popup",
    height: 200,
    width: 200,
  });
  creating.then(onCreated, onError);
});
```

浏览器兼容性
------

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

### Example extensions

* store-collected-images
* window-manipulator

**备注：** This API is based on Chromium's `chrome.windows` API. This documentation is derived from `windows.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.


downloads.download() - Mozilla

downloads.download()
====================

`downloads` API 的 **`download()`** 函数根据给出的 URL 和其他首选项下载一个文件。

* 如果指定的 `url` 使用 HTTP 或者 HTTPS 协议，那么下载请求将会包含当前为该域名所设置的所有 cookie。
* 如果`filename` 和 `saveAs` 都已经指定，那么将会弹出“保存为”对话框，并且默认名称显示为`filename`.

这是一个异步函数，其返回值为 `Promise`.

语法
--

```js
var downloading = browser.downloads.download(
  options, // object
);
```

### 参数

`options`

一个 `object` ，用来指定你想要下载的文件和其他想要在下载时设置的首选项。可以包含以下属性：

`allowHttpErrors`可选

一个 `boolean`，启用后即使遇到 HTTP 错误仍然继续下载。例如，可以使用该标志下载服务错误页面。默认值为`false`. 当设置为以下值时：

* `false`,遇到 HTTP 错误时下载会被取消。
* `true`, 即使遇到 HTTP 错误也会继续下载，并且不会弹出 HTTP 服务错误报告。但是，如果下载失败的原因是文件相关，网络相关，用户相关，或者说其他错误，仍然会报错。

`body`可选

一个 `string`，代表请求的内容。

`conflictAction`可选

一个字符串，表示如果存在命名冲突时你希望进行的操作，字符串内容所代表的类型由 `downloads.FilenameConflictAction` (en-US) 定义 (未指定时默认为 "uniquify" )。

`filename`可选

一个 `string` ，表示相对默认保存位置的文件路径——这里提供你希望文件保存的位置，和你想要使用的文件名。绝对路径，空路径，以及包含反向引用的路径 (`../`) 会导致错误产生。如果省略，该值将默认为已经提供给下载文件的文件名，并且直接保存到下载文件夹中。

`headers`可选

如果 URL 使用 HTTP 或者 HTTPS 协议，保存在 `array` 中的一系列 `objects` 表示与请求一起发送的额外 HTTP 请求头。每一个请求头表示为字典对象，包含有关键字 `name` 还有 `value`或`binaryValue`中的一个。无法指定 `XMLHttpRequest`和 `fetch`禁止的请求头，但是 Firefox 70 之后允许使用`Referer`请求头。尝试使用被禁止的请求头会产生一个错误。

`incognito`可选

一个 `boolean`：如果被设置为 true，那么这次下载会建立一个隐私浏览会话。这意味着它只会出现在当前打开的任意隐私窗口的下载管理器。

`method`可选

一个 `string`，表示`url`使用 HTTP[S] 协议时使用的 HTTP 方法。其值可能是 "GET" 或 "POST"。

`saveAs`可选

一个`boolean` 指定是 (`true`) 否 (`false`) 提供一个文件选择对话框允许用户选择文件名。.

如果该选项省略，浏览器会根据用户对于该行为的偏好设置决定是否提供一个文件选择对话框 (在火狐这项设置标签在 about:preferences 里为"每次都问你要存到哪" ，或者 about:config 里 `browser.download.useDownloadDir` )。

**备注：** 如果 `saveAs` 被设置为 `true`，Firefox for Android 将会引发一个错误。当 `saveAs` 为 `false` 或空时这个参数会被忽略。

`url`

一个 `string`，表示需要下载的链接地址。

### 返回值

一个 `Promise`. 如果成功开始下载，promise 会被新创建的`downloads.DownloadItem` 的 `id` 填充。否则 promise 会被拒绝并产生一条`downloads.InterruptReason` (en-US)错误信息。

如果你使用 URL.createObjectURL() 下载由 JavaScript 创建的数据并且之后想要 (使用 revokeObjectURL) 撤销对象链接 (并且强烈推荐这么做)，你必须在下载完成后再这么做。监听 downloads.onChanged (en-US) 事件来判断是否下载完成。

浏览器兼容性
------

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

示例
--

下面这段代码尝试下载一个 example 文件，同时指定文件名和保存位置，还有 `uniquify` `conflictAction` 选项。

```js
function onStartedDownload(id) {
  console.log(`Started downloading: ${id}`);
}

function onFailed(error) {
  console.log(`Download failed: ${error}`);
}

var downloadUrl = "https://example.org/image.png";

var downloading = browser.downloads.download({
  url: downloadUrl,
  filename: "my-image-again.png",
  conflictAction: "uniquify",
});

downloading.then(onStartedDownload, onFailed);
```

**备注：** 这个 API 基于 Chromium 的 `chrome.downloads` API.


downloads.DownloadItem - Mozilla

downloads.DownloadItem
======================

`downloads` API 的 `DownloadItem` 类代表了一个被下载的文件。

Type
----

这个类型的值是对象，包含了以下属性：

`byExtensionId`可选

一个代表了触发此下载的扩展的 ID 的 `string` （如果是被扩展触发的话）。一旦设置，不会改变。如果下载不是由扩展触发的，则为 undefined。

`byExtensionName`可选

一个代表了触发此下载的扩展的名字的 `string` （如果是被扩展触发的话）。如果用户改变了扩展的语言环境，则这个属性的值也可能变化。如果下载不是由扩展触发的，则为 undefined。

`bytesReceived`

一个代表了在下载过程中从主机接收到的字节数的 `number` ；不考虑文件压缩。

`canResume`

一个标识当前中断（例如暂停）的下载是否可以从当前位置恢复的 `boolean`。

`danger`

一个标识这个下载是否通过一个不安全的或已知的可疑的站点。可能被设置为 `downloads.DangerType` (en-US) 类型。

`endTime`可选

A `string` (in ISO 8601 format) representing the number of milliseconds between the UNIX epoch and when this download ended. This is undefined if the download has not yet finished.

`error`可选

A string indicating why a download was interrupted. Possible values are defined in the `downloads.InterruptReason` (en-US) type. This is undefined if an error has not occurred.

`estimatedEndTime`可选

A `string` (in ISO 8601 format) representing the estimated number of milliseconds between the UNIX epoch and when this download is estimated to be completed. This is undefined if it is not known (in particular, it is undefined in the `DownloadItem` that's passed into `downloads.onCreated` (en-US)).

`exists`

A `boolean` indicating whether a downloaded file still exists (`true`) or not (`false`). This information might be out-of-date, as browsers do not automatically watch for file removal — to check whether a file exists, call the `downloads.search()` (en-US) method, filtering for the file in question.

`filename`

A `string` representing the file's absolute local path.

`fileSize`

A `number` indicating the total number of bytes in the whole file, after decompression. A value of -1 here means that the total file size is unknown.

`id`

An `integer` representing a unique identifier for the downloaded file that is persistent across browser sessions.

`incognito`

A `boolean` that indicates whether the download is recorded in the browser's history (`false`), or not (`true`).

`mime`

A `string` representing the downloaded file's MIME type.

`paused`

A `boolean` indicating whether the download is paused, i.e. if the download has stopped reading data from the host but has kept the connection open. If so, the value is `true`, `false` if not.

`referrer`

A `string` representing the downloaded file's referrer.

`startTime`

A `string` (in ISO 8601 format) representing the number of milliseconds between the UNIX epoch and when this download began.

`state`

A `string` Indicating whether the download is progressing, interrupted, or complete. Possible values are defined in the `downloads.State` (en-US) type.

`totalBytes`

A `number` indicating the total number of bytes in the file being downloaded. This does not take file compression into consideration. A value of -1 here means that the total number of bytes is unknown.

`url`

A `string` representing the absolute URL from which the file was downloaded.

Browser compatibility
---------------------

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

**备注：** This API is based on Chromium's `chrome.downloads` API.

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


获取处理器架构 - runtime.PlatformArch - Mozilla

获取处理器架构 - runtime.PlatformArch
==============================

当前浏览器所在的计算机的处理器架构。

值类型
---

该值的类型是字符串。可能的值如下：

`"arm"`

标识平台基于 arm 架构。

`"x86-32"`

表示平台基于 x86 32-bit 架构。

`"x86-64"`

表示平台基于 x86 64-bit 架构。

浏览器兼容性
------

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

**备注：** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.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.