URLSearchParams.get() — Methode · JavaScript-Referenz

Signatur

URLSearchParams.prototype.get(name)

Beschreibung

Die Methode get() liest den Wert eines einzelnen Query-Parameters aus einem URLSearchParams-Objekt aus. Damit lassen sich Werte wie ?seite=2&sort=preis bequem auswerten, ohne den Query-String von Hand zu zerlegen oder zu dekodieren.

Kommt ein Parameter mehrfach vor (z. B. ?tag=js&tag=css), liefert get() nur den ersten Wert. Alle Werte bekommt man mit getAll(). Fehlt der Parameter ganz, ist der Rückgabewert null. Ist er zwar vorhanden, hat aber keinen Wert (?debug oder ?debug=), kommt ein leerer String "" zurück.

Der Rückgabewert ist immer ein String und bereits prozent-dekodiert. Das Zeichen + wird dabei als Leerzeichen gelesen. Zahlen oder Wahrheitswerte muss man also selbst umwandeln, etwa mit Number(). Bei Parameternamen wird zwischen Groß- und Kleinschreibung unterschieden.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des gesuchten Parameters. Groß- und Kleinschreibung wird unterschieden. Werte, die keine Strings sind, werden in einen String umgewandelt.

Rückgabewert

Typ

string | null

Beschreibung

Der erste Wert des Parameters als dekodierter String, "" bei einem Parameter ohne Wert oder null, wenn der Parameter nicht vorhanden ist.

Beispiele

Parameter aus der aktuellen Seiten-URL lesen

// Angenommen: https://shop.example/produkte?kategorie=buecher&seite=3
const params = new URLSearchParams(window.location.search);

const kategorie = params.get('kategorie');
const seite = Number(params.get('seite') ?? 1);
const sortierung = params.get('sort'); // nicht vorhanden

console.log(kategorie, seite, sortierung);

buecher 3 null

Mehrfache, leere und kodierte Werte

const params = new URLSearchParams('tag=js&tag=css&debug&q=Hallo+Welt%21');

console.log(params.get('tag'));     // nur der erste Wert
console.log(params.getAll('tag'));  // alle Werte
console.log(params.get('debug'));   // vorhanden, aber leer
console.log(params.get('q'));       // dekodiert, + wird Leerzeichen
console.log(params.get('Tag'));     // Groß-/Kleinschreibung zählt

js ['js', 'css'] "" Hallo Welt! null

Query-Parameter in einem Node.js-HTTP-Server auswerten

import http from 'node:http';

const server = http.createServer((req, res) => {
  const url = new URL(req.url, `http://${req.headers.host}`);
  const limit = Math.min(Number(url.searchParams.get('limit')) || 10, 100);
  const suche = url.searchParams.get('q')?.trim() ?? '';

  res.setHeader('Content-Type', 'application/json');
  res.end(JSON.stringify({ suche, limit }));
});

server.listen(3000);
// GET /api?q=%20lampe%20&limit=500

{"suche":"lampe","limit":100}

Feature-Flag per URL prüfen

const params = new URLSearchParams('?debug=&theme=dark');

// Falsch: "" ist falsy, obwohl der Parameter gesetzt ist
const debugFalsch = Boolean(params.get('debug'));
// Richtig: auf null prüfen oder has() verwenden
const debug = params.get('debug') !== null;

console.log(debugFalsch, debug, params.has('debug'));

false true true

// Wichtig · Fallstricke

"" oder null: Ein Parameter ohne Wert liefert "", und dieser Wert ist falsy. Ob ein Parameter vorhanden ist, prüft man mit !== null oder has(), nicht mit einem reinen Wahrheitstest.
Immer String: get('seite') gibt "3" zurück, nicht 3. Umwandeln und auf NaN prüfen nicht vergessen.
Nur der erste Wert: Für Mehrfachauswahl, etwa ?farbe=rot&farbe=blau, getAll() verwenden.
Plus-Zeichen: + im Query-String wird als Leerzeichen gelesen. Ein echtes Plus muss als %2B kodiert sein, sonst wird z. B. aus der Telefonnummer +49 der Wert " 49".
Führendes ?: Der Konstruktor entfernt ein einzelnes führendes ?. Eine komplette URL als String wird dagegen nicht zerlegt. In diesem Fall new URL(...).searchParams verwenden.
Sicherheit: URL-Parameter werden vom Nutzer gesteuert. Werte nie ungeprüft über innerHTML ausgeben (Gefahr durch XSS) und nie ungeprüft für Weiterleitungen nutzen (offene Weiterleitung).
Kompatibilität: Wird von allen modernen Browsern, Deno und Node.js (global ab Version 10) unterstützt. Der Internet Explorer braucht einen Polyfill.

Siehe auch

URLSearchParams URLSearchParams.getAll() URLSearchParams.has() URLSearchParams.set() URLSearchParams.append() URL.searchParams new SpeechGrammarList()