URLSearchParams.sort() — Methode · JavaScript-Referenz

Signatur

URLSearchParams.prototype.sort()

Beschreibung

sort() ordnet die Paare eines URLSearchParams-Objekts nach ihren Schlüsseln neu. Das Objekt wird dabei direkt verändert, es entsteht keine Kopie. Verglichen wird nach UTF-16-Codeeinheiten, also nicht nach Sprachregeln wie bei localeCompare(). Großbuchstaben stehen deshalb vor Kleinbuchstaben, und Umlaute kommen nach dem ASCII-Bereich.

Die Sortierung ist stabil: Paare mit gleichem Schlüssel behalten ihre bisherige Reihenfolge. Die Werte selbst werden nicht sortiert. Bei tag=b&tag=a bleibt es daher bei b vor a. Das ist wichtig, weil die Reihenfolge wiederholter Parameter für viele Server eine Bedeutung hat.

Nützlich ist die Methode vor allem, um URLs zu normalisieren. Zwei URLs, deren Parameter nur anders angeordnet sind, ergeben nach dem Sortieren dieselbe Zeichenkette. Das hilft bei Cache-Schlüsseln, beim Entfernen doppelter Einträge, bei kanonischen URLs, bei Signaturen (z. B. HMAC über Abfrageparameter) und bei stabilen Tests. Stammt das Objekt aus url.searchParams, wird url.search bzw. url.href automatisch mit angepasst.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Das Objekt wird direkt verändert. Deshalb ist eine Verkettung wie params.sort().toString() nicht möglich.

Beispiele

Einfaches Sortieren mit doppelten Schlüsseln

const params = new URLSearchParams("c=4&a=2&b=3&a=1");
params.sort();

// Gleiche Schlüssel behalten ihre Reihenfolge (stabil)
console.log(params.toString());

a=2&a=1&b=3&c=4

URLs für einen Cache-Schlüssel normalisieren

const normalizeUrl = (href) => {
  const url = new URL(href);
  url.searchParams.sort(); // passt url.href automatisch an
  return url.href;
};

const cache = new Map();
const a = normalizeUrl("https://api.example.com/items?page=2&limit=10");
const b = normalizeUrl("https://api.example.com/items?limit=10&page=2");

cache.set(a, { cached: true });
console.log(a);
console.log(a === b, cache.has(b));

https://api.example.com/items?limit=10&page=2 true true

Sortierung nach UTF-16-Codeeinheiten

const params = new URLSearchParams("b=1&B=2&a=3&ä=4&_=5");
params.sort();

// Großbuchstaben < '_' < Kleinbuchstaben < Umlaute
console.log([...params.keys()]);
console.log(params.toString());

[ 'B', '_', 'a', 'b', 'ä' ] B=2&_=5&a=3&b=1&%C3%A4=4

Sortierte Parameter für eine Anfrage-Signatur

const signRequest = async (params, secret) => {
  const sorted = new URLSearchParams(params); // Kopie, Original bleibt unverändert
  sorted.sort();
  const enc = new TextEncoder();
  const key = await crypto.subtle.importKey(
    "raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]
  );
  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(sorted.toString()));
  return [...new Uint8Array(sig)].map((x) => x.toString(16).padStart(2, "0")).join("");
};

const s1 = await signRequest({ user: "42", action: "read" }, "geheim");
const s2 = await signRequest({ action: "read", user: "42" }, "geheim");
console.log(s1 === s2);

true

// Wichtig · Fallstricke

Kein Rückgabewert: sort() gibt undefined zurück. const s = params.sort() liefert also keine sortierten Parameter.
Ändert das Original: Das Objekt wird direkt verändert, bei url.searchParams also auch die zugehörige URL. Wer das Original behalten will, legt vorher mit new URLSearchParams(params) eine Kopie an.
Nur Schlüssel werden sortiert: Werte mit gleichem Schlüssel bleiben in ihrer ursprünglichen Reihenfolge. Das ist Absicht, weil die Reihenfolge wiederholter Parameter oft eine Bedeutung hat.
Keine sprachabhängige Sortierung: Verglichen wird nach UTF-16-Codeeinheiten, also "Z" vor "a" und "ä" nach "z". Für eine eigene Reihenfolge erzeugt man ein neues Objekt: new URLSearchParams([...params].sort(([a], [b]) => a.localeCompare(b))).
Kodierung: toString() kodiert Leerzeichen als + und Nicht-ASCII-Zeichen prozentkodiert. Für Signaturen müssen Client und Server genau dieselbe Kodierung verwenden.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt, nicht aber vom Internet Explorer. In Node.js ist die Methode ab Version 7.7 verfügbar und global ab Version 10.

Siehe auch

URLSearchParams URLSearchParams.toString() URLSearchParams.append() URLSearchParams.keys() URL.searchParams Array.prototype.sort() TrustedScript.toJSON()