匹配模式

匹配模式是一种指定网址组的方法：一个匹配模式匹配特定的一组 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