URLPattern — Schnittstelle · JavaScript-Referenz

Signatur

interface URLPattern

Beschreibung

URLPattern ist das zentrale Interface der URL Pattern API. Ein Muster beschreibt die einzelnen Bestandteile einer URL – protocol, username, password, hostname, port, pathname, search und hash – mit einer Syntax, die an die bekannte Routing-Syntax von path-to-regexp (Express, Next.js u. a.) angelehnt ist: :id für benannte Gruppen, * als Platzhalter, {…}? für optionale Abschnitte und (\\d+) für eigene reguläre Ausdrücke.

Typische Einsatzfälle sind clientseitiges Routing in Single-Page-Apps, das Abfangen von Anfragen im Service Worker (fetch-Event) und serverseitiges Routing in Node.js, Deno oder Cloudflare Workers. Statt fehleranfälliger eigener RegExp-Konstrukte erhält man eine lesbare, standardisierte Musterbeschreibung.

Die wichtigsten Mitglieder:

new URLPattern(input, baseURL?, options?) – erzeugt ein Muster aus einem String oder einem Objekt mit Einzelbestandteilen.
test(input, baseURL?) – gibt true oder false zurück, je nachdem ob die URL passt.
exec(input, baseURL?) – liefert ein Ergebnisobjekt mit inputs und den erkannten groups je Bestandteil, oder null.
Schreibgeschützte Eigenschaften protocol, hostname, pathname, search, hash usw. mit dem normalisierten Teilmuster sowie hasRegExpGroups.

Nicht angegebene Bestandteile passen bei der Objektform auf alles (*). Bei der String-Form ohne Basis-URL müssen hingegen Protokoll und Host im Muster enthalten sein.

Parameter

Name	Typ	Default	Beschreibung
$input	string \| URLPatternInit	{}	Das Muster – entweder als vollständiger URL-Musterstring (z. B. `'https://example.com/books/:id'`) oder als Objekt mit Einzelbestandteilen wie `{ pathname: '/books/:id' }`. Eine Objektform darf zusätzlich `baseURL` enthalten.
$baseURL	string		Basis-URL, gegen die ein relativer Musterstring aufgelöst wird. Nur zulässig, wenn `input` ein String ist.
$options	{ ignoreCase?: boolean }	{ ignoreCase: false }	Optionen. Mit `ignoreCase: true` wird ohne Beachtung der Groß-/Kleinschreibung verglichen.

Rückgabewert

Typ

URLPattern

Beschreibung

Eine neue URLPattern-Instanz. Bei ungültiger Mustersyntax wird ein TypeError ausgelöst.

Beispiele

Muster erzeugen und mit test() prüfen

const pattern = new URLPattern({ pathname: '/books/:id' });

console.log(pattern.test('https://example.com/books/123'));
console.log(pattern.test('https://example.com/authors/5'));
console.log(pattern.pathname);

true false /books/:id

Benannte Gruppen mit exec() auslesen

const pattern = new URLPattern('https://shop.example.com/:category/:product(\\d+)');

const result = pattern.exec('https://shop.example.com/laptops/4711');
if (result) {
  const { category, product } = result.pathname.groups;
  console.log(`Kategorie: ${category}, Produkt-ID: ${product}`);
}

// Keine Zahl -> kein Treffer
console.log(pattern.exec('https://shop.example.com/laptops/abc'));

Kategorie: laptops, Produkt-ID: 4711 null

Einfacher Router für eine Single-Page-App

const routes = [
  { pattern: new URLPattern({ pathname: '/' }), view: () => 'Startseite' },
  { pattern: new URLPattern({ pathname: '/users/:id' }), view: ({ id }) => `Profil von Nutzer ${id}` },
  { pattern: new URLPattern({ pathname: '/docs/*' }), view: (g) => `Doku: ${g[0]}` },
];

const render = (url) => {
  for (const { pattern, view } of routes) {
    const match = pattern.exec(url);
    if (match) return view(match.pathname.groups);
  }
  return '404 – Seite nicht gefunden';
};

console.log(render('https://app.example.com/users/42'));
console.log(render('https://app.example.com/docs/api/url'));
console.log(render('https://app.example.com/impressum'));

Profil von Nutzer 42 Doku: api/url 404 – Seite nicht gefunden

Anfragen im Service Worker gezielt abfangen

// sw.js
const apiPattern = new URLPattern({
  hostname: 'api.example.com',
  pathname: '/v1/images/:name.:ext(png|jpg|webp)',
});

self.addEventListener('fetch', (event) => {
  if (!apiPattern.test(event.request.url)) return;

  event.respondWith((async () => {
    const cache = await caches.open('images-v1');
    const cached = await cache.match(event.request);
    if (cached) return cached;
    const response = await fetch(event.request);
    await cache.put(event.request, response.clone());
    return response;
  })());
});

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser unterstützen URLPattern seit Version 95, Firefox seit 142 und Safari seit 26. Für ältere Umgebungen gibt es das Polyfill urlpattern-polyfill. Zur Feature-Erkennung eignet sich 'URLPattern' in globalThis.
String- vs. Objektform: new URLPattern('/books/:id') ohne baseURL wirft einen TypeError. Für reine Pfadmuster die Objektform { pathname: '/books/:id' } verwenden oder eine Basis-URL mitgeben.
Query-Parameter: search wird als roher String verglichen – die Reihenfolge der Parameter spielt eine Rolle. Für flexible Abfragen besser nur den Pfad matchen und danach URLSearchParams auswerten.
Escaping: Sonderzeichen wie :, *, (, { und ? haben eine Bedeutung im Muster und müssen mit \\ maskiert werden (im JS-String als '\\\\').
Performance/Sicherheit: Eigene RegExp-Gruppen (hasRegExpGroups === true) sind langsamer und können bei ungünstigen Ausdrücken zu ReDoS führen. Muster einmalig erzeugen und wiederverwenden, nicht pro Anfrage neu anlegen.
Die Gruppenwerte sind prozentkodiert, wie sie in der URL stehen – bei Bedarf mit decodeURIComponent() dekodieren.

Siehe auch

URL RegExp XRLayer Attr CanvasPattern