recursal/MDN huggingface dataset:
User interface
==============

为了能给用户提供在不同场景下都具有价值的功能，WebExtensions 提供了许多的用户界面选项。下面是这些选项的摘要，在本章中将会对每个选项做出更详细的说明。

**备注：** 想要使你的扩展能提供良好的用户体验吗？请查看文章用户体验的最佳实践 .


| UI 选项 | 描述 | 实例 |
| --- | --- | --- |
| 浏览器工具栏按钮(浏览器行为) | 工具栏上一个可点击的按钮，点击时将事件派发到附件组件上。默认情况下，这个按钮在栏位中是可见的。 | Example of a WebExtension toolbar button |
| 带有弹出面板的工具栏按钮 | 
 当这个在工具栏上的按钮被点击时，它会弹出一个面板。这个面板使用 HTML
 文档编写，用于处理与用户的交互行为。
  | Example of a WebExtension toolbar button with a popup |
| 地址栏菜单按钮(页面行为) | 
 这个按钮位于浏览器地址栏菜单条，按钮被点击的时候可以派发一个事件出来。默认情况下，这个按钮在所有
 tab 上都是隐藏的。
  | Example showing an address bar button (page action) |
| 带有弹出面板 (en-US)的地址栏菜单按钮 | 
 地址栏菜单按钮被点击时，会弹出一个面板，这个面板通过 HTML
 文档定义，用于处理用户交互。
  | Example of a popup on the address bar button |
| 上下文菜单项 (en-US) | 在一个或多个网页上下文菜单中的菜单项，复选框和单选按钮。菜单项也可以通过添加分隔栏进行分组，当一个菜单项被点击时，一个事件将会被派发至附加组件。 |  |
| 侧边栏 (en-US) | 
 一个在网页边显示的 HTML
 文档，每页都有其特定的内容。每当扩展安装时侧边栏将会打开，但最终还是遵循用户的侧边栏可见性设置。侧边栏内的用户交互通过
 HTML 文档处理。
  | Example of a WebExtension's sidebar |
| 选项页面 (en-US) | 一个可以使你定义可以更改的扩展首选项的页面。用户可以从浏览器的附加组件管理器中访问此页面。 | Example showing the options page content added in the favorite colors example. |
| 扩展页面 (en-US) | 在单独的窗口或页面中使用扩展提供的页面来提供表单，帮助或其他任何需要的内容。 | Example of a simple bundled page displayed as a detached panel. |
| 通知 | 
 通过底层操作系统的通知机制向用户显示的短暂通知。当用户点击或者通知关闭时
 (用户关闭或超时关闭) 派发事件到扩展程序。
  | Example notification from a WebExtension |
| 地址栏建议 (en-US) | 当用户输入关键词时提供自定义的地址栏建议。 | Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions. |
| 开发者工具面板 (en-US) | 在浏览器的开发者工具中显示的一个关联了 HTML 文档的标签。 | New panel tab in the Developer Tools tab bar |

以下的操作指南提供了一些创建用户界面选项的指导;

* 在工具栏中添加一个按钮
* 实现一个设置页面
* 扩展开发人员工具
* 浏览器样式
你的第一个拓展
=======

**备注：** 如果你熟悉浏览器扩展的基本概念，你可以跳过这一章节，去阅读如何把扩展文件组合在一起。然后，阅读参考文档以构建你的扩展。访问 Firefox 扩展工作站，了解有关 Firefox 扩展测试、发布等更多信息。

在这篇文章中，我们将为 Firefox 创建一个扩展。这个扩展只是给从“`mozilla.org`”或其任意子域名加载的任何页面添加一个红色边框。

该示例的源代码位于 GitHub：https://github.com/mdn/webextensions-examples/tree/main/borderify

编写扩展
----

创建一个新的目录并切换到该目录。例如，在你的命令行或者终端，你可以这么做：


```bash
mkdir borderify
cd borderify
```

### manifest.json

现在，在“borderify”目录内直接创建文件“manifest.json”。文件内容如下：


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

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

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

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


* 前三个键：`manifest_version`、`name` 和 `version` 是必须的，包含有扩展的基本元数据。
* `description` 是可选的，但建议使用：该描述将显示在附加组件管理器上。
* `icons` 是可选的，但建议使用：它允许你给扩展指定一个图标，将显示在附加组件管理器上。

这里最有意思的键是 `content_scripts`（内容脚本），它告诉 Firefox 加载脚本到其 URL 匹配特定模式的网页。本例中，我们要求 Firefox 加载脚本“borderify.js”到任何来自“mozilla.org”或其子域的 HTTP 或 HTTPS 页面。

* 进一步了解内容脚本
* 进一步了解模式匹配

**警告：** 某些情况下，你需要给你的扩展指定一个 ID。如果你需要指定一个附加组件 ID，请在 `manifest.json` 中添加 `browser_specific_settings` 键，并设置其 `gecko.id` 属性：


```json
"browser\_specific\_settings": {
  "gecko": {
    "id": "borderify@example.com"
  }
}
```


### icons/border-48.png

扩展应该有一个图标。这将显示在附加组件管理器加载项的列表中。我们的 manifest.json 保证了会有一个图标“icons/border-48.png”。

在“borderify”目录下直接创建“icons”目录，并在“icons”目录下保存一个名为“border-48.png”的图标。你可以使用我们示例中的图标，来自谷歌 Material Design 的图标库，遵循 Creative Commons Attribution-ShareAlike 协议。

如果你选择使用自己的图标，它也应该是 48×48 像素的。你也可以为高分辨率显示器提供一个 96x96 的像素图标，在 manifest.json 的 `icons` 对象中添加 `96` 属性即可：


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


或者，也可以在这里提供一个 SVG 文件，它会被正确地缩放。（不过：如果你正在使用 SVG 并且你的图标包含文字，你可能需要使用 SVG 编辑器的“转换为路径”工具来使文字扁平化，这样图标会以一个恒定的大小或位置来缩放。）

* 了解更多关于指定图标的内容
### borderify.js

最后，在“borderify”目录下直接创建“borderify.js”文件，并写入下面的内容：


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


manifest.json 文件中 `content_scripts` 的键给出了一条模式匹配，该脚本便会被加载到匹配的页面中。该脚本会像页面加载自己的脚本一样被加载，可以直接访问该文档。

* 了解更多关于内容脚本的内容。
测试一下
----

首先，仔细检查文件是否在正确的位置：
```

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

### 安装

打开 Firefox 的 about:debugging 页面，点击“This Firefox”，点击“临时加载附加组件（Load Temporary Add-on）”按钮，并选择你的扩展所在的目录：

附加组件将会被安装，直到下次重启浏览器失效。

或者，你可以通过 web-ext 工具从命令行来运行扩展。

### 测试

**备注：** 默认情况下扩展在隐私浏览模式中不起作用

现在尝试访问“mozilla.org”，你将会在页面上看到有个红色的边框。

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

**备注：** 不要在“`addons.mozilla.org`”上尝试！内容脚本当前在那个域名下是被限制的。

尝试一下编辑内容脚本更改边框的颜色，或做页面内容别的修改，保存内容脚本，然后通过单击 **about:debugging** 页面下的“刷新”按钮重新加载附加的文件。你可以马上看到的变化：

* 了解更多关于加载附加组件的信息
打包和发布
-----

为了给其他人使用你的插件，你需要打包，并将其提交给 Mozilla 进行签名。要了解更多有关，请参考“发布你的扩展” (en-US)。

下一步
---

现在，你已经在开发 Firefox 的一个 Web 扩展的过程中得到了一些想法，尝试：

* 写一个更加复杂的扩展
* 阅读更多关于扩展的内容
* 探索更多关于扩展的示例
* 发现开发，测试，和发布扩展需要的知识
* 进一步的学习
为 Thunderbird 开发 WebExtension
=============================

你将采用与 Firefox 扩展相同的方式对 Thunderbird 扩展进行代码编写；使用你选择的文本编辑器工具来编写代码。

API 差异
------

**备注：** 查看 ReadTheDocs 了解 Thunderbird 特定的 WebExtension API 文档。

因为都基于 Gecko，Thunderbird 支持许多 Firefox 支持的 API，但有一些区别，查看 manifest.json 的浏览器兼容性和 JavaScript API 的浏览器支持了解详情。

参见
--

* Thunderbird 附加组件开发的介绍
* Thunderbird 的 WebExtension API 文档
* JavaScript API 的浏览器支持
* manifest.json 的浏览器兼容性
下一步是什么？
=======

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

你可以在扩展工坊上找到更多本页讨论的相关内容，这是一个致力于帮助编写、测试、发布和分发 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 开发者社区的详细介绍
地址栏按钮
=====

通常来说的 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
==============

 常说的 浏览器动作（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 实现了浏览器动作。
通知
==

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

![](/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
=======

使用 `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
=========

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
=====

**警告：** 不推荐使用 `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
=========

启用与浏览器的下载管理器交互的扩展。你可以使用这个 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
====

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

要使用此 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.
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
======

在未来一个特定的时间运行的计划任务代码。这很像`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
=============

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

你可以为该按钮指派一个弹出窗。弹出窗可采用 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
====

国际化扩展的函数。你可以使用这些 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 美国许可证》中。