URLSearchParams — Interface · JavaScript-Referenz

Signatur

URLSearchParams

Beschreibung

Das URLSearchParams-Interface definiert Hilfsmethoden für die Arbeit mit dem Query-String einer URL.

URLSearchParams-Objekte sind iterable, daher können sie direkt in einer for...of-Struktur verwendet werden, um über Schlüssel/Wert-Paare in derselben Reihenfolge zu iterieren, in der sie im Query-String erscheinen. Beispielsweise sind die folgenden zwei Zeilen äquivalent:

for (const [key, value] of mySearchParams) {}
for (const [key, value] of mySearchParams.entries()) {}

Obwohl URLSearchParams funktional einer Map ähnelt, kann es beim Iterieren aufgrund seiner Implementierung zu einigen Fallstricken kommen, die bei Map nicht auftreten.

Konstruktor:

URLSearchParams() — Gibt eine Instanz eines URLSearchParams-Objekts zurück.

Instanz-Eigenschaften:

size (schreibgeschützt) — Gibt die Gesamtzahl der Suchparameter-Einträge an.

Instanz-Methoden:

URLSearchParams[Symbol.iterator]() — Gibt einen iterator zurück, mit dem alle im Objekt enthaltenen Schlüssel/Wert-Paare in derselben Reihenfolge durchlaufen werden können, in der sie im Query-String erscheinen.
append() — Hängt ein angegebenes Schlüssel/Wert-Paar als neuen Suchparameter an.
delete() — Löscht Suchparameter aus der Liste aller Suchparameter, die einem Namen und optional einem Wert entsprechen.
entries() — Gibt einen iterator zurück, mit dem alle enthaltenen Schlüssel/Wert-Paare durchlaufen werden können.
forEach() — Ermöglicht die Iteration über alle Werte über eine callback-Funktion.
get() — Gibt den ersten Wert zurück, der dem angegebenen Suchparameter zugeordnet ist.
getAll() — Gibt alle Werte zurück, die einem gegebenen Suchparameter zugeordnet sind.
has() — Gibt einen booleschen Wert zurück, der angibt, ob ein bestimmter Parameter oder ein Parameter/Wert-Paar existiert.
keys() — Gibt einen iterator zurück, mit dem alle Schlüssel der Schlüssel/Wert-Paare durchlaufen werden können.
set() — Setzt den Wert, der einem gegebenen Suchparameter zugeordnet ist, auf den angegebenen Wert. Bei mehreren Werten werden die anderen gelöscht.
sort() — Sortiert alle Schlüssel/Wert-Paare (falls vorhanden) nach ihren Schlüsseln.
toString() — Gibt einen String zurück, der einen für eine URL geeigneten Query-String enthält.
values() — Gibt einen iterator zurück, mit dem alle Werte der Schlüssel/Wert-Paare durchlaufen werden können.

Beispiele

URLSearchParams verwenden

const paramsString = "q=URLUtils.searchParams&topic=api";
const searchParams = new URLSearchParams(paramsString);

// Iterating the search parameters
for (const p of searchParams) {
  console.log(p);
}

console.log(searchParams.has("topic")); // true
console.log(searchParams.has("topic", "fish")); // false
console.log(searchParams.get("topic") === "api"); // true
console.log(searchParams.getAll("topic")); // ["api"]
console.log(searchParams.get("foo") === null); // true
console.log(searchParams.append("topic", "webdev"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=api&topic=webdev"
console.log(searchParams.set("topic", "More webdev"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams&topic=More+webdev"
console.log(searchParams.delete("topic"));
console.log(searchParams.toString()); // "q=URLUtils.searchParams"

Suchparameter können auch ein Objekt sein

const paramsObj = { foo: "bar", baz: "bar" };
const searchParams = new URLSearchParams(paramsObj);

console.log(searchParams.toString()); // "foo=bar&baz=bar"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // "bar"

window.location parsen

// Assume page has location:
// https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams?foo=a
const paramsString = window.location.search;
const searchParams = new URLSearchParams(paramsString);
console.log(searchParams.get("foo")); // a

Doppelte Suchparameter

const paramStr = "foo=bar&foo=baz";
const searchParams = new URLSearchParams(paramStr);

console.log(searchParams.toString()); // "foo=bar&foo=baz"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // bar, only returns the first value
console.log(searchParams.getAll("foo")); // ["bar", "baz"]

Kein URL-Parsing

const paramsString1 = "http://example.com/search?query=%40";
const searchParams1 = new URLSearchParams(paramsString1);

console.log(searchParams1.has("query")); // false
console.log(searchParams1.has("http://example.com/search?query")); // true

console.log(searchParams1.get("query")); // null
console.log(searchParams1.get("http://example.com/search?query")); // "@" (equivalent to decodeURIComponent('%40'))

const paramsString2 = "?query=value";
const searchParams2 = new URLSearchParams(paramsString2);
console.log(searchParams2.has("query")); // true

const url = new URL("http://example.com/search?query=%40");
const searchParams3 = new URLSearchParams(url.search);
console.log(searchParams3.has("query")); // true

Prozent-Kodierung

// Creation from parsing a string: percent-encoding is decoded
const params = new URLSearchParams("%24%25%26=%28%29%2B");
// Retrieving all keys/values: only decoded values are returned
console.log([...params]); // [["$%&", "()+"]]
// Getting an individual value: use the decoded key and get the decoded value
console.log(params.get("$%&")); // "()+"
console.log(params.get("%24%25%26")); // null
// Setting an individual value: use the unencoded key and value
params.append("$%&$#@+", "$#&*@#()+");
// Serializing: percent-encoding is applied
console.log(params.toString());
// "%24%25%26=%28%29%2B&%24%25%26%24%23%40%2B=%24%23%26*%40%23%28%29%2B"

Bereits kodierte Schlüssel werden erneut kodiert

const params = new URLSearchParams();

params.append("%24%26", "value");
params.toString(); // "%2524%2526=value"

Pluszeichen bewahren

const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'

const searchParams = new URLSearchParams(`bin=${base64Data}`); // 'bin=E+AXQB+A'
const binQuery = searchParams.get("bin"); // 'E AXQB A', '+' is replaced by spaces

console.log(atob(binQuery) === rawData); // false

append() statt String-Interpolation verwenden

const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'

const searchParams = new URLSearchParams();
searchParams.append("bin", base64Data); // 'bin=E%2BAXQB%2BA'
const binQuery = searchParams.get("bin"); // 'E+AXQB+A'

console.log(atob(binQuery) === rawData); // true

Interaktion mit URL.searchParams

const url = new URL("https://example.com/?a=b ~");
console.log(url.href); // "https://example.com/?a=b%20~"
console.log(url.searchParams.toString()); // "a=b+%7E"
// This should be a no-op, but it changes the URL's query to the
// serialization of its searchParams
url.searchParams.sort();
console.log(url.href); // "https://example.com/?a=b+%7E"

const url2 = new URL("https://example.com?search=1234&param=my%20param");
console.log(url2.search); // "?search=1234&param=my%20param"
url2.searchParams.delete("search");
console.log(url2.search); // "?param=my+param"

Leerer Wert vs. kein Wert

const emptyVal = new URLSearchParams("foo=&bar=baz");
console.log(emptyVal.get("foo")); // returns ''
const noEquals = new URLSearchParams("foo&bar=baz");
console.log(noEquals.get("foo")); // also returns ''
console.log(noEquals.toString()); // 'foo=&bar=baz'

// Wichtig · Fallstricke

Der `URLSearchParams`-Konstruktor parst _keine_ vollständigen URLs. Er entfernt jedoch ein führendes `?` aus einem String, falls vorhanden. Konstruiere `URLSearchParams`-Objekte niemals mit dynamisch interpolierten Strings, sondern verwende stattdessen die `append()`-Methode, die alle Zeichen unverändert interpretiert.

Siehe auch

URL

← Vorheriger Eintrag URLPattern.username Nächster Eintrag → URLSearchParams.append()