URLSearchParams.toString() — Methode · JavaScript-Referenz

Signatur

URLSearchParams.prototype.toString()

Beschreibung

Die Methode toString() wandelt alle Schlüssel-Wert-Paare eines URLSearchParams-Objekts in eine Abfragezeichenfolge um, etwa q=suche&page=2. Die Paare stehen in der Reihenfolge, in der sie eingefügt wurden. Doppelte Schlüssel, zum Beispiel aus mehreren append()-Aufrufen, erscheinen alle einzeln.

Kodiert wird nach dem Format application/x-www-form-urlencoded. Leerzeichen werden zu +. Unverändert bleiben nur ASCII-Buchstaben, Ziffern und die Zeichen *, -, . und _. Alle anderen Zeichen werden UTF-8-prozentkodiert, zum Beispiel ä → %C3%A4 und ~ → %7E. Das Ergebnis weicht deshalb von encodeURIComponent() ab.

Die Methode wird auch automatisch aufgerufen, wenn das Objekt in einen String umgewandelt wird, etwa in Template-Literalen (`${params}`) oder bei der Verkettung mit +. Typische Einsätze sind GET-URLs für fetch(), Links oder die Adressleiste über die History-API. Außerdem kann man das Objekt direkt als Body eines POST-Requests mit Formular-Kodierung verwenden.

Rückgabewert

Typ

string

Beschreibung

Die kodierte Abfragezeichenfolge ohne führendes ?. Hat das Objekt keine Parameter, ist das Ergebnis ein leerer String "".

Beispiele

Einfache Abfragezeichenfolge erzeugen

const params = new URLSearchParams({ q: 'JavaScript Tutorial', page: 2 });
params.append('sort', 'neu');

console.log(params.toString());

q=JavaScript+Tutorial&page=2&sort=neu

Such-URL für fetch() zusammenbauen

const suche = async (begriff, tags) => {
  const params = new URLSearchParams({ q: begriff });
  // Mehrfachwerte: jeder Tag als eigener Parameter
  tags.forEach((tag) => params.append('tag', tag));

  // Das Template-Literal ruft toString() automatisch auf
  const url = `https://api.example.com/search?${params}`;
  console.log(url);
  const response = await fetch(url);
  return response.json();
};

suche('Größe & Form', ['js', 'web']);

https://api.example.com/search?q=Gr%C3%B6%C3%9Fe+%26+Form&tag=js&tag=web

Unterschied zu encodeURIComponent()

const wert = 'a b~c!';

console.log(new URLSearchParams({ x: wert }).toString());
console.log('x=' + encodeURIComponent(wert));

x=a+b%7Ec%21 x=a%20b~c!

Filter in der Adressleiste speichern, ohne neu zu laden

const params = new URLSearchParams(location.search);
params.set('filter', 'aktiv');
params.delete('page');

const query = params.toString();
// Kein '?' anhängen, wenn keine Parameter übrig sind
const neueUrl = query ? `${location.pathname}?${query}` : location.pathname;
history.replaceState(null, '', neueUrl);

// Wichtig · Fallstricke

Kein führendes ?: toString() liefert nur die Abfragezeichenfolge. Das ? muss man selbst voranstellen. URL.prototype.search enthält es dagegen.
Leerzeichen werden zu +, nicht zu %20. Die meisten Server kommen damit zurecht. Manche APIs, etwa bei Signaturen wie OAuth 1.0, verlangen aber %20. Dann das Ergebnis nachbearbeiten (.replace(/\+/g, '%20')) oder encodeURIComponent() verwenden.
Normalisierung: Eine eingelesene Zeichenfolge kommt nicht unbedingt unverändert zurück. So ergibt new URLSearchParams('a=%20&b=~').toString() den String \"a=+&b=%7E\". Beim Vergleichen oder Signieren von URLs deshalb vorsichtig sein.
Werte werden in Strings umgewandelt: null wird zu \"null\", undefined zu \"undefined\", und Objekte werden zu \"[object Object]\". Solche Werte vorher herausfiltern.
Die Reihenfolge der Paare bleibt erhalten. Für stabile Cache-Schlüssel vorher params.sort() aufrufen.
Kompatibilität: Alle modernen Browser unterstützen die Methode. Der Internet Explorer kennt URLSearchParams nicht, dort ist ein Polyfill nötig. In Node.js ist die Klasse seit Version 10 global verfügbar.

Siehe auch

URLSearchParams URLSearchParams.append() URLSearchParams.set() URLSearchParams.sort() URL.searchParams URL.search encodeURIComponent()