JavaScript/URLSearchParams

Browserunterstützung
caniuse.com

Die URLSearchParams Schnittstelle wird verwendet, um den Querystring Anteil eines URL besser handhaben zu können. Zu diesem Zweck stellt ein URLSearchParams-Objekt die Liste von Namen und Werten, aus denen sich der Querystring zusammensetzt, in ähnlicher Form wie ein Map-Objekt bereit. Da ein Querystring den gleichen Namen mehrfach enthalten darf, gibt es aber auch leichte Unterschiede.

Allgemeines

Sie können ein URLSearchParams-Objekt über die searchParams-Eigenschaft eines URL erhalten, oder sie können es mittels der Konstruktorfunktion URLSearchParams neu erzeugen.

URLSearchParams-Objekte sind iterierbar, Sie können sie unmittelbar als Datenquelle einer for...of-Schleife verwenden. Der Iterator ist mit dem Ergebnis der entries()-Methode identisch.

Hinweis:

Wenn der Querystring mehrere Parameter mit gleichem Namen enthält, ist seine Verarbeitung serverseitig nicht mehr ganz einfach. Ohne weitere Maßnahmen würden Sie beispielsweise in PHP im $_GET-Superglobal nur den letzten übergebenen Wert vorfinden. Sie müssen entweder den Querystring von Hand zerlegen (zu finden in $_SERVER['QUERY_STRING']), oder - besser - Sie verwenden Parameternamen, die auf [] enden, damit PHP die Parameterwerte als Array bereitstellt.

Die Eigenschaften und Methoden der URLSearchParams-Schnittstelle werden durch das URLSearchParams.prototype-Objekt implementiert und an URLSearchParams-Objekte vererbt.

Konstruktor

const search = new URLSearchParams(options);

Methoden von URLSearchParams.prototype

• append()
• delete()
• entries()
• forEach()
• get()
• getAll()
• has()
• keys()
• set()
• sort()
• toString()
• values()

Eigenschaften von URLSearchParams.prototype

• size
• @@toStringTag

Konstruktor

Der Konstruktoraufruf new URLSearchParams() erzeugt ein neues URLSearchParams-Objekt. Das options-Argument ist optional; wenn Sie es weglassen, erhalten Sie ein Objekt, das einem leeren oder fehlenden Query-String entspricht.

Wenn Sie ein options-Argument übergeben, muss es einem der drei folgenden Muster entsprechen:

String

Eine URL-codierte Zeichenkette, die dem Querystring-Anteil eines URL entspricht. Ein führendes Fragezeichen wird ignoriert, die Übergabe einer vollständigen URL ist nicht zulässig.

Objekt

Ein einfaches Objekt, dessen Eigenschaftsnamen Strings sein müssen (d. h. keine Symbole). Die Werte dieser Eigenschaften sollten skalare Werte sein oder eine taugliche toString()-Implementierung besitzen, denn sie werden in Strings umgewandelt, bevor sie in das URLSearchParams-Objekt übernommen werden.

Ein iterierbares Objekt

Wenn Sie ein Objekt übergeben, das die iterable-Schnittstelle unterstützt, so wird sein Iterator durchlaufen. Er muss Arrays mit je zwei Einträgen bereitstellen. Der erste Eintrag in einem solchen Array liefert den Namen eines Queryparameters und muss daher ein String sein, der zweite Eintrag stellt den Wert dar und wird nach Bedarf in einen String konvertiert.

Beachten Sie:

• Wenn Sie an new URLSearchParams() einen vollständigen URL übergeben, führt das zu keinem Programmabbruch. Statt dessen wird der komplette Text vor dem ersten =-Zeichen als Parametername aufgefasst.
• Wenn Sie dem Konstruktor einen String übergeben, wird nicht jedes Zeichen darin vom Konstruktor prozentcodiert.
  • Das Zeichen # bleibt erhalten, was zu einem inkorrektem Fragmentteil in einem URL führen kann.
  • Zeichen, die in einer codierten URL zu finden sind (also + und ein %-Zeichen, auf das zwei Hexadezimalziffern folgen), bleiben unverändert erhalten. Sie können also einen Querystring, der bereits prozentcodiert ist, an den Konstruktor übergeben.
• Es ist nicht empfehlenswert, einen String, der einen Query-Parameter darstellt, von Hand zu erstellen und ihn dann an den URLSearchParams-Konstruktor zu übergeben. Sie müssten dann sicherstellen, dass jeder Parameterwert korrekt mit encodeURIComponent maskiert wird. Diesen Kontextwechsel nimmt Ihnen der Konstruktor ab, wenn Sie statt dessen ein iterierbares Objekt oder ein einfaches Objekt übergeben, oder wenn Sie die Werte mit set() oder append() speichern.
• Querystrings, die einen Namen ohne Wert enthalten, sind grundsätzlich zulässig (z. B. a&b=3). Solche Querystrings werden vom URLSearchParams-Konstruktor zwar verstanden, aber nicht exakt so gespeichert. Die beste Näherung, die Sie an einen solchen Querystring erreichen können, ist a=&b=3.

Eigenschaften

size

Die Eigenschaft size gibt an, wieviele Suchparameter der Query-String enthält.

Beispiel

const search = new URLSearchParms("?selfhtml=3&wiki=2");
console.log(search.size); 
// Ergebnis: 2

Methoden

toString()

Diese Methode wird von URLSearchParams.prototype überschrieben, um eine URL-konforme Stringdarstellung der Suchparameter zu erzeugen. Das einleitende Fragezeichen ist nicht Teil dieser Darstellung!

get()

Um auf einen gespeicherten Suchparameter zuzugreifen, verwenden Sie die get()-Methode.

  const paramValue = searchParams.get(name);

Falls der gleiche Parametername mehrfach verwendet wurde, liefert get() den ersten Wert zu diesem Namen zurück. Wurde der Name gar nicht verwenden, erhalten Sie null.

Beispiel

const search = new URLSearchParms("?selfhtml=3&wiki=artikel&wiki=mitmachen");
console.log(search.get("wiki")); 
// Ergebnis: artikel

getAll()

Wenn Sie damit umgehen müssen, dass ein Parametername mehrfach verwendet wird, dann verwenden Sie die getAll()-Methode. Sie liefert ein Array mit allen Werten, die zu diesem Namen gespeichert wurden. Sie erhalten immer ein Array zurück, auch wenn der Name gar nicht oder nur einmal verwendet wurde.

  const paramValues = searchParams.getAll(name);

Beispiel

const search = new URLSearchParms("?selfhtml=3&wiki=artikel&wiki=mitmachen");
console.log(search.getAll("selfhtml")); 
console.log(search.getAll("wiki")); 
console.log(search.getAll("forum")); 
// Ergebnis:
// ['3']
// ['artikel', 'mitmachen']
// []    (leeres Array)

set()

Mit Hilfe der set()-Methode speichern Sie einen Wert. Wenn unter dem angegebenen Name bereits ein oder mehrere Werte gespeichert sind, werden alle Werte überschrieben. Verwenden Sie append, wenn Sie unter einem Namen einen zweiten Wert speichern möchten.

  searchParams.set(name, wert);

Die Methode hat keinen Rückgabewert.

Beispiel

const search = new URLSearchParms("?selfhtml=3&wiki=artikel&wiki=mitmachen");
search.set("wiki", "viel arbeit"); 
console.log(search.getAll("wiki")); 
// Ergebnis:
// ['viel+arbeit']         Nur noch ein Eintrag, das Space ist durch + codiert

Das +-Zeichen stellt in URLs eine einfachere Codierung für Leerstellen dar als die %-Sequenz %20.

Beachten Sie:

• Wenn Sie an set() einen Wert übergeben, der bereits URL-codiert ist (also ein +-Zeichen oder eine %-Sequenz enthält), so werden diese Codierungszeichen erneut codiert. Das Ergebnis ist am Server nicht lesbar.
• Übergeben Sie als Wert null oder undefined, so erscheinen die Worte 'null' bzw. 'undefined' im Ergebnis. Einen Parameternamen ohne Wert können Sie nicht speichern, die beste Näherung daran erreichen Sie durch Übergabe eines Leerstrings.

append()

Die append()-Methode fügt dem URLSearchParams-Objekt einen neuen Suchparameter hinzu. Parameter, die den gleichen Namen tragen, bleiben unbeeinflusst.

  searchParams.append(name, wert);

Die Methode hat keinen Rückgabewert.

Beispiel

const search = new URLSearchParms("?selfhtml=3&wiki=viel+arbeit");
search.append("autor", "fleißig"); 
search.append("autor", "müde"); 
console.log(search.toString()); 
// Ergebnis:
// 'selfhtml=3&wiki=viel+arbeit&autor=flei%C3%9Fig&autor=m%C3%BCde'

Der Name autor existierte noch nicht und wurde deshalb durch den ersten append()-Aufruf neu angelegt. Die Zeichen ß und ü wurden als UTF-8 Sequenz prozentcodiert.

Beachten Sie: Beachten Sie die Hinweise zur Codierung im Abschnitt set().

delete()

Um Suchparameter aus dem URLSearchParams-Objekt zu löschen, verwenden Sie die Methode delete.

  searchParams.delete(name, wert);

Die Angabe eines Wertes ist optional. Wenn Sie ihn weglassen, werden alle Suchparameter mit diesen Namen gelöscht. Sie können den wert-Parameter verwenden, wenn es mehrere Suchparameter gleichen Namens gibt und Sie denjenigen entfernen möchten, der einen bestimmten Wert hat.

Die Methode hat keinen Rückgabewert.

Beispiel

const search = new URLSearchParms("?selfhtml=1&selfhtml=verein&wiki=viel+Arbeit&wiki=mitmachen");
search.delete("selfhtml"); 
search.delete("wiki", "viel Arbeit"); 
console.log(search.toString()); 
// Ergebnis:
// 'wiki=mitmachen'

Der delete("selfhtml")-Aufruf löscht alle Parameter mit dem Namen selfhtml. Der zweite Aufruf löscht lediglich den wiki-Parameter mit dem Wert 'viel Arbeit'.

has()

Die has()-Methode liefert Ihnen einen booleschen Wert, der angibt, ob der übergebene Name von einem der Suchparameter verwendet wird. Optional können Sie auch den erwarteten Parameterwert übergeben, was nützlich ist, wenn der Name mehrfach verwendet wird.

  const hasName = search.has(name);

Beispiel

const search = new URLSearchParms("?selfhtml=verein&wiki=viel+Arbeit");
console.log("Enthält selfhtml: ", search.has("selfhtml")); 
console.log("Enthält wiki=mitmachen: ", search.has("wiki", "mitmachen")); 
// Ergebnis:
// Enthält selfhtml: true
// Enthält wiki=mitmachen: false

keys(), entries(), values(), forEach()

Diese vier Methoden sind mit den gleichnamigen Methoden von Map-Objekten vergleichbar. Bitte lesen Sie dort nach.

Die Parameter werden in der Reihenfolge durchlaufen, wie sie dem URLSearchParams-Objekt hinzugefügt wurden (und wie toString() sie darstellt). Mehrfach verwendete Parameternamen erscheinen auch mehrfach.

sort()

Für den Fall, dass Ihr Server die Parameter in alphabetisch aufsteigender Reihenfolge erwartet (oder zumindest gleichnamige Parameter aufeinanderfolgend haben will), können Sie die gespeicherten Suchparameter aufsteigend nach ihrem Namen sortieren. Spezielle Sortierungen mit Hilfe einer Callback-Funktion sind nicht vorgesehen.

Sortiert wird gemäß der Unicode Codepoints der Parameternamen. Der verwendete Algorithmus ist stabil, d. h. die relative Reihenfolge von Parametern mit gleichem Namen bleibt garantiert erhalten.