Dieser Inhalt wurde automatisch aus dem Englischen übersetzt, und kann Fehler enthalten.Erfahre mehr über dieses Experiment.
URLSearchParams
Baseline Widely available *
This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2018.
* Some parts of this feature may have varying levels of support.
Hinweis: Diese Funktion ist inWeb Workers verfügbar.
DasURLSearchParams-Interface definiert Hilfsmethoden zur Arbeit mit der Abfragezeichenfolge einer URL.
URLSearchParams-Objekte sinditerierbar, sodass sie direkt in einerfor...of-Struktur verwendet werden können, um über Schlüssel/Wert-Paare in der gleichen Reihenfolge zu iterieren, wie sie in der Abfragezeichenfolge erscheinen. Zum Beispiel sind die folgenden zwei Zeilen gleichwertig:
for (const [key, value] of mySearchParams) {}for (const [key, value] of mySearchParams.entries()) {}ObwohlURLSearchParams funktional einemMap ähnelt, kann es beim Iterieren einigeFallstricke geben, denenMap aufgrund seiner Implementierung nicht begegnet.
Konstruktor
URLSearchParams()Gibt eine Instanz eines
URLSearchParams-Objekts zurück.
Instanzeigenschaften
sizeSchreibgeschütztGibt die Gesamtzahl der Einträge von Suchparametern an.
Instanzmethoden
URLSearchParams[Symbol.iterator]()Gibt einen
Iteratorzurück, der die Iteration durch alle in diesem Objekt enthaltenen Schlüssel/Wert-Paare in der gleichen Reihenfolge wie in der Abfragezeichenfolge erlaubt.URLSearchParams.append()Fügt ein angegebenes Schlüssel/Wert-Paar als neuen Suchparameter hinzu.
URLSearchParams.delete()Löscht Suchparameter, die mit einem Namen und optional einem Wert übereinstimmen, aus der Liste aller Suchparameter.
URLSearchParams.entries()Gibt einen
Iteratorzurück, der die Iteration durch alle in diesem Objekt enthaltenen Schlüssel/Wert-Paare in der gleichen Reihenfolge wie in der Abfragezeichenfolge erlaubt.URLSearchParams.forEach()Ermöglicht die Iteration durch alle in diesem Objekt enthaltenen Werte über eine Callback-Funktion.
URLSearchParams.get()Gibt den ersten Wert zurück, der mit dem angegebenen Suchparameter verknüpft ist.
URLSearchParams.getAll()Gibt alle Werte zurück, die mit einem gegebenen Suchparameter verknüpft sind.
URLSearchParams.has()Gibt einen booleschen Wert zurück, der angibt, ob ein bestimmter Parameter oder ein Parameter-Wert-Paar existiert.
URLSearchParams.keys()Gibt einen
Iteratorzurück, der die Iteration durch alle Schlüssel der in diesem Objekt enthaltenen Schlüssel/Wert-Paare erlaubt.URLSearchParams.set()Setzt den Wert, der mit einem gegebenen Suchparameter verknüpft ist, auf den angegebenen Wert. Wenn es mehrere Werte gibt, werden die anderen gelöscht.
URLSearchParams.sort()Sortiert alle Schlüssel/Wert-Paare (falls vorhanden) nach ihren Schlüsseln.
URLSearchParams.toString()Gibt eine Zeichenfolge zurück, die eine zum Gebrauch in einer URL geeignete Abfragezeichenfolge enthält.
URLSearchParams.values()Gibt einen
Iteratorzurück, der die Iteration durch alle Werte der in diesem Objekt enthaltenen Schlüssel/Wert-Paare erlaubt.
Beispiele
Verwendung von URLSearchParams
const paramsString = "q=URLUtils.searchParams&topic=api";const searchParams = new URLSearchParams(paramsString);// Iterating the search parametersfor (const p of searchParams) { console.log(p);}console.log(searchParams.has("topic")); // trueconsole.log(searchParams.has("topic", "fish")); // falseconsole.log(searchParams.get("topic") === "api"); // trueconsole.log(searchParams.getAll("topic")); // ["api"]console.log(searchParams.get("foo") === null); // trueconsole.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")); // trueconsole.log(searchParams.get("foo")); // "bar"Parsen von window.location
Im Gegensatz zurURL bietet dasLocation-Interface keine sofort verfügbaresearchParams-Eigenschaft. Wir könnenlocation.search mitURLSearchParams parsen.
// Assume page has location:// https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams?foo=aconst paramsString = window.location.search;const searchParams = new URLSearchParams(paramsString);console.log(searchParams.get("foo")); // aDoppelte 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")); // trueconsole.log(searchParams.get("foo")); // bar, only returns the first valueconsole.log(searchParams.getAll("foo")); // ["bar", "baz"]Kein URL-Parsing
DerURLSearchParams-Konstruktor parstnicht vollständige URLs. Er entfernt jedoch ein initiales führendes? von einer Zeichenfolge, falls vorhanden.
const paramsString1 = "http://example.com/search?query=%40";const searchParams1 = new URLSearchParams(paramsString1);console.log(searchParams1.has("query")); // falseconsole.log(searchParams1.has("http://example.com/search?query")); // trueconsole.log(searchParams1.get("query")); // nullconsole.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")); // trueconst url = new URL("http://example.com/search?query=%40");const searchParams3 = new URLSearchParams(url.search);console.log(searchParams3.has("query")); // trueProzentkodierung
URLSearchParams-Objekteprozentkodieren alles in demapplication/x-www-form-urlencoded Prozent-Encoding-Set (das alle Zeichen außer ASCII-Alphanumerisch,*,-,., und_ enthält) und kodieren U+0020 SPACE als+. Es behandelt jedoch die Prozentcodierung nur beim Serialisieren und Deserialisieren der vollständigen URL-Suchparameter-Syntax. Beim Arbeiten mit einzelnen Schlüsseln und Werten verwenden Sie immer die nicht kodierte Version.
// Creation from parsing a string: percent-encoding is decodedconst params = new URLSearchParams("%24%25%26=%28%29%2B");// Retrieving all keys/values: only decoded values are returnedconsole.log([...params]); // [["$%&", "()+"]]// Getting an individual value: use the decoded key and get the decoded valueconsole.log(params.get("$%&")); // "()+"console.log(params.get("%24%25%26")); // null// Setting an individual value: use the unencoded key and valueparams.append("$%&$#@+", "$#&*@#()+");// Serializing: percent-encoding is appliedconsole.log(params.toString());// "%24%25%26=%28%29%2B&%24%25%26%24%23%40%2B=%24%23%26*%40%23%28%29%2B"Wenn Sie ein Schlüssel/Wert-Paar mit einem prozentkodierten Schlüssel anhängen, wird dieser Schlüssel als unkodiert behandelt und erneut kodiert.
const params = new URLSearchParams();params.append("%24%26", "value");params.toString(); // "%2524%2526=value"Pluszeichen beibehalten
DerURLSearchParams-Konstruktor interpretiert Pluszeichen (+) als Leerzeichen, was Probleme verursachen kann. Im folgenden Beispiel verwenden wirhexadezimale Escape-Sequenzen, um eine Zeichenfolge mit Binärdaten (bei der jedes Byte Informationen trägt) darzustellen, die in den URL-Suchparametern gespeichert werden muss. Beachten Sie, wie die vonbtoa() erzeugte kodierte Zeichenfolge+ enthält und vonURLSearchParams nicht beibehalten wird.
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 spacesconsole.log(atob(binQuery) === rawData); // falseErstellen Sie niemalsURLSearchParams-Objekte mit dynamisch interpolierten Zeichenfolgen. Verwenden Sie stattdessen dieappend()-Methode, die, wie oben erwähnt, alle Zeichen unverändert interpretiert.
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); // trueInteraktion mit URL.searchParams
DieURL.searchParams-Eigenschaft stellt diesearch-Zeichenfolge der URL alsURLSearchParams-Objekt dar. Wenn Sie dieseURLSearchParams aktualisieren, wird diesearch der URL mit ihrer Serialisierung aktualisiert.URL.search kodiert jedoch eine Teilmenge von Zeichen, dieURLSearchParams tut, und kodiert Leerzeichen als%20 statt+. Dies kann zu überraschenden Interaktionen führen – wenn SiesearchParams aktualisieren, auch mit denselben Werten, kann die URL unterschiedlich serialisiert werden.
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 searchParamsurl.searchParams.sort();console.log(url.href); // "https://example.com/?a=b+%7E"const url2 = new URL("https://example.com?search=1234¶m=my%20param");console.log(url2.search); // "?search=1234¶m=my%20param"url2.searchParams.delete("search");console.log(url2.search); // "?param=my+param"Leerwert vs. kein Wert
URLSearchParams unterscheidet nicht zwischen einem Parameter ohne etwas nach dem= und einem Parameter, der überhaupt kein= hat.
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'Spezifikationen
| Specification |
|---|
| URL # urlsearchparams |