Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

Match patterns

我們的志工尚未將此文章翻譯為 正體中文 (繁體) 版本。加入我們,幫忙翻譯!

Match patterns are a way to specify groups of URLs: a match pattern matches a specific set of URLs. They are used by WebExtensions in a few places, most notably to specify which documents to load content scripts into, and to specify which URLs to add webRequest listeners to.

APIs that use match patterns usually accept a list of match patterns, and will perform the appropriate action if the URL matches any of the patterns. See, for example, the content_scripts key in manifest.json.

Match pattern structure

All match patterns are specified as strings. Apart from the special "<all_urls>" pattern, match patterns consist of three parts: scheme, host, and path. The scheme and host are separated by "://".

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

scheme

The scheme component may take one of two forms:

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

host

The host component may take one of three forms:

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.

host is optional only if the scheme is "file".

Note that the wildcard may only appear at the start.

path

The path component must begin with a "/".

After that, it may subsequently contain any combination of the "*" wildcard and any of the characters that are allowed in URL paths. Unlike host, the path component may contain the "*" wildcard in the middle or at the end, and the "*" wildcard may appear more than once.

<all_urls>

The special value "<all_urls>" matches all URLs under any of the supported schemes: that is, "http", "https", "file", "ftp", "app".

Examples

Pattern Example matches Example non-matches

<all_urls>

Match all URLs.

https://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.

https://mozilla.org/

https://mozilla.org/

https://a.mozilla.org/

https://a.b.mozilla.org/

https://b.mozilla.org/path/

ftp://mozilla.org/
(unmatched scheme)

https://mozilla.com/
(unmatched host)

https://firefox.org/
(unmatched host)

*://mozilla.org/

Match all HTTP and HTTPS URLs that are hosted at exactly "mozilla.org/".

https://mozilla.org/

https://mozilla.org/

ftp://mozilla.org/
(unmatched scheme)

https://a.mozilla.org/
(unmatched host)

https://mozilla.org/a
(unmatched path)

ftp://mozilla.org/

Match only "ftp://mozilla.org/".

ftp://mozilla.org

https://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

https://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/

https://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

https://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 match patterns

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.

Testing match patterns

When writing WebExtensions you don't generally work with match patterns directly: usually you pass a match pattern string into an API, and the API constructs a match pattern and uses it to test URLs. However, if you're trying to work out which match pattern to use, or debugging a problem with one, it can be useful to be able to create and test match patterns directly. This section explains how to do this.

First, open the developer tool settings and check the setting marked "Enable browser chrome and add-on debugging toolboxes":

Next, open the "Browser Console":

This gives you a command line that you can use to execute privileged JavaScript in Firefox.

Because code running in the Browser Console has system privileges, any time you use it to run code, you need to understand exactly what the code is doing. That includes the code samples in this article.

Now paste this code into the command line and press enter:

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

This does two things:

  • imports "MatchPattern.jsm": this is the system module that implements match patterns. Specifically, the module contains a constructor for MatchPattern objects. MatchPattern objects define a function called matches(), that takes a URI and returns true or false.
  • imports "BrowserUtils.jsm": this includes a function makeURI(), that converts a string into an nsIURI object. nsIURI is the type that matches() expects to receive.

Now you can construct MatchPattern objects, construct URIs, and check whether the URIs match:

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

 

文件標籤與貢獻者

 此頁面的貢獻者: wbamberg
 最近更新: wbamberg,