recursal/MDN huggingface dataset:
webRequest.RequestFilter
========================

webRequest 事件参数

Type
----

该参数值是一个对象，包括以下属性：

`urls`

字符串数组类型，数组内的每个字符串为模式匹配格式。当请求地址符合给定模式时，事件监听器才会响应。需注意的是，仅支持 http 和 HTTPS 协议的参数地址，其他协议即使与该给定模式匹配也不会响应。

`types`可选

webRequest.ResourceType 类型的数组，表示资源类型列表。例如：stylesheets、images、scripts。事件监听器仅响应出现在该指定列表的资源类型。

`tabId`可选

数值类型，与`tab`关联，事件监听器仅响应指定了该 tabId 的请求。

`windowId`可选

数值类型，与`window` (en-US)关联，事件监听器仅响应指定了该`windowId`的请求。

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

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

**备注：** 该 API 基于 Chromium 的 `chrome.webRequest` API. 该文档来源于 Chromium 代码中的 `web_request.json` 。

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

该`Session`对象表示用户在当前浏览会话中已关闭的选项卡或窗口。

如果关闭了选项卡但未关闭其窗口，则会话以`Tab`对象表示：例如，因为用户单击了“关闭选项卡”按钮，并且此选项卡不是其窗口中的唯一选项卡。

如果关闭窗口，则会话表示为`Window` (en-US)对象：例如，由于用户单击“关闭窗口”按钮，或关闭了窗口中唯一打开的选项卡。

请注意，不同的浏览器可能对会话何时为 Tab 和何时为 Window 有不同的想法。例如：

* 在 Chrome 中，如果用户关闭包含多个标签的窗口，则会话将记录为“窗口”。如果用户关闭了仅包含一个选项卡的窗口，则该窗口将记录为一个选项卡。
* 在 Firefox 中，如果用户关闭窗口（或该窗口中最后一个选项卡的选项卡），则将会话记录为窗口，如果用户关闭窗口中最后一个选项卡中的选项卡，则将会话记录为一个 Tab。

打开的选项卡的 Tab 对象没有`sessionId`。关闭选项卡时，它将具有一个`sessionId`但没有选项卡`id`。如果恢复了该标签页，它将获得一个新的标签页，`id`并且会丢失`sessionId`。

类型
--

此类型的值是对象。它们包含以下属性：

`lastModified`

`number`。选项卡或窗口关闭的时间，自 epoch 以来的毫秒数。

`tab`可选

`object`。如果对象表示已关闭的选项卡，则此属性存在，并且将是 `tabs.Tab` 对象。仅当扩展具有“tabs” 权限时，它才会包含 `url`，`title` 和 `favIconUrl`。

`window`可选

`object`。如果对象表示一个关闭的窗口，则此属性存在并且将是`windows.Window` (en-US)对象。

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

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

**备注：** 该 API 基于 Chromium 的`chrome.sessions`API。

Microsoft Edge 兼容性数据由 Microsoft Corporation 提供，并在此处包含在 Creative Commons Attribution 3.0 美国许可证下。
bookmarks.BookmarkTreeNode
==========================

代表书签树中的一个节点（书签或文件夹），子节点在它们的父文件夹中按顺序排列。

类型
--

这种类型的值都是对象。它们包含以下属性：

`id`

`string`. 节点的唯一标识符。唯一标识符在当前用户配置文件中保证唯一，并且在浏览器重新启动后仍然有效。

`parentId`可选

`string`. 父节点的标识符（id）。根节点没有此属性。

`index`可选

`integer`. 该节点在父文件夹中的位置（从 0 开始）。

`url`可选

`string`. 当用户单击书签时打开的 URL。文件夹没有此属性。

`title`

`string`. 该节点显示的文字。

`dateAdded`可选

`number`. 该节点创建的时间，表示为自 1970 年 1 月 1 日午夜至今所经过的毫秒数（new Date(dateAdded)）。

`dateGroupModified`可选

`number`. 该文件夹内容的上一次修改时间，表示为自 1970 年 1 月 1 日午夜至今所经过的毫秒数。

`unmodifiable`可选

`bookmarks.BookmarkTreeNodeUnmodifiable` (en-US). 表示该节点不可修改的原因，"*managed*"表示该节点由系统管理员配置。如果该节点可以由用户和扩展程序修改（默认）则省略。

`children`可选

`array` of ``bookmarks.BookmarkTreeNode``. 该节点的所有子节点（已排序）。

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

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

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

**`bookmarks.remove()`** 方法用于删除单个书签或一个空的书签文件夹。

**警告：** 如果你的扩展尝试从书签树的根节点中移除一个书签，该调用将会引发一个“书签根不能被修改的”的错误信息并且这个书签不会被移除。

这是一个异步方法，返回 `Promise` 对象。

语法
--


```js
var removingBookmark = browser.bookmarks.remove(
  id, // 字符串
);
```

### 参数

`id`

`string` 要删除的书签或空书签文件夹的 id 标识

### 返回值

若方法执行完成，返回一个无参的 `Promise` 对象。

若未找到该书签或该空书签文件夹，将返回一个带有错误信息的 `Promise` 对象。

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

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

示例
--


```js
function onRemoved() {
  console.log("Removed!");
}

function onRejected(error) {
  console.log(`An error: ${error}`);
}

var bookmarkId = "abcdefghijkl";

var removingBookmark = browser.bookmarks.remove(bookmarkId);
removingBookmark.then(onRemoved, onRejected);
```

### 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.
bookmarks.getTree()
===================

**`bookmarks.getTree()`** 返回一个数组，该数组每一项为`bookmarks.BookmarkTreeNode`对象，作为书签树的根节点。

如果它们是文件夹的话，你可以通过其 `children` 属性及其后代的 `children` 属性递归地访问整个树。

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

使用格式
----


```js
var gettingTree = browser.bookmarks.getTree();
```

### 参数

无。

### 返回值

`Promise` 对象，该对象未来会得到一个填充代表根节点的 `bookmarks.BookmarkTreeNode` 对象的数组。

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

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

示例
--

这个示例会打印出整个书签树：


```js
function makeIndent(indentLength) {
  return ".".repeat(indentLength);
}

function logItems(bookmarkItem, indent) {
  if (bookmarkItem.url) {
    console.log(makeIndent(indent) + bookmarkItem.url);
  } else {
    console.log(makeIndent(indent) + "Folder");
    indent++;
  }
  if (bookmarkItem.children) {
    for (child of bookmarkItem.children) {
      logItems(child, indent);
    }
  }
  indent--;
}

function logTree(bookmarkItems) {
  logItems(bookmarkItems[0], 0);
}

function onRejected(error) {
  console.log(`An error: ${error}`);
}

var gettingTree = browser.bookmarks.getTree();
gettingTree.then(logTree, onRejected);
```


**备注：** 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.
名称 - name
=========

|  |  |
| --- | --- |
| 值类型 | `字符串（String）` |
| 强制性 | 强制 |
| 示例 | 
```json
"name": "附加组件的名称"
```
 |

附加组件的名称。用于在用户界面和 addons.mozilla.org 网站上显示标识名称。

关于本地化，可查看 localizable property.

示例
--


```json
"name": "插件的名称"
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
作者 - author
===========

|  |  |
| --- | --- |
| 值类型 | `字符串（String）` |
| 强制性 | 非强制 |
| 示例 | 
```json
"author": "小明"
```
 |

附加组件的作者，用于在浏览器用户界面上显示，这样别人下载安装使用该附加组件的时候，就能看见你的大名了。

示例
--


```json
"author": "小明"
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
manifest\_version
=================

|  |  |
| --- | --- |
| 值类型 | `Number` |
| 强制性 | 强制 |
| 示例 | 
```json
"manifest\_version": 2
```
 |

此键指定扩展使用的 manifest.json 的版本。

示例
--


```json
"manifest\_version": 2
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
homepage\_url
=============

|  |  |
| --- | --- |
| 值类型 | 字符串（`String`） |
| 强制性 | 非强制 |
| 示例 | 
```json
"homepage\_url": "https://example.org/my-addon"
```
 |

该扩展的主页地址。

如果 developer 键存在且包含“url”属性，它将会覆盖 `homepage_url` 键。

这是一个 localizable property.

示例
--


```json
"homepage\_url": "https://github.com/mdn/webextensions-examples/tree/main/beastify"
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
后台 - background
===============

|  |  |
| --- | --- |
| Type | `Object` |
| 强制性 | 不强制 |
| 示例 | 
```json
"background": {
  "scripts": ["background.js"]
}
```
 |

通过 background 键来给你的扩展程序引入一个或者多个后台脚本文件，以及一个可选的后台页面文件。

后台脚本放置的是需要长期保持状态，或者需要执行长期的操作，并且与任意特定网页或者浏览器窗口的生命周期无关的代码。

后台脚本会在扩展程序被加载后立即被加载，并且一直保持被加载状态，只有在扩展程序被禁止或者卸载的时候才停止运行。只要你获得了必要的许可permissions，你可以在该脚本中使用任意的扩展程序 API。

浏览Anatomy of a WebExtension中的 Background pages 部分以获取更多的细节。

background 键最多只能拥有以下的两个属性，两个属性都是可选属性：

|  |  |
| --- | --- |
| `"scripts"` | 
 一个字符串数组，数组中的每个字符串都是 JavaScript 源文件相对于
 manifest.json 的相对路径，JavaScript
 源文件便是些被包含在扩展程序中的后台脚本文件。

脚本共享相同的全局窗口
脚本按照在数组中的顺序进行加载

**注意在低于 Firefox 50 版本的浏览器下会出现一个问题：**当 Firefox debugger
 已经打开时，脚本并不能总是按照数组中定义的顺序进行加载。若要解决这个问题，你可以使用
 page
 属性，用<script>标签将后台脚本文件从页面中加载进来。这个问题已经在
 Firefox 50 中被修复。
  |
| `"page"` | 如果你仅仅指定了“scripts”属性，将生成一个空白的页面来运行指定的脚本。
如果你需要在页面中显示某些特定的内容，你可以使用“page”属性来定义自己的页面。
如果你使用此属性，你仍然可以使用“script”属性来指定后台脚本，但你也可以就像在普通网页中一样在页面中包含自己的脚本。 |

示例
--

加载 2 个后台脚本文件。


```json
  "background": {
    "scripts": ["jquery.js", "my-background.js"]
  }
```


加载 1 个自定义的后台页面文件。


```json
  "background": {
    "page": "my-background.html"
  }
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
default\_locale
===============

|  |  |
| --- | --- |
| Type | `String` |
| 强制性 | 可能发生的：如果存在\_locales 子目录，必须存在，否则不存在。 |
| 例子 | 
```json
"default\_locale": "en"
```
 |

如果扩展名包含\_locales 目录，则该 key 必须存在，否则不得存在。它标识 \_locales 的一个子目录，该子目录将用于查找扩展名的默认字符串。

见 国际化 。

范例
--


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

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
content\_scripts
================

|  |  |
| --- | --- |
| 类型 | 数组（`Array`） |
| 必要 | 否 |
| 示例 | 
```json
"content\_scripts": [
  {
    "matches": ["\*://\*.mozilla.org/\*"],
    "js": ["borderify.js"]
  }
]
```
 |

让浏览器将content scripts加载到匹配网址的网站上

此键（content\_scripts）是一个数组，每个项目都是一个满足下列条件的对象：

* **必须**包含一个名为 **`matches`** 的键，指定要加载脚本的 URL 的格式
* **可以**包含一个名为 **`js`** 或 **`css`** 的键，列出要加载到匹配页面的脚本
* **可以**包含控制如何加载、何时加载等方面更精细的属性

下面表格列出了所有与你可以使用的键：

| 名称 | 类型 | 描述 |
| --- | --- | --- |
| `all_frames` | `Boolean` | `true`: 将`js`和`css`注入该页面所有的框架（frame）中
`false`: 仅注入到顶层
默认为 false |
| `css` | `Array` | 
 一个数组，包含将会被注入到匹配页面的 CSS 文件的路径（路径相对于
 manifest.json）。

在加载 DOM 之前，文件将会按指定的顺序注入。 |
| `exclude_globs` | `Array` | Firefox 自 48 版本开始支持 globs
包含通配符的字符串数组。请参阅下面的匹配 URL 格式。 |
| `exclude_matches` | `Array` | 一个match patterns的数组，请参阅下面的匹配 URL 格式。 |
| `include_globs` | `Array` | Firefox 自 48 版本开始支持 globs包含通配符的字符串数组。请参阅下面的匹配 URL 格式。
  |
| `js` | `Array` | 
 一个数组，包含将会被注入到匹配页面的 JS 文件的路径（路径相对于
 manifest.json）。


 文件将会按指定的顺序注入。这意味着如果你想在另一个脚本中包含
 jQuery，可以这样做：


```json
"js": ["jquery.js", "my-content-script.js"]
```

接下来，`"my-content-script.js"`可以使用 jQuery.
文件将在run\_at指定的时间注入。 |
| `matches` | `Array` | 一个match patterns的数组，请参阅下面的匹配 URL 格式。
这是唯一的必须键。 |
| `run_at` | `String` | 此选项指定在“js”键中的脚本何时被注入。你可以使用下列的三个字符串之一，每个字符串都代表加载文档过程中的不同状态。状态直接对应于`Document.readyState`：* “`document_start`”：对应于正在加载。DOM 仍在加载中。
* “`document_end`”：对应于可交互。DOM
 已完成加载，但脚本和图像等资源可能仍在加载。
* “`document_idle`”：对应完成。文档及其所有资源已完成加载。

默认值为“document\_idle”。
在所有情况下，js 键中的文件都会在css 键中的文件之后注入。 |

匹配 URL 格式
---------

“content\_scripts”键基于 URL 匹配将 content scripts 注入到网页上：如果网页的 URL 与键中的规则匹配，则将注入脚本。“content\_scripts”中有四个属性，可以用于此规则：

* `matches`: 一个关于match patterns的数组
* `exclude_matches`: 一个关于match patterns的数组
* `include_globs`: 一个关于globs的数组
* `exclude_globs`: 一个关于globs的数组

要匹配这些属性之一，网址必须与其数组中的至少一个项匹配。例如，指定一个属性：


```json
"matches": ["\*://\*.example.org/\*", "\*://\*.example.com/\*"]
```


"http://example.org/"和"http://example.com/"都将会匹配

由于 matches 是唯一的强制性键，其他三个键用于进一步限制匹配的 URL。要匹配作为一个整体的键，网址必须：

1. 匹配 matches 属性
2. 并且，匹配 include\_globs 属性（如果有）
3. 并且，不匹配`exclude_matches`属性（如果有）
4. 并且，不匹配`exclude_globs`属性（如果有）
### globs

Firefox 自 48 版本开始支持 globs

glob 只是一个可以包含通配符的字符串。有两种类型的通配符，你可以在一个 glob 中组合使用它们：

* "\*" 匹配零个或多个字符
* "?" 匹配一个字符

例如，`"*na?i"` 会匹配 `"illuminati"` 和 `"annunaki"`，但不会匹配 `"sagnarelli"`.

示例
--


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


这会将 content 脚本“borderify.js”插入到“mozilla.org”或其任何子域下的所有页面，无论是 HTTP 还是 HTTPS。


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


这会将两个 content 脚本插入到“mozilla.org”及其任何子域（除“developer.mozilla.org”外）的所有页面中，无论是通过 HTTP 还是 HTTPS。

content 脚本有相同的 DOM 视图，并按照它们在数组中出现的顺序注入，因此“borderify.js”可以访问由“jquery.js”添加的全局变量。

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

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

|  |  |
| --- | --- |
| Type | `String` |
| 强制性 | 强制 |
| 示例 | 
```json
"version": "0.1"
```
 |

附加组件的版本，一般格式设置为由点分隔开来数字的 ASCII 字符串。关于版本格式的详细信息，请查看 Version format .

需要注意的是 Chrome 浏览器的 version 格式要求 (the syntax defined for Chrome's `version`) 比 Firefox 浏览器的 version 格式更严格一些，这意味这：

* 对 Chrome 浏览器有效的 version 特性的值一定在 Firefox 浏览器中有效
* 但对 Firefox 浏览器有效的 version 特性的值在 Chrome 浏览器中却不一定有效
示例
--


```json
"version": "0.1"
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
短名称 - short\_name
=================

|  |  |
| --- | --- |
| Type | `String` |
| 强制性 | 不强制 |
| 示例 | 
```json
"short\_name": "附加组件的短名称"
```
 |

附加组件的短名称。一般用在 name 特性太长的情况下。建议短名称的长度不要超过 12 个字符。如果没有在 manifest.json 主文件中声明 short\_name, 并且 name 特性的值又比较长的话，用户界面显示的时候可能只会显示一部分。

关于本地化，可查看 localizable property.

示例
--


```json
"short\_name": "附加组件的短名称"
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
描述 - description
================

|  |  |
| --- | --- |
| 值类型 | `字符串` |
| 强制性 | 不强制 |
| 示例 | 
```json
"description": "附加组件的主要功能特性的简短描述。"
```
 |

用于在用户下载安装使用界面中显示的一段简短的关于该附加组件的描述。

关于本地化，可查看 localizable property.

示例
--


```json
"description": "附加组件的主要功能特性的简短描述。"
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
browser\_specific\_settings
===========================

**备注：** 注意这个 key 不被 Blink-based 浏览器 (Google Chrome 和 Opera) 支持。如果你在插件中包含了这个 key，当在这些浏览器中调用时虽然能用但是会显示警告。


|  |  |
| --- | --- |
| 类型 | `Object` |
| 强制性 | 通常不做强制性要求（详细参见什么时候需要附加组件 ID？。）如果扩展 ID 不能确定，则必需，参见 `browser_specific_settings.gecko.id`。 |
| 示例 | 
```json
"browser\_specific\_settings": {
  "gecko": {
    "id": "addon@example.com",
    "strict\_min\_version": "42.0"
  }
}
```
 |

描述
--

`browser_specific_settings` 键包含特定于主机应用程序的键。

### Firefox（Gecko）属性

* `id` 即扩展 ID。从 Firefox 48 起为可选项，在此之前为强制必须项。参见 WebExtensions 和附加组件 ID 来确认何时需要定义附加组件 ID。
* `strict_min_version`: Gecko 所能支持的最小版本号。不允许使用"\*"来定义版本号。默认值为 "42a1"。
* `strict_max_version`: Gecko 所能支持的最大版本号。如果安装或运行附加组件的 Firefox 版本号高于这个最大版本号，附加组件将不能运行或不允许被安装。默认值为"\*"，意思为不对最大版本号做检查。
* `update_url` 为链接到扩展更新清单的链接。注意链接必须以“https”开头。这是为了使你自己就能够管理附加组件的更新（如不通过 AMO）。
示例
--

示例中包含了所有可能的 key。注意你通常不会在大部分附加组件中包含 `strict_max_version` 和 `update_url`。


```json
"browser\_specific\_settings": {
  "gecko": {
    "id": "addon@example.com",
    "strict\_min\_version": "42.0",
    "strict\_max\_version": "50.\*",
    "update\_url": "https://example.com/updates.json"
  },
  "safari": {
    "strict\_min\_version": "14",
    "strict\_max\_version": "20"
  }
}
```

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

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

|  |  |
| --- | --- |
| 值类型 | `对象` |
| 强制性 | 非强制 |
| 示例 | 
```json
"developer": {
  "name": "Walt Whitman",
  "url": "https://en.wikipedia.org/wiki/Walt\_Whitman"
}
```
 |

插件开发者的名字和主页地址，用于显示在浏览器的用户界面中。

该对象的两个属性都是可选的。如果存在“name”和“url”属性，将会分别覆盖author和homepage\_url键。这个对象仅仅允许指定一个开发者名字的主页地址。

示例
--


```json
"developer": {
  "name": "Walt Whitman",
  "url": "https://en.wikipedia.org/wiki/Walt\_Whitman"
}
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
web\_accessible\_resources
==========================

|  |  |
| --- | --- |
| 类型 | `Array` |
| 是否必需 | No |
| 示例 | 
```json
"web\_accessible\_resources": [
  "images/my-image.png"
]
```
 |

描述
--

你有时想将资源（如图片、HTML、CSS 或 JavaScript）与你的扩展应用合并打包，让网页能够访问它们。

举个例子，Beastify example extension 将用户选择的野兽图片来替换网页，这些图片与应用是经过合并打包的。该应用添加 `<img>`，其 `src` 指向图片，这样就使选中的图片可见了。网页要载入图片的话，这些图片就必须可经访问。

通过 `web_accessible_resources`，你列出资源，让它们可经网页访问。这些资源路径相对于 manifest.json 文件。

注意，这其中不必包括 content scripts。

如果你的应用要用 `webRequest` 来重定向公共 URL(如 HTTPS) 到一个该应用中的页面，那么应用必须将该页面列入`web_accessible_resources`。

### 使用 web\_accessible\_resources

例如，如果你的应用含有图片，路径为 images/my-image.png，如下所示：
```

my-extension-files/
    manifest.json
    my-background-script.js
    images/
        my-image.png
```


如果要使网页能够从元素 `<img>` 的属性 `src` 指向该图片，你得写明`web_accessible_resources`，如下所示：


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


之后，图片可通过 URL 来访问，如下所示：
```

moz-extension://<extension-UUID>/images/my-image.png"
```


`<extension-UUID>` 不是应用 ID，它随机生成，对应每个浏览器实例，以防网页查看浏览器安装的扩展应用来获取信息。

**备注：** Chrome 的 `<extension-UUID>` 是不变的。某资源如果由`web_accessible_resources` 写明，那么它可通过 `chrome-extension://<your-extension-id>/<path/to/resource>` 来访问。

要获得资源的 URL，推荐用 `runtime.getURL` 向参数传递 manifest.json 的相对路径，比如：


```js
browser.runtime.getURL("images/my-image.png");
// something like:
// moz-extension://944cfddf-7a95-3c47-bd9a-663b3ce8d699/images/my-image.png
```


这会返回正确的 URL，不受应用运行的浏览器影响。

### 通配符

`web_accessible_resources` 中的条目还可以有通配符。比如，下面的条目匹配“images/my-image.png”：


```json
  "web\_accessible\_resources": ["images/\*.png"]
```

### 安全

注意，如果你部署了一个页面，那么任一网页可能会链接或重定向至该页面，因而它应认为任意输入（比如 POST data）的来源不可信任，这与通常网页的做法一样。

Example
-------


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


Make the file at "images/my-image.png" web accessible.

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
加载和运行 WebAssembly 代码
====================

为了在 JavaScript 中使用 WebAssembly，在编译/实例化之前，你首先需要把模块放入内存。本文提供了一篇关于获取 WebAssembly 字节码的不同机制以及如何编译/实例化并运行它的参考。

这里的主题是什么？
---------

WebAssembly 还没有和 `<script type='module'>` 或 `import` 语句集成，因此当前还没有方式可以让浏览器使用 import 为你获取模块。

老的 `WebAssembly.compile`/`WebAssembly.instantiate` 方法要求你在获取原始字节之后创建一个包含了你的 WebAssembly 模块二进制的 `ArrayBuffer`，然后编译/实例化它。这类似于 `new Function(string)`，只不过我们用字节数组缓冲区（WebAssembly 源码）替换了字符串（JavaScript 源码）。

新的 `WebAssembly.compileStreaming`/`WebAssembly.instantiateStreaming` 方法更加高效——它们直接在来自网络的原始字节流上执行操作，省去了 `ArrayBuffer` 步骤。

那么，我们该如何把这些字节放入到一个数组缓冲区并进行编译呢？下面的部分将进行解释。

使用 Fetch
--------

Fetch 是一个方便的、现代的用于获取网络资源的 API。

获取 WebAssembly 模块最快、最有效的方式是使用新的 `WebAssembly.instantiateStreaming()` 方法，该方法可以接受一个 `fetch()` 调用作为它的第一个参数，并且可以在一步骤中处理获取、编译和实例化模块，访问从服务器流式传输的原始字节码：


```js
WebAssembly.instantiateStreaming(fetch("simple.wasm"), importObject).then(
  (results) => {
    // 使用 results 做些什么！
  },
);
```


如果我们使用旧的 `WebAssembly.instantiate()` 方法，它不能直接在流上工作，我们需要一个额外的步骤来把获取的字节码转换为 `ArrayBuffer`，像这样：


```js
fetch("module.wasm")
  .then((response) => response.arrayBuffer())
  .then((bytes) => WebAssembly.instantiate(bytes, importObject))
  .then((results) => {
    // 使用 results 做些什么！
  });
```

### 顺便说一下 instantiate() 重载

`WebAssembly.instantiate()` 函数有两种重载形式——一种是前面展示的那样，接受待编译的字节码作为参数并且返回一个 Promise，其会被解决为一个包含已编译的模块对象及其实例的对象。这个对象看起来像这样：


```js
{
  module: Module, // 新编译的 WebAssembly.Module 对象，
  instance: Instance, // 新的模块对象实例（WebAssembly.Instance）
}
```


**备注：** 通常，我们只关心实例，但是，当我们想缓存模块，使用 `postMessage()` (en-US) 与另外一个 worker 或 window 共享模块或者只是创建更多的实例的时候，拥有模块对象是很有用的。

**备注：** 这二种重载形式接受一个 `WebAssembly.Module` 对象作为参数，并且返回一个直接包含一个实例对象作为其结果的 promise。参考第二种重载示例。

### 运行你的 WebAssembly 代码

一旦在 JavaScript 中得到了可用的 WebAssembly 实例，你就可以开始使用那些通过 `WebAssembly.Instance.exports` (en-US) 属性导出的特性了。你的代码可能看起来像这样：


```js
WebAssembly.instantiateStreaming(fetch("myModule.wasm"), importObject).then(
  (obj) => {
    // 调用导出函数：
    obj.instance.exports.exported\_func();

    // 或者获取导出内存的缓存内容：
    const i32 = new Uint32Array(obj.instance.exports.memory.buffer);

    // 或者获取导出表格中的元素：
    const table = obj.instance.exports.table;
    console.log(table.get(0)());
  },
);
```


**备注：** 关于如何从 WebAssembly 模块中导出的更多信息，请阅读使用 WebAssembly JavaScript API 和理解 WebAssembly 文本格式。

使用 XMLHttpRequest
-----------------

`XMLHttpRequest` 在一定程度上而言要比 Fetch 老旧一些，但是仍然可以很好地被用来获取类型化数组。仍然假设我们的模块叫做 `simple.wasm`：

1. 创建一个 `XMLHttpRequest()` 实例，然后使用它的 `open()` 方法来开启一个请求——设置请求方法为 `GET` 并且声明我们想要获取的文件路径。
2. 关键之处在于使用 `responseType` 属性设置响应类型为 `'arraybuffer'`。
3. 接下来使用 `XMLHttpRequest.send()` 发送请求。
4. 当响应已经完成下载之后，我们使用 `load` 事件处理器来调用一个函数——在这个函数中，我们从 `response` 属性中得到数组缓冲区，然后就像使用 Fetch 那样把它传递给`WebAssembly.instantiate()` 方法。

最终代码看起来像这样：


```js
const request = new XMLHttpRequest();
request.open("GET", "simple.wasm");
request.responseType = "arraybuffer";
request.send();

request.onload = () => {
  const bytes = request.response;
  WebAssembly.instantiate(bytes, importObject).then((results) => {
    results.instance.exports.exported\_func();
  });
};
```


**备注：** 你可以在 xhr-wasm.html 看到实际使用的示例。
导出的 WebAssembly 函数
==================

导出 WebAssembly 函数的过程，其实就是指这些函数在 JavaScript 中如何用表示。本文更详细的介绍它们。

导出的...什么？
---------

导出的 WebAssembly 函数只是用 JavaScript 来表示 WebAssembly 函数的封装而已。当你调用它们的时候，就会有一些后台活动把参数转换为 wasm 能够处理的类型（例如，把 JavaScript 数字转换为 Int32 类型），参数被传递到 wasm 模块中的函数，函数被调用，返回值被转换并传回到 JavaScript。

你可以通过两种方式来获得导出的 WebAssembly 函数：

* 在一个已经存在的表格上调用 Table.prototype.get() (en-US)。
* 通过 Instance.exports (en-US) 从一个 wasm 模块实例获取导出的函数。

无论哪种方式，你得到的都是底层函数的相同封装。从 JavaScript 的角度来看，每一个 wasm 函数看起来也是一个 JavaScript 函数——但是，它们被封装在导出的 wasm 函数对象实例中，并且只有有限的方式来获取它们。

一个例子
----

让我们看个例子从而让事情更清晰（你可以在 GitHub 上找到这个例子 table-set.html；或者实时运行然后查看 wasm 文本表示）：


```js
var otherTable = new WebAssembly.Table({ element: "anyfunc", initial: 2 });

fetchAndInstantiate("table.wasm").then(function (instance) {
  var tbl = instance.exports.tbl;
  console.log(tbl.get(0)()); // 13
  console.log(tbl.get(1)()); // 42
  otherTable.set(0, tbl.get(0));
  otherTable.set(1, tbl.get(1));
  console.log(otherTable.get(0)());
  console.log(otherTable.get(1)());
});
```


在这里，我们使用 WebAssembly.Table 构造函数在 JavaScript 中创建了一个表格（otherTable），然后使用 fetchAndInstantiate() 实用函数把 table.wasm 加载到我们的页面。

然后，我们得到了从模块中导出的函数，通过 tbl.get() (en-US) 获取引用的函数并且把每一次的调用结果输出到控制台。接下来，我们使用 set() 使得 otherTable 表格包含了与 tbl 表格相同的函数。

为了证明这一点，我们从 otherTable 中获取了这些引用并且也把他们的结果打印到控制台，结果是一样的。

它们确实是函数
-------

在前面的例子中，每次 Table.prototype.get() (en-US) 调用的返回值都是一个导出的 WebAssembly 函数——这正是我们一直在讨论的。

它们确实是 JavaScript 函数也是对 WebAssembly 函数的封装。如果你把上面的例子加载到支持 WebAssembly 的浏览器中，然后在你的控制台运行下面几行代码：


```js
var testFunc = otherTable.get(0);
typeof testFunc;
```


你得到的返回结果是 function。对于这个函数，你可以像对待其他 JavaScript 函数那样做你想做的任何事——call()、bind() 等等。testFunc.toString() 返回一个有趣的结果：


```js
function 0() {
    [native code]
}
```


这带给你关于封装类型特征的更多理解。

关于导出的 WebAssembly 函数的一些其他值得关注的特性：

* 它们的 length 属性是在 wasm 函数签名中声明的参数的数量。
* 它们的 name 属性是函数在 wasm 模块中的索引调用 toString() 的返回值。
* 如果你尝试调用一个接受或返回一个 i64 类型值的导出的 wasm 函数，目前它会抛出一个错误，因为 JavaScript 当前没有精确的方式来表示一个 i64。不过，这在将来可能会改变——在将来的标准中，新的 int64 类型正在考虑之中。到那时，wasm 可以使用它。
将 WebAssembly 文本格式转换为 wasm
==========================

WebAssembly 有一个基于 S-表达式的文本表示形式，设计为在文本编辑器，浏览器开发人员工具等中暴露的一个中间形式。本文解释了它是如何工作的一些内容以及如何使用可用的工具把文本格式文件转换为.wasm 汇编格式文件。

**备注：** 文本格式文件通常被保存为.wat 扩展名；有时.wast 也被使用，它是说文件包含了额外的测试命令（断言等）并且它们不需要转换到.wasm 中。

初识文本格式
------

让我们看一个简单的例子——下面的程序从一个叫做 imports 的模块中导入了一个叫做 imported\_func 的函数并且导出了一个叫做 exported\_func 的函数：


```wasm
(module
  (func $i (import "imports" "imported\_func") (param i32))
  (func (export "exported\_func")
    i32.const 42
    call $i
  )
)
```


WebAssembly 函数 exported\_func 是被导出供我们的环境（比如，使用了 WebAssembly 模块的网络应用）使用。当被调用的时，它进而调用了一个被导入的叫做 imported\_func 的函数并且向该函数传递了一个值（42）作为参数。

把.wat 文本文件转换为.wasm 二进制文件
------------------------

让我们尝试一下把前面提到的 wat 文本表示的例子转换为 wasm 汇编格式。

1. 首先，把前面的清单内容复制到一个文本文件中；命名为 simple.wat。
2. 在使用它之前，我们需要把这个文本表示汇编为浏览器能够识别的汇编语言。为了达到这个目的，我们可以使用 wabt 工具，该工具包括了在 WebAssembly 文本表示和 wasm 之间进行相互转化的编译器以及其他一些功能。访问 https://github.com/webassembly/wabt——按照该页面的指令来安装好工具。
3. 当你安装好工具之后，将/wabt/out 目录添加到你的系统路径。
4. 下一步，执行 wat2wasm 程序，把输入文件的路径传递给它，紧跟一个-o 参数，然后是输出文件的路径：

```bash
wat2wasm simple.wat -o simple.wasm
```


该命令会把 wasm 输出到一个叫做 simple.wasm 的文件，该文件包含了.wasm 汇编代码。

**备注：** 你可以使用 wasm2wat 工具把汇编代码转换为文本表示；例如，wasm2wat simple.wasm -o text.wat。

查看汇编输出
------

因为输出文件是基于汇编的，所以，它不能在常规的文本编辑器中查看。尽管如此，你可以使用 wat2wasm 工具的-v 选项来查看。试试这个：


```bash
wat2wasm simple.wat -v
```


这会在终端产生一个如下所示的输出：

![several strings of binary with textual descriptions beside them. For example: 0000008: 01 ; section code ](/zh-CN/docs/WebAssembly/Text_format_to_Wasm/assembly-output.png)

另见
--

* 理解 WebAssembly 文本格式——详细解释文本格式语法。
* 从 C/C++ 编译为 WebAssembly——诸如 Binaryen/Emscripten 的工具不但把你的代码编译为 wasm 而且创建必要的用来在一个 JavaScript 上下文中运行模块的 API 代码。关于如何使用它们，可以探究更多内容。
* 使用 WebAssembly 的 JavaScript API——如果你想探究关于 WebAssembly API 代码是如何工作的更多内容，可以阅读这篇文章。
* 文本格式——在 WebAssembly 的 GitHub 仓库上面关于文本格式的更多解释。