URL Pattern API

Baseline 2025

Neu verfgbar

Seit September 2025 funktioniert diese Funktion auf aktuellen Gerten und in aktuellen Browserversionen. Auf lteren Gerten oder in lteren Browsern funktioniert sie mglicherweise nicht.

Mehr erfahren
Vollstndige Kompatibilitt anzeigen

Hinweis: Diese Funktion ist in Web Workers verfgbar.

Die URL Pattern API definiert eine Syntax, die zur Erstellung von URL-Musterabgleichern verwendet wird. Diese Muster knnen mit URLs oder einzelnen URL-Komponenten abgeglichen werden.

Konzepte und Nutzung

Muster werden mit der URLPattern-Schnittstelle angegeben. Die Mustersyntax basiert auf der Syntax der path-to-regexp-Bibliothek. Muster knnen enthalten:

Wrtliche Zeichenfolgen, die genau bereinstimmen.
Platzhalter (/posts/*), die jedes Zeichen abgleichen.
Benannte Gruppen (/books/:id), die einen Teil der passenden URL extrahieren.
Nicht erfassende Gruppen (/books{/old}?), die Teile eines Musters optional machen oder mehrfach bereinstimmen lassen.
RegExp-Gruppen (/books/(\\d+)), die beliebig komplexe regulre Ausdrcke erzeugen. Beachten Sie, dass die Klammern nicht Teil des regulren Ausdrucks sind, sondern deren Inhalt als regulrer Ausdruck definieren. Einige APIs verbieten die Verwendung von regulren Ausdrucksgruppen in URLPattern-Objekten. Die hasRegExpGroups-Eigenschaft zeigt an, ob regulre Ausdrucksgruppen verwendet werden oder nicht.

Details zur Syntax finden Sie im Abschnitt Mustersyntax weiter unten.

Schnittstellen

URLPattern: Reprsentiert ein Muster, das mit URLs oder Teilen von URLs abgeglichen werden kann. Das Muster kann erfassende Gruppen enthalten, die Teile der passenden URL extrahieren.

Mustersyntax

Die Syntax fr Muster basiert auf der path-to-regexp JavaScript-Bibliothek. Diese Syntax ist hnlich wie die, die in Ruby on Rails oder JavaScript-Frameworks wie Express oder Next.js verwendet wird.

Fester Text und Erfassungsgruppen

Jedes Muster kann eine Kombination aus festem Text und Gruppen enthalten. Der feste Text ist eine Zeichenfolge, die genau bereinstimmt. Gruppen stimmen mit einer beliebigen Zeichenfolge basierend auf den Abgleichsregeln berein. Jeder URL-Teil hat seine eigenen Standardregeln, die unten erklrt werden, aber sie knnen berschrieben werden.

// A pattern matching some fixed text
const pattern = new URLPattern({ pathname: "/books" });
console.log(pattern.test("https://example.com/books")); // true
console.log(pattern.exec("https://example.com/books").pathname.groups); // {}

// A pattern matching with a named group
const pattern = new URLPattern({ pathname: "/books/:id" });
console.log(pattern.test("https://example.com/books/123")); // true
console.log(pattern.exec("https://example.com/books/123").pathname.groups); // { id: '123' }

Segment-Platzhalter

Standardmig wird eine Gruppe, die den pathname-Teil der URL abgleicht, alle Zeichen auer dem Schrgstrich (/) abgleichen. Im hostname-Teil wird die Gruppe alle Zeichen auer dem Punkt (.) abgleichen. In allen anderen Teilen wird die Gruppe alle Zeichen abgleichen. Der Segment-Platzhalter ist nicht gierig, was bedeutet, dass er die krzeste mgliche Zeichenfolge abgleicht.

Regex-Abgleicher

Anstatt die Standardabgleichsregeln fr eine Gruppe zu verwenden, knnen Sie ein Regex fr jede Gruppe angeben, indem Sie es in Klammern setzen. Dieses Regex definiert die Abgleichsregeln fr die Gruppe. Unten ist ein Beispiel fr einen Regex-Abgleicher auf einer benannten Gruppe, die die Gruppe nur abgleicht, wenn sie eine oder mehrere Ziffern enthlt:

const pattern1 = new URLPattern("/books/:id(\\d+)", "https://example.com");
console.log(pattern1.test("https://example.com/books/123")); // true
console.log(pattern1.test("https://example.com/books/abc")); // false
console.log(pattern1.test("https://example.com/books/")); // false

Sie knnen auch Regex verwenden, wenn Sie ein URLPattern mit der Objektsyntax konstruieren.

const pattern2 = new URLPattern({ pathname: "/books/:id(\\d+)" });
console.log(pattern2.test("https://example.com/books/123")); // true
console.log(pattern2.test("https://example.com/books/abc")); // false
console.log(pattern2.test("https://example.com/books/")); // false

Pathname-Abgleich

Der pathname-URL-Teil beginnt immer mit /. Wenn Sie das / in Ihrem regulren Ausdruck weglassen, schlgt der Abgleich fehl. Das unten stehende Beispiel

// Doesn't match, because omits the `/`
const pattern1 = new URLPattern({ pathname: "(b.*)" });
console.log(pattern1.test("https://example.com/b")); // false
console.log(pattern1.test("https://example.com/ba")); // false

Die folgenden Beispiele enthalten das /:

// Matches URL where path is exactly "/b"
const pattern2 = new URLPattern({ pathname: "(/b)" });
console.log(pattern2.test("https://example.com/b")); // true
console.log(pattern2.test("https://example.com/ba")); // false

// Matches URL where path is /b followed by any number of characters
const pattern3 = new URLPattern({ pathname: "(/b.*)" });
console.log(pattern3.test("https://example.com/b")); // true
console.log(pattern3.test("https://example.com/ba")); // true

Start- und Endanker von Zeilen

Der Startanker (^) und der Endanker ($) werden verwendet, um Muster am Anfang bzw. Ende der Prfzeichenkette zu verankern. Whrend diese fr den Beginn und das Ende eines URL-Teils angegeben werden knnen, sind sie redundant. Dies liegt daran, dass alle URL-Teile implizit von dem Anker ^ am Anfang und von dem Anker $ am Ende gefolgt werden.

Der folgende Code zeigt, dass es egal ist, ob das ^ angegeben wird oder nicht. Das Beispiel verwendet ein Muster im protocol-URL-Teil, aber die anderen Teile der URL verhalten sich gleich.

// with `^` in protocol
const pattern1 = new URLPattern({ protocol: "(^https?)" });
console.log(pattern1.test("https://example.com/index.html")); // true

// without `^` in protocol
const pattern2 = new URLPattern({ protocol: "(https?)" });
console.log(pattern2.test("https://example.com/index.html")); // true

Der unten stehende Code zeigt, dass es egal ist, ob das $ angegeben wird oder nicht.

// with `$` in pathname
const pattern1 = new URLPattern({ pathname: "(/path$)" });
console.log(pattern1.test("https://example.com/path")); // true

// without `$` in pathname
const pattern2 = new URLPattern({ pathname: "(/path)" });
console.log(pattern2.test("https://example.com/path")); // true

// with `$` in hash
const pattern3 = new URLPattern({ hash: "(hash$)" });
console.log(pattern3.test("https://example.com/#hash")); // true

// without `$` in hash
const pattern4 = new URLPattern({ hash: "(hash)" });
console.log(pattern4.test("https://example.com/#hash")); // true

Lookahead- und Lookbehind-Bedingungen

Lookahead und Lookbehind Bedingungen erlauben Ihnen, anzugeben, dass Text vor oder hinter der aktuellen Parseposition einem bestimmten Muster entspricht, ohne dass dieses Match erfasst oder die Zeichen konsumiert werden.

Es gibt vier Arten von Bedingungen:

(?=...): Eine positive Lookahead-Bedingung gibt ein Muster an, dem die folgenden Zeichen entsprechen mssen.
(?!...): Eine negative Lookahead-Bedingung gibt ein Muster an, dem die folgenden Zeichen nicht entsprechen drfen.
(?<=...): Eine positive Lookbehind-Bedingung gibt ein Muster an, dem die vorhergehenden Zeichen entsprechen mssen.
(?<!...): Eine negative Lookbehind-Bedingung gibt ein Muster an, dem die vorhergehenden Zeichen nicht entsprechen drfen.

Seien Sie vorsichtig bei der Verwendung von Lookahead- und Lookbehind-Bedingungen mit URLPattern, da es Verhalten gibt, das Sie als unintuitiv empfinden knnten. Beispielsweise wrden Sie erwarten, dass die folgende Lookahead-Bedingung einen pathname von /ab abgleicht, dies geschieht jedoch nicht.

const pattern = new URLPattern({ pathname: "(/a(?=b))" });
console.log(pattern.test("https://example.com/ab")); // false

Die URLPattern-Engine gleicht die Prfzeichenkette gegen das pathname-Muster ab, findet zuerst das Match fr /a und stellt dann fest, dass das nchste Zeichen in der Test-URL b ist dieses jedoch nicht konsumiert. Die Engine setzt den Abgleich der Test-URL am nicht konsumierten Zeichen b fort, aber es bleibt nichts im Muster, um es abzugleichen, was dazu fhrt, dass das Match fehlschlgt.

Damit der Abgleich funktioniert, muss das Muster alle Zeichen in der Testzeichenkette konsumieren. Um das b-Zeichen zu konsumieren, knnten Sie b am Ende des Ausdrucks hinzufgen, einen . verwenden, um ein beliebiges Zeichen abzugleichen, oder .*, um alle Zeichen nach der Lookahead-Bedingung abzugleichen:

// positive-lookahead
const pattern1 = new URLPattern({ pathname: "(/a(?=b).*)" });
console.log(pattern1.test("https://example.com/ab")); // true
console.log(pattern1.test("https://example.com/ax")); // false

Das nchste Beispiel zeigt ein negatives Lookahead-Match fr /a, dem kein b folgt. Beachten Sie, dass die Bedingung von .* gefolgt wird, um das von der Bedingung erfasste Zeichen zu konsumieren.

// negative-lookahead - matches /a<not b><anything>
const pattern2 = new URLPattern({ pathname: "(/a(?!b).*)" });
console.log(pattern2.test("https://example.com/ab")); // false
console.log(pattern2.test("https://example.com/ax")); // true

Das folgende Beispiel zeigt ein positives Lookbehind-Match, das bei einem Pfadnamen wie /ba bereinstimmt. Das Muster passt auf /, dann . um das nchste Zeichen zu konsumieren, gefolgt von der Bedingung, dass das vorherige Zeichen ein b war, und dann einem a.

// positive-lookbehind
const pattern = new URLPattern({ pathname: "(/.(?<=b)a)" });
console.log(pattern.test("https://example.com/ba")); // true
console.log(pattern.test("https://example.com/xa")); // false

Dieses Beispiel zeigt ein negatives Lookbehind-Match, das bei einem Pfadnamen wie /<not b>a bereinstimmt. Das Muster passt auf /, dann . um das nchste Zeichen (x) zu konsumieren, gefolgt von der Bedingung, dass das vorherige Zeichen kein b war, und dann einem a.

// negative-lookbehind
const pattern4 = new URLPattern({ pathname: "(/.*(?<!b)a)" });
console.log(pattern4.test("https://example.com/ba")); // false
console.log(pattern4.test("https://example.com/xa")); // true

Weitere Einschrnkungen von Regex-Abgleichern

Einige andere Regex-Muster funktionieren mglicherweise nicht wie erwartet:

Klammern mssen in Bereichsausdrcken innerhalb von URLPattern entkommen werden, obwohl sie dies in RegExp nicht tun.

new URLPattern({ pathname: "([()])" }); // throws
new URLPattern({ pathname: "([\\(\\)])" }); // ok

new RegExp("[()]"); // ok
new RegExp("[\\(\\)]"); // ok

Nicht benannte und benannte Gruppen

Gruppen knnen entweder benannt oder unbenannt sein. Benannte Gruppen werden spezifiziert, indem der Gruppenname mit einem Doppelpunkt (:) vorangestellt wird. Regex-Gruppen, die nicht von einem Doppelpunkt und einem Namen vorangestellt sind, sind unbenannt. Unbenannte Gruppen sind im Abgleichsergebnis numerisch indiziert, basierend auf ihrer Reihenfolge im Muster.

// A named group
const pattern = new URLPattern("/books/:id(\\d+)", "https://example.com");
console.log(pattern.exec("https://example.com/books/123").pathname.groups); // { id: '123' }

// An unnamed group
const pattern = new URLPattern("/books/(\\d+)", "https://example.com");
console.log(pattern.exec("https://example.com/books/123").pathname.groups); // { '0': '123' }

Gruppenmodifikatoren

Gruppen knnen auch Modifikatoren haben. Diese werden nach dem Gruppennamen (oder nach dem Regex, wenn es eines gibt) angegeben. Es gibt drei Modifikatoren: ?, um die Gruppe optional zu machen, +, um die Gruppe ein- oder mehrmals zu wiederholen, und *, um die Gruppe null- oder mehrmals zu wiederholen.

// An optional group
const pattern = new URLPattern("/books/:id?", "https://example.com");
console.log(pattern.test("https://example.com/books/123")); // true
console.log(pattern.test("https://example.com/books")); // true
console.log(pattern.test("https://example.com/books/")); // false
console.log(pattern.test("https://example.com/books/123/456")); // false
console.log(pattern.test("https://example.com/books/123/456/789")); // false

// A repeating group with a minimum of one
const pattern = new URLPattern("/books/:id+", "https://example.com");
console.log(pattern.test("https://example.com/books/123")); // true
console.log(pattern.test("https://example.com/books")); // false
console.log(pattern.test("https://example.com/books/")); // false
console.log(pattern.test("https://example.com/books/123/456")); // true
console.log(pattern.test("https://example.com/books/123/456/789")); // true

// A repeating group with a minimum of zero
const pattern = new URLPattern("/books/:id*", "https://example.com");
console.log(pattern.test("https://example.com/books/123")); // true
console.log(pattern.test("https://example.com/books")); // true
console.log(pattern.test("https://example.com/books/")); // false
console.log(pattern.test("https://example.com/books/123/456")); // true
console.log(pattern.test("https://example.com/books/123/456/789")); // true

Gruppentrennzeichen

Muster knnen auch Gruppentrennzeichen enthalten. Dies sind Teile eines Musters, die von geschweiften Klammern ({}) umgeben sind. Diese Gruppentrennzeichen werden im Abgleichsergebnis nicht wie erfassende Gruppen erfasst, knnen jedoch wie Gruppen Modifikatoren haben. Wenn Gruppentrennzeichen nicht durch einen Modifikator gendert werden, werden sie behandelt, als ob die Elemente in ihnen einfach Teil des bergeordneten Musters wren. Gruppentrennzeichen drfen keine anderen Gruppentrennzeichen enthalten, knnen jedoch alle anderen Musteritems enthalten (erfassende Gruppen, Regex, Platzhalter oder fester Text).

// A group delimiter with a ? (optional) modifier
const pattern = new URLPattern("/book{s}?", "https://example.com");
console.log(pattern.test("https://example.com/books")); // true
console.log(pattern.test("https://example.com/book")); // true
console.log(pattern.exec("https://example.com/books").pathname.groups); // {}

// A group delimiter without a modifier
const pattern = new URLPattern("/book{s}", "https://example.com");
console.log(pattern.pathname); // /books
console.log(pattern.test("https://example.com/books")); // true
console.log(pattern.test("https://example.com/book")); // false

// A group delimiter containing a capturing group
const pattern = new URLPattern({ pathname: "/blog/:id(\\d+){-:title}?" });
console.log(pattern.test("https://example.com/blog/123-my-blog")); // true
console.log(pattern.test("https://example.com/blog/123")); // true
console.log(pattern.test("https://example.com/blog/my-blog")); // false

Automatisches Prfixing von Gruppen in Pfadnamen

In Mustern, die gegen den pathname-Teil einer URL abgeglichen werden, erhalten Gruppen automatisch ein Schrgstrich- (/) Prfix, wenn die Gruppendefinition von einem Schrgstrich (/) vorangestellt wird. Dies ist ntzlich fr Gruppen mit Modifikatoren, da es ermglicht, dass wiederholte Gruppen wie erwartet funktionieren.

Wenn Sie das automatische Prfixing nicht wnschen, knnen Sie es deaktivieren, indem Sie die Gruppe mit Gruppentrennzeichen ({}) umgeben. Gruppentrennzeichen haben kein automatisches Prfixing-Verhalten.

// A pattern with an optional group, preceded by a slash
const pattern = new URLPattern("/books/:id?", "https://example.com");
console.log(pattern.test("https://example.com/books/123")); // true
console.log(pattern.test("https://example.com/books")); // true
console.log(pattern.test("https://example.com/books/")); // false

// A pattern with a repeating group, preceded by a slash
const pattern = new URLPattern("/books/:id+", "https://example.com");
console.log(pattern.test("https://example.com/books/123")); // true
console.log(pattern.test("https://example.com/books/123/456")); // true
console.log(pattern.test("https://example.com/books/123/")); // false
console.log(pattern.test("https://example.com/books/123/456/")); // false

// Segment prefixing does not occur outside of pathname patterns
const pattern = new URLPattern({ hash: "/books/:id?" });
console.log(pattern.test("https://example.com#/books/123")); // true
console.log(pattern.test("https://example.com#/books")); // false
console.log(pattern.test("https://example.com#/books/")); // true

// Disabling segment prefixing for a group using a group delimiter
const pattern = new URLPattern({ pathname: "/books/{:id}?" });
console.log(pattern.test("https://example.com/books/123")); // true
console.log(pattern.test("https://example.com/books")); // false
console.log(pattern.test("https://example.com/books/")); // true

Platzhalterzeichen

Das Platzhalterzeichen (*) ist eine Abkrzung fr eine nicht benannte erfassende Gruppe, die alle Zeichen null- oder mehrmals abgleicht. Sie knnen dies berall im Muster platzieren. Das Platzhalterzeichen ist gierig, was bedeutet, dass es die lngste mgliche Zeichenfolge abgleichen wird.

// A wildcard at the end of a pattern
const pattern = new URLPattern("/books/*", "https://example.com");
console.log(pattern.test("https://example.com/books/123")); // true
console.log(pattern.test("https://example.com/books")); // false
console.log(pattern.test("https://example.com/books/")); // true
console.log(pattern.test("https://example.com/books/123/456")); // true

// A wildcard in the middle of a pattern
const pattern = new URLPattern("/*.png", "https://example.com");
console.log(pattern.test("https://example.com/image.png")); // true
console.log(pattern.test("https://example.com/image.png/123")); // false
console.log(pattern.test("https://example.com/folder/image.png")); // true
console.log(pattern.test("https://example.com/.png")); // true

Abschlieende Schrgstriche im Pfadnamen werden standardmig nicht abgeglichen

Abschlieende Schrgstriche in einem Pfadnamen werden nicht automatisch abgeglichen. Das unten stehende Beispiel zeigt, dass ein URLPattern-Abgleich fr einen Pfadnamen von /books https://example.com/books abgleichen wird, aber nicht https://example.com/books/ (und umgekehrt):

const patternSlash = new URLPattern({ pathname: "/books/" });
console.log(patternSlash.test("https://example.com/books")); // false
console.log(patternSlash.test("https://example.com/books/")); // true

const patternNoSlash = new URLPattern({ pathname: "/books" });
console.log(patternNoSlash.test("https://example.com/books")); // true
console.log(patternNoSlash.test("https://example.com/books/")); // false

Wenn Sie beides abgleichen mchten, mssen Sie ein Abgleichsmuster verwenden, das beides zulsst. Der einfachste Ansatz ist die Verwendung eines Gruppentrennzeichens, das einen Schrgstrich enthlt, gefolgt vom optionalen Modifikator. Dies wird das Muster mit oder ohne abschlieenden Schrgstrich abgleichen.

const patternOptionalSlash = new URLPattern({ pathname: "/books{/}?" });
console.log(patternOptionalSlash.test("https://example.com/books")); // true
console.log(patternOptionalSlash.test("https://example.com/books/")); // true

Musternormalisierung

Wenn ein Muster geparst wird, wird es automatisch in eine kanonische Form normalisiert. Zum Beispiel werden Unicode-Zeichen im pathname-Prozent-codiert, punycode-codiert im hostname, Standardportnummern werden weggelassen, Pfade wie /foo/./bar/ werden zu /foo/bar zusammengefasst, etc. Darber hinaus gibt es einige Musterreprsentationen, die zur selben zugrunde liegenden Bedeutung parsen, wie foo und {foo}. Solche Flle werden auf die einfachste Form normalisiert. In diesem Fall wird {foo} zum Beispiel zu foo normalisiert.

Vererbung von einer Basis-URL

Sowohl die in URLPattern definierten Abgleichsmuster als auch die in URLPattern.test() und URLPattern.exec() verwendeten Test-URLs ermglichen die Eingaben mit einer optionalen Basis-URL zu spezifizieren (diese Basis-URL ist ein separates Parameter bei der Angabe der URL als Zeichenfolge und eine separate Eigenschaft bei der Angabe der URL als Objekt).

Wenn eine Basis-URL definiert ist, knnen URL-Teile von der Basis-URL erben und zur Festlegung von Teilen des Musters oder der Test-URL verwendet werden. Die URL-Auflsung ist hnlich dem, was Sie erwarten wrden, wenn Sie eine URL auflsen, die mit einer Basis-URL spezifiziert ist.

Der username und das password werden niemals von der Basis-URL geerbt.

Nur die "spezifischeren" URL-Teile als der speziellste Teil, der in der Eingabe definiert ist, werden von der Basis-URL geerbt. Die folgende Liste zeigt die Reihenfolge der Spezifitt:

protocol (am spezifischsten), hostname, port, pathname, search, hash
protocol, hostname, port, username, password

Das bedeutet, wenn beispielsweise das protocol in der Eingabe-URL angegeben ist, ist nichts spezifischer, daher wird nichts von der Basis-URL geerbt. Wenn jedoch der pathname-Teil in der Eingabe angegeben ist, knnen das protocol, der hostname und der port von der Basis-URL geerbt werden, aber search und hash werden nicht.

Beachten Sie, dass URL-Komponenten, die in der Zeichenfolge/dem Eingabeobjekt nicht angegeben oder von der Basis-URL geerbt werden, standardmig den Platzhalterwert ("*") fr ein URLPattern und die leere Zeichenfolge ("") fr eine Test-URL annehmen.

Gro- und Kleinschreibung

Die URL Pattern API behandelt viele Teile der URL standardmig als Gro- und Kleinschreibung unterscheidend beim Abgleichen. Im Gegensatz dazu verwenden viele clientseitige JavaScript-Frameworks eine Gro- und Kleinschreibung ignorierende URL-Abgleichung. Eine ignoreCase-Option ist im URLPattern()-Konstruktor verfgbar, um bei Bedarf eine Gro- und Kleinschreibung ignorierende Abgleichung zu ermglichen.

// Case-sensitive matching by default
const pattern = new URLPattern("https://example.com/2022/feb/*");
console.log(pattern.test("https://example.com/2022/feb/xc44rsz")); // true
console.log(pattern.test("https://example.com/2022/Feb/xc44rsz")); // false

Das Einstellen der ignoreCase-Option auf true im Konstruktor schaltet alle Abgleichsoperationen fr das angegebene Muster auf Gro- und Kleinschreibung ignorierend um:

// Case-insensitive matching
const pattern = new URLPattern("https://example.com/2022/feb/*", {
  ignoreCase: true,
});
console.log(pattern.test("https://example.com/2022/feb/xc44rsz")); // true
console.log(pattern.test("https://example.com/2022/Feb/xc44rsz")); // true

Beispiele

Filter fr eine bestimmte URL-Komponente

Das folgende Beispiel zeigt, wie ein URLPattern eine spezifische URL-Komponente filtert. Wenn der URLPattern()-Konstruktor mit einem strukturierten Objekt von Komponentenmuster aufgerufen wird, nehmen alle fehlenden Komponenten standardmig den Platzhalterwert * an.

// Construct a URLPattern that matches a specific domain and its subdomains.
// All other URL components default to the wildcard `*` pattern.
const pattern = new URLPattern({
  hostname: "{*.}?example.com",
});

console.log(pattern.hostname); // '{*.}?example.com'

console.log(pattern.protocol); // '*'
console.log(pattern.port); // '*'
console.log(pattern.username); // '*'
console.log(pattern.password); // '*'
console.log(pattern.pathname); // '*'
console.log(pattern.search); // '*'
console.log(pattern.hash); // '*'

console.log(pattern.test("https://example.com/foo/bar")); // true
console.log(pattern.test({ hostname: "cdn.example.com" })); // true
console.log(pattern.test("custom-protocol://example.com/other/path?q=1")); // true

// Prints `false` because the hostname component does not match
console.log(pattern.test("https://cdn-example.com/foo/bar"));

Konstruieren eines URLPattern aus einer vollstndigen URL-Zeichenfolge

Das folgende Beispiel zeigt, wie man ein URLPattern aus einer vollstndigen URL-Zeichenfolge mit eingebetteten Mustern konstruiert. Zum Beispiel kann ein : sowohl das Protokollsuffix einer URL sein, wie https:, als auch der Beginn einer benannten Mustersgruppe, wie :foo. Es "funktioniert einfach", wenn keine Mehrdeutigkeit besteht, ob ein Zeichen Teil der URL-Syntax oder der Mustersyntax ist.

// Construct a URLPattern that matches URLs to CDN servers loading jpg images.
// URL components not explicitly specified result in the wild string ("*")
const pattern = new URLPattern("https://cdn-*.example.com/*.jpg");

console.log(pattern.protocol); // 'https'
console.log(pattern.hostname); // 'cdn-*.example.com'
console.log(pattern.pathname); // '/*.jpg'

console.log(pattern.username); // '*'
console.log(pattern.password); // '*'
console.log(pattern.search); // '*'
console.log(pattern.hash); // '*'

// `true`
console.log(
  pattern.test("https://cdn-1234.example.com/product/assets/hero.jpg"),
);

// `true` because the search pattern defaults to wildcard
console.log(
  pattern.test("https://cdn-1234.example.com/product/assets/hero.jpg?q=1"),
);

Konstruieren eines URLPattern mit einer mehrdeutigen URL-Zeichenfolge

Das folgende Beispiel zeigt, wie ein URLPattern aus einer mehrdeutigen Zeichenfolge konstruiert wird, wobei Zeichen als Teil der Mustersyntax behandelt werden. In diesem Fall knnte das :-Zeichen das Suffix der Protokollkomponente oder es knnte das Prfix fr eine benannte Gruppe im Muster sein. Der Konstruktor entscheidet, dies als Teil des Musters zu behandeln und bestimmt daher, dass es sich um ein relatives Pfadnamensmuster handelt. Da keine Basis-URL vorhanden ist, kann der relative Pfadname nicht aufgelst werden und es wird ein Fehler ausgelst.

// Throws because this is interpreted as a single relative pathname pattern
// with a ":foo" named group and there is no base URL.
const pattern = new URLPattern("data:foo*");

Escape von Zeichen zur Auflsung ambiger URLPattern-Konstruktorzeichenfolgen

Das folgende Beispiel zeigt, wie ein mehrdeutiges Konstruktorzeichenfolgenzeichen entkommen werden kann, um als URL-Trennzeichen anstatt als Musterzeichen behandelt zu werden. Hier wird : als \\: entkommen.

// Constructs a URLPattern treating the `:` as the protocol suffix.
const pattern = new URLPattern("data\\:foo*");

console.log(pattern.protocol); // 'data'
console.log(pattern.pathname); // 'foo*'
console.log(pattern.username); // '*'
console.log(pattern.password); // '*'
console.log(pattern.hostname); // ''
console.log(pattern.port); // ''
console.log(pattern.search); // '*'
console.log(pattern.hash); // '*'

console.log(pattern.test("data:foobar")); // true

Verwendung von Basis-URLs fr test() und exec()

Das folgende Beispiel zeigt, wie test() und exec() Basis-URLs verwenden knnen.

const pattern = new URLPattern({ hostname: "example.com", pathname: "/foo/*" });

console.log(pattern.protocol); // '*'
console.log(pattern.pathname); // '/foo/*'
console.log(pattern.username); // '*'
console.log(pattern.password); // '*'
console.log(pattern.hostname); // 'example.com'
console.log(pattern.port); // '*'
console.log(pattern.search); // '*'
console.log(pattern.hash); // '*'

// `true` as the hostname is inherited from `baseURL` property
// (so is the protocol, but that is matched by the pattern wildcard)
console.log(
  pattern.test({
    pathname: "/foo/bar",
    baseURL: "https://example.com/baz",
  }),
);

// Prints `true` as the hostname in the second argument base URL matches.
console.log(pattern.test("/foo/bar", "https://example.com/baz"));

// Throws because the second argument cannot be passed with the object input.
try {
  pattern.test({ pathname: "/foo/bar" }, "https://example.com/baz");
} catch (e) {}

// The `exec()` method takes the same arguments as `test()`.
const result = pattern.exec("/foo/bar", "https://example.com/baz");
console.log(result.pathname.input); // '/foo/bar'
console.log(result.pathname.groups[0]); // 'bar'
console.log(result.hostname.input); // 'example.com'

Verwendung von Basis-URLs im URLPattern-Konstruktor

Das folgende Beispiel zeigt, wie Basis-URLs auch zur Konstruktion des URLPattern verwendet werden knnen. Die Basis-URL wird strikt als URL behandelt und kann keine Mustersyntax selbst enthalten.

Das Muster erbt nur URL-Teile von der Basis-URL, die weniger spezifisch sind als die in den anderen Eigenschaften.

In diesem Fall ist pathname angegeben, sodass das Protokoll und der Host geerbt werden knnen, aber nicht die Suche, das Fragment, der Benutzername oder das Passwort. Die Eigenschaften, die nicht geerbt werden, nehmen standardmig die Platzhalterzeichenfolge ("*"). Die Ausnahme bildet der Port, der auf die leere Zeichenfolge gesetzt wird, da der hostname von der Basis-URL bernommen wird (der einen "Standardport"-Wert impliziert).

const pattern1 = new URLPattern({
  pathname: "/foo/*",
  baseURL: "https://example.com",
});

console.log(pattern1.protocol); // 'https'
console.log(pattern1.hostname); // 'example.com'
console.log(pattern1.pathname); // '/foo/*'
console.log(pattern1.username); // '*'
console.log(pattern1.password); // '*'
console.log(pattern1.port); // ''
console.log(pattern1.search); // '*'
console.log(pattern1.hash); // '*'

// Equivalent to pattern1
const pattern2 = new URLPattern("/foo/*", "https://example.com");

// Throws because a relative constructor string must have a base URL to resolve
// against.
try {
  const pattern3 = new URLPattern("/foo/*");
} catch (e) {}

Zugriff auf erfasste Gruppenwerte

Das folgende Beispiel zeigt, wie Eingabewerte, die Mustern entsprechen, spter aus dem exec()-Ergebnisobjekt abgerufen werden knnen.

Die input-Eigenschaft ist die Zeichenfolge, die mit dem Muster bereinstimmt: in diesem Fall ist es cdn.example.com. Die groups-Eigenschaft enthlt erfasste Gruppen, die basierend auf ihrer Reihenfolge nummeriert und entweder nach Nummer bei unbenannten oder nach Name bei benannten Gruppen indiziert sind. In diesem Fall gibt es nur eine unbenannte Gruppe fr die Platzhaltereigenschaft mit dem Wert cdn.

const pattern = new URLPattern({ hostname: "*.example.com" });
const result = pattern.exec({ hostname: "cdn.example.com" });

console.log(result.hostname); // {"groups": {"0": "cdn"}, "input": "cdn.example.com"}

Zugriff auf erfasste benannte Gruppenwerte

Das folgende Beispiel zeigt, wie Gruppen benutzerdefinierte Namen erhalten knnen, die verwendet werden knnen, um den passenden Wert im Ergebnisobjekt abzurufen.

Die Abgleichsmuster im Muster werden durch das :-Symbol gefolgt von einem Namen angegeben. Die gleichen Namen erscheinen dann als Schlssel in der groups-Eigenschaft, wobei die passenden Werte der bereinstimmende Teil der Test-URL sind. Die input-Eigenschaft enthlt den gesamten Teil der URL, der mit dem pathname-Muster bereinstimmt.

// Construct a URLPattern using matching groups with custom names.

const pattern = new URLPattern({ pathname: "/:product/:user/:action" });
const result = pattern.exec({ pathname: "/store/wanderview/view" });

console.log(result.pathname);
/*
{
    "groups": {
        "product": "store",
        "user": "wanderview",
        "action": "view"
    },
    "input": "/store/wanderview/view"
}
*/

// These names can then be later used to access the matched values
// in the result object, such as "user" below.
console.log(result.pathname.groups.user); // 'wanderview'

Regulrer Ausdruck mit unbenannter Gruppe

Das folgende Beispiel zeigt, wie eine Abgleichsgruppe einen regulren Ausdruck verwenden kann, um entweder /foo oder /bar in einer Test-URL abzugleichen. Die Gruppe ist unbenannt, wird also im Ergebnis ber eine Indexnummer referenziert.

const pattern = new URLPattern({ pathname: "/(foo|bar)" });

console.log(pattern.test({ pathname: "/foo" })); // true
console.log(pattern.test({ pathname: "/bar" })); // true
console.log(pattern.test({ pathname: "/baz" })); // false

const result = pattern.exec({ pathname: "/foo" });
console.log(result.pathname.groups[0]); // 'foo'

Regulrer Ausdruck mit benannter Gruppe

Das folgende Beispiel zeigt, wie Sie einen benutzerdefinierten regulren Ausdruck mit einer benannten Gruppe verwenden.

Die Gruppe wird type genannt und stimmt mit einem Pfad berein, der entweder /foo oder /bar ist.

const pattern = new URLPattern({ pathname: "/:type(foo|bar)" });
const result = pattern.exec({ pathname: "/foo" });

console.log(result.pathname.groups.type); // 'foo'

Erfasste Gruppen optional machen

Das folgende Beispiel zeigt, wie eine Abgleichsgruppe optional gemacht wird, indem ein ?-Modifikator danach platziert wird.

Fr die pathname-Komponente verursacht dies auch, dass ein vorausgehendes /-Zeichen als optionales Prfix zur Gruppe behandelt wird.

const pattern = new URLPattern({ pathname: "/product/(index.html)?" });

console.log(pattern.test({ pathname: "/product/index.html" })); // true
console.log(pattern.test({ pathname: "/product" })); // true

const pattern2 = new URLPattern({ pathname: "/product/:action?" });

console.log(pattern2.test({ pathname: "/product/view" })); // true
console.log(pattern2.test({ pathname: "/product" })); // true

Platzhalter knnen ebenfalls optional gemacht werden. Dies mag keinen Sinn ergeben, da sie bereits die leere Zeichenfolge abgleichen, aber es macht auch das Prfix / optional in einem Pfadnamenmuster.

const pattern3 = new URLPattern({ pathname: "/product/*?" });

console.log(pattern3.test({ pathname: "/product/wanderview/view" })); // true
console.log(pattern3.test({ pathname: "/product" })); // true
console.log(pattern3.test({ pathname: "/product/" })); // true

Erfasste Gruppen wiederholbar machen

Das folgende Beispiel zeigt, wie eine Abgleichsgruppe wiederholbar gemacht wird, indem ein +-Modifikator danach platziert wird. In der pathname-Komponente behandelt dies auch das /-Prfix als speziell, so dass es effektiv der Anfang der wiederholten Gruppe ist.

const pattern = new URLPattern({ pathname: "/product/:action+" });
const result = pattern.exec({ pathname: "/product/do/some/thing/cool" });

console.log(result.pathname);
// { "groups": { "action": "do/some/thing/cool" }, "input": "/product/do/some/thing/cool" }

Beachten Sie, dass /product nicht bereinstimmt, da es nicht von / und mindestens einem Zeichen gefolgt wird.

console.log(pattern.test({ pathname: "/product" })); // false
console.log(pattern.test({ pathname: "/product/" })); // false
console.log(pattern.test({ pathname: "/product/do" })); // true
console.log(pattern.test({ pathname: "/product/do/" })); // false

Erfasste Gruppen optional und wiederholbar machen

Das folgende Beispiel zeigt, wie eine Abgleichsgruppe sowohl optional als auch wiederholbar gemacht wird. Tun Sie dies, indem Sie einen *-Modifikator nach der Gruppe platzieren. Auch hier behandelt die pathname-Komponente das /-Prfix speziell.

Es wird sowohl optional als auch mit der Gruppe wiederholt.

const pattern = new URLPattern({ pathname: "/product/:action*" });
const result = pattern.exec({ pathname: "/product/do/some/thing/cool" });

console.log(result.pathname);
// { "groups": { "action": "do/some/thing/cool" }, "input": "/product/do/some/thing/cool" }

Beachten Sie, dass im Gegensatz zum vorherigen Beispiel /product bereinstimmt, da die wiederholten Segmente, einschlielich /, optional sind. Es muss jedoch mindestens ein Zeichen vorhanden sein, das nach einem Schrgstrich erfasst wird, um die wiederholte Gruppe abzugleichen.

console.log(pattern.test({ pathname: "/product" })); // true
console.log(pattern.test({ pathname: "/product/" })); // false
console.log(pattern.test({ pathname: "/product/do" })); // true
console.log(pattern.test({ pathname: "/product/do/" })); // false

Ein benutzerdefiniertes Prfix oder Suffix fr einen optionalen oder wiederholten Modifikator verwenden

Das folgende Beispiel zeigt, wie geschweifte Klammern (ein Gruppentrennzeichen) mit einer benannten Gruppe verwendet werden knnen, um ein benutzerdefiniertes Prfix und/oder Suffix festzulegen, auf das ein nachfolgender ?, * oder +-Modifikator angewendet wird.

Zum Beispiel stimmt {:subdomain.}* gegen jede Subdomain von example.com und die Domne selbst ab. Der Abgleich wird der benannten Gruppe "subdomain" zugewiesen.

const pattern = new URLPattern({ hostname: "{:subdomain.}*example.com" });
const result = pattern.exec({ hostname: "foo.bar.example.com" });

console.log(pattern.test({ hostname: "example.com" })); // true
console.log(pattern.test({ hostname: "foo.bar.example.com" })); // true
console.log(pattern.test({ hostname: ".example.com" })); // false

console.log(result.hostname);
// { "groups": { "subdomain": "foo.bar" }, "input": "foo.bar.example.com" }

Text optional oder wiederholbar machen ohne erfasste Gruppe

Das folgende Beispiel zeigt, wie geschweifte Klammern verwendet werden knnen, um feste Textwerte optional oder wiederholbar zu machen, ohne eine erfasste Gruppe zu verwenden.

Das untenstehende Muster stimmt entweder mit /product oder /product/ berein, aber da Gruppentrennzeichen standardmig nicht erfassend sind, wird das Ergebnis nicht in einer entsprechenden Abgleichsgruppe gefunden.

const pattern = new URLPattern({ pathname: "/product{/}?" });

console.log(pattern.test({ pathname: "/product" })); // true
console.log(pattern.test({ pathname: "/product/" })); // true

const result = pattern.exec({ pathname: "/product/" });
console.log(result.pathname.groups); // {}

Verwendung mehrerer Komponenten und Funktionen gleichzeitig

Das folgende Beispiel zeigt, wie viele Funktionen ber mehrere URL-Komponenten hinweg kombiniert werden knnen.

const pattern = new URLPattern({
  protocol: "http{s}?",
  username: ":user?",
  password: ":pass?",
  hostname: "{:subdomain.}*example.com",
  pathname: "/product/:action*",
});

const result = pattern.exec(
  "http://foo:bar@sub.example.com/product/view?q=12345",
);

console.log(result.username.groups.user); // 'foo'
console.log(result.password.groups.pass); // 'bar'
console.log(result.hostname.groups.subdomain); // 'sub'
console.log(result.pathname.groups.action); // 'view'

Spezifikationen

Spezifikation
URL Pattern

Browser-Kompatibilitt

Siehe auch

Ein Polyfill von URLPattern ist auf GitHub verfgbar
Die von URLPattern verwendete Mustersyntax ist hnlich der Syntax, die von path-to-regexp verwendet wird

Help improve MDN

War diese bersetzung hilfreich?

Ja Nein

Erfahren Sie, wie Sie beitragen knnen Diese Seite wurde automatisch aus dem Englischen bersetzt.

bersetzung auf GitHub anzeigen Fehler mit dieser bersetzung melden

URL Pattern API
Interfaces
1. URLPattern