URLPattern.exec() — Methode · JavaScript-Referenz

Signatur

URLPattern.prototype.exec(input, baseURL)

Beschreibung

exec() ist das Gegenstück zu URLPattern.prototype.test(): test() sagt nur, ob eine URL passt. exec() gibt zusätzlich zurück, was gepasst hat. Das Ergebnis enthält für jeden URL-Bestandteil (protocol, username, password, hostname, port, pathname, search, hash) ein Objekt mit dem abgeglichenen Eingabetext (input) und den erfassten Gruppen (groups).

Typische Einsatzfälle sind clientseitiges Routing, Service Worker, die Anfragen nach URL-Mustern verteilen, und das Auslesen von Pfadparametern wie /users/:id. Dafür braucht man keine selbstgeschriebenen regulären Ausdrücke. Benannte Parameter (:id) stehen unter ihrem Namen in groups. Unbenannte Gruppen wie das Platzhalterzeichen * oder (\\d+) bekommen fortlaufende Schlüssel ("0", "1", …).

Als Eingabe akzeptiert exec() eine absolute URL als Zeichenkette, eine relative URL zusammen mit baseURL oder ein Objekt mit einzelnen URL-Teilen, zum Beispiel { pathname: '/books/42' }. Das Eingabeobjekt inputs im Ergebnis enthält genau die übergebenen Argumente. So lässt sich später nachvollziehen, womit abgeglichen wurde.

Parameter

Name	Typ	Default	Beschreibung
$input	string \| URLPatternInit	{}	Die zu prüfende URL: entweder eine absolute oder relative URL als Zeichenkette oder ein Objekt mit einzelnen URL-Teilen (`protocol`, `hostname`, `pathname`, `search`, `hash`, `baseURL` …).
$baseURL	string		Basis-URL, gegen die ein relativer `input`-String aufgelöst wird. Nur erlaubt, wenn `input` eine Zeichenkette ist.

Rückgabewert

Typ

URLPatternResult | null

Beschreibung

Ein Objekt mit inputs (Array der übergebenen Argumente) und je einem Eintrag pro URL-Bestandteil im Format { input: string, groups: Record<string, string | undefined> }. Passt die URL nicht zum Muster oder lässt sie sich nicht auswerten, wird null zurückgegeben.

Beispiele

Benannten Pfadparameter auslesen

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

const result = pattern.exec('https://example.com/books/123');

console.log(result.pathname.input);     // abgeglichener Pfad
console.log(result.pathname.groups.id); // erfasster Parameter
console.log(pattern.exec('https://example.com/authors/7'));

/books/123 123 null

Einfacher Router mit exec()

const routes = [
  { pattern: new URLPattern({ pathname: '/users/:userId' }), handler: ({ userId }) => `Profil von Nutzer ${userId}` },
  { pattern: new URLPattern({ pathname: '/posts/:slug/comments/:commentId(\\d+)' }), handler: ({ slug, commentId }) => `Kommentar ${commentId} zu "${slug}"` }
];

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

console.log(route('https://blog.example/users/42'));
console.log(route('https://blog.example/posts/hallo-welt/comments/9'));
console.log(route('https://blog.example/posts/hallo-welt/comments/abc'));

Profil von Nutzer 42 Kommentar 9 zu "hallo-welt" 404 – nicht gefunden

Platzhalter, relative URL und baseURL

const pattern = new URLPattern('/assets/*', 'https://cdn.example.com');

// Relative Eingabe wird gegen baseURL aufgelöst
const result = pattern.exec('/assets/img/logo.png', 'https://cdn.example.com');

console.log(result.pathname.groups[0]); // unbenannte Gruppe hat den Schlüssel "0"
console.log(result.hostname.input);
console.log(result.inputs);

img/logo.png cdn.example.com [ '/assets/img/logo.png', 'https://cdn.example.com' ]

Anfragen im Service Worker zuordnen

const apiPattern = new URLPattern({ pathname: '/api/:version/:resource{/:id}?' });

self.addEventListener('fetch', (event) => {
  const match = apiPattern.exec(event.request.url);
  if (!match) return; // Browser übernimmt normal

  const { version, resource, id } = match.pathname.groups;
  console.log(version, resource, id ?? '(Liste)');
});

v1 products (Liste) // bei /api/v1/products v1 products 17 // bei /api/v1/products/17

// Wichtig · Fallstricke

Gruppenwerte sind immer Zeichenketten. groups.id ist "123" und nicht 123. Bei Bedarf selbst umwandeln, z. B. mit Number().
Nicht getroffene optionale Gruppen wie {/:id}? haben den Wert undefined. Der Schlüssel ist trotzdem vorhanden.
Wird input als Objekt übergeben, darf kein zweites Argument baseURL folgen. Das löst einen TypeError aus. Die Basis gehört dann als Eigenschaft baseURL ins Objekt.
Ein relativer String ohne baseURL oder eine ungültige URL führt zu null, nicht zu einer Ausnahme. Ein null kann also „passt nicht“ oder „URL ungültig“ bedeuten.
Bestandteile, die im Konstruktor-Objekt nicht angegeben sind, gelten als Platzhalter *. Ihr Wert steht dann in groups["0"].
Wer nur wissen will, ob eine URL passt, sollte test() verwenden. Das spart das Aufbauen des Ergebnisobjekts.
Kompatibilität: In Chromium-Browsern seit Version 95 verfügbar, in Firefox seit 142 und in Safari seit 26. Für ältere Browser gibt es das Polyfill urlpattern-polyfill. Prüfen lässt sich die Unterstützung mit 'URLPattern' in globalThis.
Erfasste Gruppen sind unbereinigte Benutzereingaben. Vor der Verwendung in HTML, SQL oder Dateipfaden müssen sie geprüft bzw. maskiert werden.

Siehe auch

URLPattern.test() URL.parse() new URLPattern() Headers.get() Headers.set() new InterestEvent() new PannerNode()