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

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

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

使浏览器扩展能够储存及获取数据，以及监听储存的数据的变化。
此存储系统 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
=======

与浏览器窗口互动。你可以使用此 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
=======

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

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

它提供一组消息通信 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.
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
==============

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

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

图像被作为包含经过编码的图像的 `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()
============

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

这是一个返回 `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()
================

向一个页面注入 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
================

当窗体的活动标签变化时触发。请注意事件触发时标签的 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.