匹配模式
====

匹配模式是一种指定网址组的方法：一个匹配模式匹配特定的一组 URL。它们由 WebExtensions 在几个地方使用，最明显的是指定要将内容脚本加载到哪些文档中，并指定要向其中添加 webRequest 侦听器的 URL。

使用匹配模板的 API 通常接收一个匹配模板的列表，当 URL 匹配任何模式时会恰当的运行。看个例子 在 manifest.json 中的 `content_scripts` 关键字。

匹配模式结构
------

所有的匹配模式用一个字符串来定义，而且都是"<all\_urls>" 模板的一部份，匹配模板包含三个部分：*scheme*、*host* 和 *path*。scheme 和 host 用 `://` 分隔。
```

<scheme>://<host><path>
```

### 方案

*scheme* 可能以下两种格式之一：

| Form | Matches |
| --- | --- |
| "\*" | Only "http" and "https". |
| One of "http", "https", "file", "ftp", "app". | Only the given scheme. |

### 主机

*host* 组件可以采取三种形式之一：:

| Form | Matches |
| --- | --- |
| "\*" | Any host. |
| "\*." followed by part of the hostname. | The given host and any of its subdomains. |
| A complete hostname, without wildcards. | Only the given host. |

只有当 *scheme* 是 "file" 是 *host* 可选的

值得注意的是通配符可能只会在开头显示。

### 路径

*path* 组件必须以“/”开头。

之后，它可能随后包含“\*”通配符和网址路径中允许的任何字符的任意组合。与 *host* 不同，*path* 组件可能在中间或末尾包含“\*”通配符，并且“\*”通配符可以多次出现。

### <all\_urls>

特殊值“<all\_urls>”匹配任何受支持方案下的所有 URL：即，"http", "https", "file", "ftp", "app"。

范例
--

| Pattern | Example matches | Example non-matches |
| --- | --- | --- |
| `<all_urls>`
Match all URLs. | `http://example.org/`
`ftp://files.somewhere.org/`
`https://a.org/some/path/` | `resource://a/b/c/`(unsupported scheme) |
| `*://*.mozilla.org/*`

 Match all HTTP and HTTPS URLs that are hosted at "mozilla.org" or one
 of its subdomains.
  | `http://mozilla.org/`
`https://mozilla.org/`
`http://a.mozilla.org/`
`http://a.b.mozilla.org/`
`https://b.mozilla.org/path/` | `ftp://mozilla.org/`(unmatched scheme)
`http://mozilla.com/`(unmatched host)
`http://firefox.org/`(unmatched host) |
| `*://mozilla.org/`

 Match all HTTP and HTTPS URLs that are hosted at exactly
 "mozilla.org/".
  | `http://mozilla.org/`
`https://mozilla.org/` | `ftp://mozilla.org/`(unmatched scheme)
`http://a.mozilla.org/`(unmatched host)
`http://mozilla.org/a`(unmatched path) |
| `ftp://mozilla.org/`
Match only "ftp://mozilla.org/". | `ftp://mozilla.org` | `http://mozilla.org/`(unmatched scheme)
`ftp://sub.mozilla.org/`(unmatched host)
`ftp://mozilla.org/path`(unmatched path) |
| `https://*/path`
Match HTTPS URLs on any host, whose path is "path". | `https://mozilla.org/path`
`https://a.mozilla.org/path`
`https://something.com/path` | `http://mozilla.org/path`(unmatched scheme)
`https://mozilla.org/path/`(unmatched path)
`https://mozilla.org/a`(unmatched path)
`https://mozilla.org/`(unmatched path) |
| `https://*/path/`
Match HTTPS URLs on any host, whose path is "path/". | `https://mozilla.org/path/`
`https://a.mozilla.org/path/`
`https://something.com/path`/ | `http://mozilla.org/path/`(unmatched scheme)
`https://mozilla.org/path`(unmatched path)
`https://mozilla.org/a`(unmatched path)
`https://mozilla.org/`(unmatched path) |
| `https://mozilla.org/*`
Match HTTPS URLs only at "mozilla.org", with any path. | `https://mozilla.org/`
`https://mozilla.org/path`
`https://mozilla.org/another`
`https://mozilla.org/path/to/doc` | `http://mozilla.org/path`(unmatched scheme)
`https://mozilla.com/path`(unmatched host) |
| `https://mozilla.org/a/b/c/`
Match only this URL. | `https://mozilla.org/a/b/c/` | Anything else. |
| `https://mozilla.org/*/b/*/`

 Match HTTPS URLs hosted on "mozilla.org", whose path contains a
 component "b" somewhere in the middle.
  | `https://mozilla.org/a/b/c/`
`https://mozilla.org/d/b/f/`
`https://mozilla.org/a/b/c/d/` | `https://mozilla.org/b/*/`(unmatched path)
`https://mozilla.org/a/b/`(unmatched path) |
| `file:///blah/*`
Match any FILE URL whose path begins with "blah". | `file:///blah/`
`file:///blah/bleh` | `file:///bleh/`(unmatched path) |

### 无效匹配模式

| Invalid pattern | Reason |
| --- | --- |
| `resource://path/` | Unsupported scheme. |
| `https://mozilla.org` | No path. |
| `https://mozilla.*.org/` | "\*" in host must be at the start. |
| `https://*zilla.org/` | "\*" in host must by the only character or be followed by ".". |
| `http*://mozilla.org/` | "\*" in scheme must be the only character. |
| `file://*` | Empty path: this should be "`file:///*`". |

测试匹配模式
------

当制作扩展时你通常不会跟直接使用匹配模板：通常你讲一个匹配模式传递给 API，然后 API 构造一个匹配模式并且使用他来测试 url。不过如果你正在尝试哪一种匹配模式可以被使用，或者调试一个匹配问题，那么直接创建和测试匹配模板的能力将变得有用，这个模块将解释如何做到这点。

首先，打开开发者工具设置，并且检查 "Enable browser chrome and add-on debugging toolboxes" 被打开：

然后打开 "Browser Console":

它给了你一个命令行以使你可以执行一些特权 javascript 代码。

**警告：** 因为运行在浏览器控制台的代码拥有系统特权，在任何时候都请你小心理解你的代码做了什么

现在粘贴以下代码到命令行然后按下 `enter`:


```js
Cu.import("resource://gre/modules/MatchPattern.jsm");
Cu.import("resource://gre/modules/BrowserUtils.jsm");
```


这做了两件事：

* 导入 "MatchPattern.jsm": 这是实现了匹配模板的系统模块，特别的，这个模块包含了 `MatchPattern` 对象。`MatchPattern` 对象定义了一个 `matches()` 方法，他需要一个 URL 然后返回 `true` 或者 `false`.
* 导入 "BrowserUtils.jsm": 包含了一个方法 `makeURI()`, 他转换一个字符串为一个 `nsIURI` 对象。`nsIURI` 是 `matches()` 方法需要接受的一个参数。

现在你可以构造 MatchPattern 对象，构造 URIs，并检查 URIs 是否匹配：


```js
var match = new MatchPattern("\*://mozilla.org/");

var uri = BrowserUtils.makeURI("https://mozilla.org/");
match.matches(uri); // < true

uri = BrowserUtils.makeURI("https://mozilla.org/path");
match.matches(uri); // < false
```