URLPattern.search — Eigenschaft · JavaScript-Referenz

Signatur

get URLPattern.prototype.search

Beschreibung

Die schreibgeschützte Eigenschaft search gibt das Teilmuster zurück, das ein URLPattern auf den Query-String einer URL anwendet, also auf alles zwischen ? und #. Das führende Fragezeichen gehört nicht dazu.

Sinnvoll ist die Eigenschaft vor allem zum Prüfen und Debuggen von Mustern, etwa in Routern, Service Workern oder Tests. Man sieht daran, wie der Konstruktor die Eingabe normalisiert hat, z. B. ob ein Platzhalter gesetzt wurde oder Zeichen kodiert wurden.

Gibt man beim Erzeugen des Musters keinen Suchteil an, steht search auf dem Platzhalter "*". Dann passt jeder Query-String, auch ein leerer. Im Muster kann man benannte Gruppen (:name), Platzhalter (*) und reguläre Ausdrücke in Klammern verwenden. Die Treffer stehen später in result.search.groups, dem Ergebnis von exec().

Rückgabewert

Typ

string

Beschreibung

Das normalisierte Muster für den Suchteil ohne führendes ?. Ist keins angegeben, lautet der Wert "*".

Beispiele

Muster für den Suchteil auslesen

const pattern = new URLPattern({
  pathname: '/suche',
  search: 'q=:begriff'
});

console.log(pattern.search);

q=:begriff

Standardwert, wenn kein Suchteil angegeben ist

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

console.log(pattern.search);
// Jeder Query-String passt
console.log(pattern.test('https://example.com/buecher/42?ref=newsletter'));

* true

Suchbegriff mit exec() herausziehen

const suchRoute = new URLPattern({
  pathname: '/suche',
  search: 'q=:begriff'
});

const treffer = suchRoute.exec('https://example.com/suche?q=javascript');
console.log(treffer?.search.input);
console.log(treffer?.search.groups.begriff);

q=javascript javascript

Muster protokollieren, z. B. in einem Service Worker

const routen = [
  new URLPattern({ pathname: '/api/produkte', search: 'seite=:nr(\\d+)' }),
  new URLPattern({ pathname: '/api/*' })
];

for (const r of routen) {
  console.log(`${r.pathname} ? ${r.search}`);
}

/api/produkte ? seite=:nr(\d+) /api/* ? *

// Wichtig · Fallstricke

Die Reihenfolge der Parameter zählt: Das Muster wird mit dem rohen Query-String als Ganzes verglichen. search: 'q=:begriff' passt deshalb nicht auf ?lang=de&q=js. Wenn Reihenfolge oder zusätzliche Parameter egal sein sollen, besser search: '*' verwenden und die Werte dann mit URLSearchParams auswerten.
Nur lesbar: Die Eigenschaft hat nur einen Getter. Eine Zuweisung wird ignoriert und löst im Strict Mode einen TypeError aus. Für ein anderes Muster muss man ein neues URLPattern erzeugen.
Ein führendes ? in der Eingabe wird beim Normalisieren entfernt. Sonderzeichen können prozentkodiert werden. Der zurückgegebene String kann also von der ursprünglichen Eingabe abweichen.
Eine benannte Gruppe wie :begriff passt im Suchteil standardmäßig auf beliebige Zeichen, auch auf &. Soll sie enger sein, hilft ein eigener regulärer Ausdruck, z. B. :begriff([^&]+).
Kompatibilität: In Chromium-Browsern gibt es URLPattern schon länger. In Firefox und Safari ist es erst seit 2025 verfügbar. Für ältere Umgebungen gibt es das Paket urlpattern-polyfill.

Siehe auch

URLPattern URLPattern.exec() URLPattern.test() URLPattern.pathname URLPattern.hash URL.search URLSearchParams