匹配模式
匹配模式是一种指定网址组的方法:一个匹配模式匹配特定的一组 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 |
---|---|---|
Match all URLs. |
|
|
Match all HTTP and HTTPS URLs that are hosted at "mozilla.org" or one of its subdomains. |
|
|
Match all HTTP and HTTPS URLs that are hosted at exactly "mozilla.org/". |
|
|
Match only "ftp://mozilla.org/". |
ftp://mozilla.org |
|
Match HTTPS URLs on any host, whose path is "path". |
|
|
Match HTTPS URLs on any host, whose path is "path/". |
|
|
Match HTTPS URLs only at "mozilla.org", with any path. |
|
|
Match only this URL. |
https://mozilla.org/a/b/c/ |
Anything else. |
Match HTTPS URLs hosted on "mozilla.org", whose path contains a component "b" somewhere in the middle. |
|
|
Match any FILE URL whose path begins with "blah". |
|
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:
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 是否匹配:
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