recursal/MDN huggingface dataset:
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
==================

浏览器窗口的类型。

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

浏览器窗口的状态。

类型
--

类型的值是字符串类型。可能的值如下：

* `"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()
================

创建一个新的窗口。

当你创建一个窗口时，你可以：

* 加载一个或多个新的标签到该窗口中。
* 将一个现有窗口的。标签移动到新的窗口中
* 设置窗口的大小和位置
* 创建一个面板样式的窗口，它没有浏览器的默认样式（地址栏，工具栏等）
* 设置窗口的多种属性，像是获得焦点或是为隐私窗口。

这是一个异步的方法返回一个 `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()
====================

`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.
获取处理器架构 - 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.
runtime.sendNativeMessage()
===========================

从 WebExtension 发送单条消息到 native application。

它需要两个强制的参数：native application 的名字和要发送给它的 JSON 对象。浏览器将会加载 native application 然后发送这个消息。

这是一个异步函数，返回一个 `Promise`对象。native application 发送的第一条消息将被当作`sendNativeMessage()` 的回复，并且 promise 将这个消息作为参数.。注意你不能使用 `runtime.onMessage` (en-US) 从应用获取回复：你必须使用回调函数来替代。

每次调用 `runtime.sendNativeMessage()`都会生成一个新的实例。浏览器将会在收到回复后结束这个 native application。为了结束这个 native application，浏览器将会关闭 pipe，并给进程几秒的时间优雅的退出，如果它没有关闭就杀死它。

更对信息，参考 Native messaging。

语法
--


```js
var sending = browser.runtime.sendNativeMessage(
  application, // string
  message, // object
);
```

### 参数

`application`

`字符串类型。`native application 的名字。它必须和 native application's manifest file中的‘name’字段一致。

`message`

`对象类型。一个将要发送给` native application 的 JSON 对象。

### 返回值

一个 `Promise`对象。如果 native application 发送了一个回复，它将会填充回复的 JSON 对象作为参数。否则它不会填充参数。如果在 native application 连接期间发生了错误，promise 将会被一个错误的消息拒绝。

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

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

示例
--

这是一个 background script，当使用者点击浏览器的 browser action 时，它会发送 "ping" 消息到 "ping\_pong" 应用并且把回复记录下来：


```js
function onResponse(response) {
  console.log(`Received ${response}`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

/\*
On a click on the browser action, send the app a message.
\*/
browser.browserAction.onClicked.addListener(() => {
  console.log("Sending: ping");
  var sending = browser.runtime.sendNativeMessage("ping\_pong", "ping");
  sending.then(onResponse, onError);
});
```


**备注：** 这个 API 基于 Chromium 的 `chrome.runtime` API。本文来自 Chromium 代码中的 `runtime.json` 。

微软 Edge 的兼容性数据由 Microsoft Corporation 提供，并且包含在这里基于 Creative Commons Attribution 3.0 United States License。
runtime.sendMessage()
=====================

向你的扩展或其他扩展中的事件监听器发送一条消息。

如果想发给你自己的扩展，则省略 `extensionId` 参数。扩展中除调用 `runtime.sendMessage` 的页面以外的所有页面都会触发 `runtime.onMessage` (en-US) 事件。

如果要发送给其他扩展，则将参数 `extensionId` 设置为其他扩展的 ID。其他扩展的 `runtime.onMessageExternal` (en-US) 将会被触发。默认情况下，你的扩展可以与其自身以及其他任何扩展（通过 `extensionId` 定义）传递消息。但是，可以使用 `externally_connectable` (en-US) 来限制与特定扩展的通信。

扩展不能使用此方法给内容脚本发送消息。要给内容脚本发送消息，请使用 `tabs.sendMessage` (en-US)。

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

**备注：** 你还可以使用基于连接的方法来传递消息。

语法
--


```js
let sending = browser.runtime.sendMessage(
  extensionId,             // 可选字符串
  message,                 // 任何值
  options,                 // 可选对象
)
```

### 参数

`extensionId` 可选

`string`。要将消息发送到的扩展的 ID。包含该参数可将消息发送到其他扩展。如果接收方使用 manifest.json 中的 browser\_specific\_settings 键显式设置了 ID，则 `extensionId` 应该设为该值。否则，它应该是为接收方生成的 ID。

如果省略了 `extensionId`，则消息会被发送到你自己的扩展。

`message`

`any`。可以使用结构化克隆算法序列化的对象。（参见数据克隆算法）。

`options` 可选

`object`。

`includeTlsChannelId` 可选

`boolean`。是否将 TLS 通道 ID 传递给正在监听连接事件的进程的 `runtime.onMessageExternal` (en-US)。

只有基于 Chromium 的浏览器支持此选项。



根据给出的参数不同，API 有时并不明确。此时会使用以下规则：

* **只有 1 个参数**：为要发送的消息，且该消息会在内部传递。
* **有 2 个参数**：
    + 若第二个参数符合下面的规则，则参数将会被解释为 `(message, options)`，且消息会在内部传递：
        1. 一个有效的 `options` 对象（也就是说，它是一个仅包含浏览器支持的 `options` 属性的对象）
        2. null
        3. undefined
    + 否则，参数将会被解释为 `(extensionId, message)`。消息将会发送给由 `extensionId` 标识的扩展。
* **有 3 个参数**：将会被解释为 `(extensionId, message, options)`。消息将会给发送给由 `extensionId` 标识的扩展。

注意，在 Firefox 55 之前，2 个参数的情况下的规则是不同的。在旧规则下，如果第一个参数是字符串，则将其视为 `extensionId`，第二个参数作为消息。这意味着如果你使用 `("my-message", {})` 这样的参数调用 `sendMessage()`，那么它将向标识为“my-message”的扩展发送空消息。根据新规则，使用这样的参数，将会是在带有一个空的 options 对象的情况下，在内部发送消息“my-message”。

### 返回值

一个 `Promise`。若接收方发送了响应，Promise 将会兑现为该响应。否则，它将不带任何参数兑现。如果连接到扩展时发生了错误，则 Promise 将以一个错误消息拒绝。

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

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

示例
--

这是一个内容脚本，当用户点击内容窗口时，会向后台脚本发送一条消息。消息载荷是 `{greeting: "来自内容脚本的问候"}`，发送者还期望得到一个响应，该响应在 `handleResponse` 函数中处理：


```js
// content-script.js

function handleResponse(message) {
  console.log(`来自后台脚本的消息：${message.response}`);
}

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

function notifyBackgroundPage(e) {
  const sending = browser.runtime.sendMessage({
    greeting: "来自内容脚本的问候",
  });
  sending.then(handleResponse, handleError);
}

window.addEventListener("click", notifyBackgroundPage);
```


对应的后台脚本如下所示：


```js
// background-script.js
function handleMessage(request, sender, sendResponse) {
  console.log(`内容脚本发送了一条消息：${request.greeting}`);
  sendResponse({ response: "来自后台脚本的响应" });
}

browser.runtime.onMessage.addListener(handleMessage);
```


**备注：** 对于 Firefox 附加组件，建议使用返回 `Promise` 的方法，而不是使用 `sendResponse()`。使用 Promise 的示例可在 `runtime.onMessage` (en-US) 监听器的“示例”小节 (en-US)中找到。

### Example extensions

* content-script-register
* devtools-panels
* export-helpers
* find-across-tabs
* mocha-client-tests
* notify-link-clicks-i18n
* store-collected-images
* user-script-register
* webpack-modules

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

当使用扩展处理或 content script 建立连接时触发。

Syntax
------


```js
browser.runtime.onConnect.addListener(listener);
browser.runtime.onConnect.removeListener(listener);
browser.runtime.onConnect.hasListener(listener);
```


事件有三个方法：

`addListener(callback)`

为 这个事件添加一个监听器。

`removeListener(listener)`

停止监听这个事件。`listener` 参数就是要移除的监听器。

`hasListener(listener)`

检查监听器是否已经注册到这个事件上。如果已经监听，则返回 `true` 否则返回 `false`.

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

### 参数

`function`

A callback function that will be called when this event occurs. The function will be passed the following arguments:

`port`

A `runtime.Port` (en-US) object connecting the current script to the other context it is connecting to.


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

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

Examples
--------

This content script:

* connects to the background script, and stores the `Port` in a variable `myPort`
* listens for messages on `myPort`, and logs them
* sends messages to the background script, using `myPort`, when the user clicks the document


```js
// content-script.js

var myPort = browser.runtime.connect({ name: "port-from-cs" });
myPort.postMessage({ greeting: "hello from content script" });

myPort.onMessage.addListener(function (m) {
  console.log("In content script, received message from background script: ");
  console.log(m.greeting);
});

document.body.addEventListener("click", function () {
  myPort.postMessage({ greeting: "they clicked the page!" });
});
```


The corresponding background script:

* listens for connection attempts from the content script
* when it receives a connection attempt:
    + stores the port in a variable named `portFromCS`
    + sends the content script a message using the port
    + starts listening to messages received on the port, and logs them
* sends messages to the content script, using `portFromCS`, when the user clicks the extension's browser action


```js
// background-script.js

var portFromCS;

function connected(p) {
  portFromCS = p;
  portFromCS.postMessage({ greeting: "hi there content script!" });
  portFromCS.onMessage.addListener(function (m) {
    console.log("In background script, received message from content script");
    console.log(m.greeting);
  });
}

browser.runtime.onConnect.addListener(connected);

browser.browserAction.onClicked.addListener(function () {
  portFromCS.postMessage({ greeting: "they clicked the button!" });
});
```


**备注：** 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.
获取当前操作系统 - runtime.PlatformOs
=============================

获取当前浏览器运行所在的操作系统。

值类型
---

该值的类型是字符串。可能的值如下：

`"mac"`

表示底层操作系统是 Mac OS X.

`"win"`

表示底层操作系统是 Windows.

`"android"`

表示底层操作系统是 Android.

`"cros"`

表示底层操作系统是 ChromeOS.

`"linux"`

表示底层操作系统是 Linux.

`"openbsd"`

表示底层操作系统是 Open/FreeBSD.

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

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.
连接本地应用程序方法 - runtime.connectNative()
====================================

该方法能够把附加组件和用户计算机上的一个本地应用程序相连接。同时我们需要本地应用程序的名称作为参数。当启动本地应用程序的时候会返回一个`runtime.Port` (en-US) 对象给调用者。之后可以通过该对象的 Port.onMessage() 和 Port.postMessage() 方法来和本地应用程序进行信息交互。本地应用程序会一直运行直到退出，除非调用了 `Port.disconnect()`方法，亦或创建该 Port 对象的页面被摧毁了。一旦 Port 对象断开连接，浏览器会给该进程几秒的时间以便安全优雅的退出和释放，之后如果发现该进程没退出的话就直接暴力干掉。

更多信息，请查看 Native messaging.

语法
--


```js
var port = browser.runtime.connectNative(
  application, // 这是一个字符串
);
```

### 参数

`application`

值类型为 `string`。该参数的值为要连接的本地应用程序的名称。必须要跟 native application's manifest file 中的"name"特性的值一致。

### 返回值

是一个 `runtime.Port` (en-US) 对象。该对象是用来跟本地应用程序进行消息交互的。

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

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

示例
--

本示例中连接了本地应用程序"ping\_pong"并且启动了监听以便接收消息。当用户单击浏览器上的操作按钮时它会发送一个本地应用程序的消息：


```js
/\*
启动时，连接"ping\_pong"本地应用程序。
\*/
var port = browser.runtime.connectNative("ping\_pong");

/\*
监听 (接收) 来自"ping\_pong"本地应用程序的消息。
\*/
port.onMessage.addListener((response) => {
  console.log("Received: " + response);
});

/\*
当浏览器上的单击操作被触发时，发送一个消息给本地应用程序。
\*/
browser.browserAction.onClicked.addListener(() => {
  console.log("Sending: ping");
  port.postMessage("ping");
});
```

### Example extensions

* native-messaging

**备注：** 该 API 是基于 Chromium 的 `chrome.runtime` API. 本文档采自 Chromium 代码中的 `runtime.json`.

Microsoft Edge 的兼容性数据由微软公司提供，并被列入以下许可证 Creative Commons Attribution 3.0 United States License.
runtime.openOptionsPage()
=========================

假如你的页面有options page（设置页面）的定义，使用此方法打开它。这是一个异步方法，返回一个 `Promise` 对象。

语法
--


```js
var openingPage = browser.runtime.openOptionsPage();
```

### 参数

无

### 返回值

当设置页面成功创建，执行Promise的无参成功回调方法，否则执行Promise的失败回调方法，参数为错误信息。

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

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

示例
--

当用户点击浏览器行为图标时，打开一个设置页面。


```js
function onOpened() {
  console.log(`Options page opened`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

var opening = browser.runtime.openOptionsPage();
opening.then(onOpened, onError);
```

### Example extensions

* favourite-colour

**备注：** 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.
读取主文件信息方法 - runtime.getManifest()
=================================

该方法会获取一个完整的主文件 manifest.json，并返回一个序列化后的 JSON 对象。

语法
--


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

### 参数

无。

### 返回值

是一个能表示主文件所有信息的 JSON 对象。

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

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

示例
--

取得主文件中的 name 特性的值，并输出到控制台：


```js
var manifest = browser.runtime.getManifest();
console.log(manifest.name);
```

### Example extensions

* runtime-examples

**备注：** 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.
alarms.create()
===============

创建一个新的 alarm.

使用语法
----


```js
browser.alarms.create(
  name, // 可选的字符串 (string) 类型
  alarmInfo, // 可选的对象 (object) 类型
);
```

### 参数介绍

`name`可选

字符串类型。alarm 的名称。默认为空的字符串。alarm 的名称可以在`alarms.get()` (en-US)方法和`alarms.clear()` (en-US)方法中引用。同时它也可以通过`alarms.onAlarm` (en-US)监听方法传入的参数对象`alarms.Alarm` (en-US)的 name 属性访问到。Alarm 的名称是唯一的 (在单个附件范围内). 如果传入了已经在这个附件存在的名称，原来的同名 alarm 会被移除并且没有警告。

`alarmInfo`可选

`object`（对象）类型。你可以对过它来指定什么时间 alarm 会开始触发，其值可以是一个具体的时间值或者是一个延时（从 alarm 设置开始）。为了让 alarm 能复现，需要指定 `periodInMinutes`。

在 Chrome 浏览器上，除非附件以非打包 (unpackaged) 方式加载，alarm 的创建每分钟不允许超过一次。如果附件尝试设置 `delayInMinutes` 为小于 1 的值，alarm 只能在到达 1 分钟之后才会触发，并且会变成每分钟触发一次。

`alarmInfo` 对象可以设置以下属性：

`when`可选

`double` 类型。alarm 第一次触发的时间，值为自 1970-01-01 00:00:00 UTC 过去的毫秒数。请使用 `Date.now()` 来获取 `1970-01-01 00:00:00 UTC` 到当前时间过去的毫秒数。如果你设置了 when 属性，请不要设置 delayInMinutes 属性。

`delayInMinutes`可选

`double` 类型。alarm 设置好到第一次触发之间的分钟数。如果你设置了 `delayInMinutes` 属性，请不要设置 when 属性。

`periodInMinutes`可选

`double` 类型。如果设置此属性，alarm 会从第一次触发开始每隔 `periodInMinutes` 分钟再次触发。如果你没有设置 when 及 delayInMinutes 属性，alarm 会在 alarm 设置好之后 periodInMinutes 分钟第一次触发。如果 periodInMinutes 属性没有设置，则 alarm 只会触发一次。


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

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

示例
--

Create a one-time delay-based alarm with "" for the name:


```js
const delayInMinutes = 5;

browser.alarms.create({
  delayInMinutes,
});
```


Create a periodic delay-based alarm named "my-periodic-alarm":


```js
const delayInMinutes = 5;
const periodInMinutes = 2;

browser.alarms.create("my-periodic-alarm", {
  delayInMinutes,
  periodInMinutes,
});
```


Create a periodic absolute alarm named "my-periodic-alarm":


```js
const when = 1545696000;
const periodInMinutes = 2;

browser.alarms.create("my-periodic-alarm", {
  when,
  periodInMinutes,
});
```


**备注：** 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.
search.search()
===============

使用指定的搜索引擎或默认搜索引擎进行搜索。

结果将显示在一个新的选项卡中，或者如果给出了 tabId 参数，则显示在由此标识的选项卡中。

要在扩展程序中使用此功能，你必须要求`"search"` 有明确许可.

获取安装的搜索引擎，请使用 `search.get()` (en-US).

语法
--


```js
browser.search.search(
  searchProperties, // object
);
```

### 参数

`searchProperties`

`object`. 拥有以下属性的对象：

`query`

`字符串`. 进行查询的内容。

`engine`可选

`字符串。`.搜索引擎的名称。如果指定的搜索引擎名称不存在，该函数将引发错误。如果省略此属性，则使用默认的搜索引擎。

`tabId`可选

整型。用于显示搜索结果的选项卡。如果省略此属性，搜索结果将显示在新选项卡中。


### 返回值

无。

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

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

示例
--

使用默认搜索引擎进行搜索。结果显示在新选项卡中：


```js
function search() {
  browser.search.search({
    query: "styracosaurus",
  });
}

browser.browserAction.onClicked.addListener(search);
```


使用维基百科进行搜索。结果显示在新选项卡中：


```js
function search() {
  browser.search.search({
    query: "styracosaurus",
    engine: "Wikipedia (en)",
  });
}

browser.browserAction.onClicked.addListener(search);
```


使用维基百科进行搜索。结果将显示在活动选项卡中：


```js
function search(tab) {
  browser.search.search({
    query: "styracosaurus",
    engine: "Wikipedia (en)",
    tabId: tab.id,
  });
}

browser.browserAction.onClicked.addListener(search);
```

### Example extensions

* menu-search