Übereinstimmungsmuster

Übereinstimmungsmuster sind eine Methode, um Gruppen von URLs zu spezifizieren: Ein Übereinstimmungsmuster passt auf eine bestimmte Menge von URLs. Sie werden in den WebExtensions-APIs an einigen Stellen verwendet, insbesondere um zu definieren, in welche Dokumente Content-Skripte geladen werden sollen, und um anzugeben, bei welchen URLs webRequest Listener hinzugefügt werden sollen.

APIs, die Übereinstimmungsmuster verwenden, akzeptieren in der Regel eine Liste von Übereinstimmungsmustern und führen die entsprechende Aktion aus, wenn die URL einem der Muster entspricht. Siehe zum Beispiel den content_scripts-Schlüssel in manifest.json.

Struktur des Übereinstimmungsmusters

Hinweis: Einige Browser unterstützen bestimmte Schemes nicht. Überprüfen Sie die Browser-Kompatibilitätstabelle für Details.

Alle Übereinstimmungsmuster werden als Strings angegeben. Abgesehen vom speziellen Muster <all_urls> bestehen Übereinstimmungsmuster aus drei Teilen: scheme, host und path. Scheme und Host sind durch :// getrennt.

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

scheme

Die Komponente scheme kann eine von zwei Formen annehmen:

Form Übereinstimmungen
* Nur "http" und "https" und in einigen Browsern auch "ws" und "wss".
Eines von http, https, ws, wss, ftp, data, file oder (chrome-)extension. Nur das angegebene Scheme.

host

Die Komponente host kann eine von drei Formen annehmen:

Form Übereinstimmungen
* Jeder Host.
*. gefolgt von einem Teil des Hostnamens. Der angegebene Host und alle seine Subdomains.
Ein vollständiger Hostname ohne Platzhalter. Nur der angegebene Host.

host darf keine Portnummer enthalten.

host ist nur dann optional, wenn das scheme "file" ist.

Beachten Sie, dass das Platzhalterzeichen nur am Anfang stehen darf.

path

Die Komponente path muss mit einem / beginnen.

Danach kann sie jede Kombination aus dem Platzhalterzeichen * und den Zeichen enthalten, die in URL-Pfaden oder Abfragezeichenfolgen erlaubt sind. Im Gegensatz zu host darf die Komponente path das Platzhalterzeichen * in der Mitte oder am Ende enthalten, und das Platzhalterzeichen * darf mehr als einmal vorkommen.

Der Wert für den path wird mit dem String abgeglichen, der aus dem URL-Pfad plus der URL-Abfragezeichenfolge besteht. Dies schließt gegebenenfalls das ? zwischen den beiden ein, wenn die Abfragezeichenfolge in der URL vorhanden ist. Wenn Sie beispielsweise URLs in einer beliebigen Domain abgleichen möchten, bei denen der URL-Pfad mit foo.bar endet, müssen Sie ein Array von Übereinstimmungsmustern wie ["*://*/*foo.bar", "*://*/*foo.bar?*"] verwenden. Das ?* ist notwendig, um zu verhindern, dass das abschließende * auf den URL-Pfad anstelle der URL-Abfragezeichenfolge angewendet wird.

Weder der URL-Fragment-Identifier noch das #, das ihm vorangeht, werden als Teil des path betrachtet.

Hinweis: Die String-Formatierung für das Pfadmuster sollte keine Portnummer enthalten. Das Hinzufügen eines Ports, wie in: http://localhost:1234/*, führt dazu, dass das Übereinstimmungsmuster ignoriert wird. Jedoch passt http://localhost:1234 zu http://localhost/*.

<all_urls>

Der spezielle Wert <all_urls> stimmt mit allen URLs unter jedem unterstützten Scheme überein, das sind "http", "https", "ws", "wss", "ftp", "data" und "file".

Beispiele

Muster Beispielmatches Beispiel-Nicht-Übereinstimmungen

<all_urls>

Übereinstimmung mit allen URLs.

http://example.org/

https://a.org/some/path/

ws://sockets.somewhere.org/

wss://ws.example.com/stuff/

ftp://files.somewhere.org/

resource://a/b/c/
(nicht unterstütztes Scheme)

ftps://files.somewhere.org/
(nicht unterstütztes Scheme)

*://*/*

Übereinstimmung mit allen HTTP-, HTTPS- und WebSocket-URLs.

http://example.org/

https://a.org/some/path/

ws://sockets.somewhere.org/

wss://ws.example.com/stuff/

ftp://ftp.example.org/
(nicht passendes Scheme)

file:///a/
(nicht passendes Scheme)

*://*.mozilla.org/*

Übereinstimmung mit allen HTTP-, HTTPS- und WebSocket-URLs, die auf "mozilla.org" oder einer seiner Subdomains gehostet werden.

http://mozilla.org/

https://mozilla.org/

http://a.mozilla.org/

http://a.b.mozilla.org/

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

ws://ws.mozilla.org/

wss://secure.mozilla.org/something

ftp://mozilla.org/
(nicht passendes Scheme)

http://mozilla.com/
(nicht passender Host)

http://firefox.org/
(nicht passender Host)

*://mozilla.org/

Übereinstimmung mit allen HTTP-, HTTPS- und WebSocket-URLs, die exakt unter "mozilla.org/" gehostet werden.

http://mozilla.org/

https://mozilla.org/

ws://mozilla.org/

wss://mozilla.org/

ftp://mozilla.org/
(nicht passendes Scheme)

http://a.mozilla.org/
(nicht passender Host)

http://mozilla.org/a
(nicht passender Pfad)

ftp://mozilla.org/

Übereinstimmung nur mit "ftp://mozilla.org/".

 ftp://mozilla.org

http://mozilla.org/
(nicht passendes Scheme)

ftp://sub.mozilla.org/
(nicht passender Host)

ftp://mozilla.org/path
(nicht passender Pfad)

https://*/path

Übereinstimmung mit HTTPS-URLs auf jedem Host, deren Pfad "path" ist.

https://mozilla.org/path

https://a.mozilla.org/path

https://something.com/path

http://mozilla.org/path
(nicht passendes Scheme)

https://mozilla.org/path/
(nicht passender Pfad)

https://mozilla.org/a
(nicht passender Pfad)

https://mozilla.org/
(nicht passender Pfad)

https://mozilla.org/path?foo=1
(nicht passender Pfad aufgrund der URL-Abfragezeichenfolge)

https://*/path/

Übereinstimmung mit HTTPS-URLs auf jedem Host, deren Pfad "path/" ist und die keine URL-Abfragezeichenfolge haben.

https://mozilla.org/path/

https://a.mozilla.org/path/

https://something.com/path/

http://mozilla.org/path/
(nicht passendes Scheme)

https://mozilla.org/path
(nicht passender Pfad)

https://mozilla.org/a
(nicht passender Pfad)

https://mozilla.org/
(nicht passender Pfad)

https://mozilla.org/path/?foo=1
(nicht passender Pfad aufgrund der URL-Abfragezeichenfolge)

https://mozilla.org/*

Übereinstimmung mit HTTPS-URLs nur bei "mozilla.org", mit jedem URL-Pfad und jeder URL-Abfragezeichenfolge.

https://mozilla.org/

https://mozilla.org/path

https://mozilla.org/another

https://mozilla.org/path/to/doc

https://mozilla.org/path/to/doc?foo=1

http://mozilla.org/path
(nicht passendes Scheme)

https://mozilla.com/path
(nicht passender Host)

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

Übereinstimmung nur mit dieser URL oder mit dieser URL mit einem beliebigem URL-Fragment.

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

https://mozilla.org/a/b/c/#section1

 Alles andere.

https://mozilla.org/*/b/*/

Übereinstimmung mit HTTPS-URLs, die auf "mozilla.org" gehostet werden, deren Pfad irgendwo in der Mitte eine Komponente "b" enthält. URLs mit Abfragezeichenfolgen werden übereinstimmen, wenn die Zeichenfolge mit einem / endet.

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

https://mozilla.org/d/b/f/

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

https://mozilla.org/a/b/c/d/#section1

https://mozilla.org/a/b/c/d/?foo=/

https://mozilla.org/a?foo=21314&bar=/b/&extra=c/

https://mozilla.org/b/*/
(nicht passender Pfad)

https://mozilla.org/a/b/
(nicht passender Pfad)

https://mozilla.org/a/b/c/d/?foo=bar
(nicht passender Pfad aufgrund der URL-Abfragezeichenfolge)

file:///blah/*

Übereinstimmung mit jeder FILE-URL, deren Pfad mit "blah" beginnt.

file:///blah/

file:///blah/bleh

 file:///bleh/
(nicht passender Pfad)

Ungültige Übereinstimmungsmuster

Ungültiges Muster Grund
resource://path/ Nicht unterstütztes Scheme.
https://mozilla.org Kein Pfad vorhanden.
https://mozilla.*.org/ "*" im Host muss am Anfang stehen.
https://*zilla.org/ "*" im Host muss das einzige Zeichen sein oder von "." gefolgt werden.
http*://mozilla.org/ "*" im Scheme muss das einzige Zeichen sein.
https://mozilla.org:80/ Der Host darf keine Portnummer enthalten.
*://* Leerzeichen: das sollte *://*/* sein.
file://* Leerzeichen: das sollte file:///* sein.

Browser-Kompatibilität