HTMLAreaElement.search — Eigenschaft · JavaScript-Referenz

Signatur

HTMLAreaElement.search

Beschreibung

Die Eigenschaft search des HTMLAreaElement-Interfaces gibt den Suchteil (Query-String) der im href-Attribut hinterlegten URL zurück. Der Wert beginnt mit einem ?, danach folgen die Parameter, z. B. ?id=42&lang=de. Hat die URL keinen Query-String oder nur ein einzelnes ?, ist der Wert ein leerer String.

Die Eigenschaft lässt sich auch beschreiben: Beim Setzen wird das href-Attribut sofort angepasst. Ein führendes ? ist optional – es wird automatisch ergänzt. Sonderzeichen werden dabei nach den Regeln des URL-Standards prozentkodiert. Fragment (#hash) und Pfad bleiben unverändert.

Praktisch ist search etwa bei Imagemaps, deren Bereiche auf dieselbe Seite mit unterschiedlichen Parametern verlinken – z. B. um Tracking-Parameter anzuhängen oder Parameter auszulesen. Für strukturiertes Arbeiten mit einzelnen Parametern kombiniert man den Wert am besten mit URLSearchParams.

Rückgabewert

Typ

string

Beschreibung

Der Query-String der URL inklusive führendem ?, oder "", wenn kein (bzw. ein leerer) Query-String vorhanden ist.

Beispiele

Query-String eines Bereichs auslesen

// <map name="karte"><area id="nord" shape="rect" coords="0,0,100,50" href="https://example.com/region?name=nord&zoom=3#info" alt="Nord"></map>
const area = document.getElementById('nord');
console.log(area.search);

?name=nord&zoom=3

Einzelne Parameter mit URLSearchParams auswerten

const area = document.getElementById('nord');
const params = new URLSearchParams(area.search);
console.log(params.get('name'));
console.log(Number(params.get('zoom')) + 1);

nord 4

Tracking-Parameter an alle Bereiche einer Imagemap anhängen

const areas = document.querySelectorAll('map[name="karte"] area[href]');

areas.forEach((area) => {
  const params = new URLSearchParams(area.search);
  params.set('utm_source', 'imagemap');
  // Das führende "?" wird automatisch ergänzt
  area.search = params.toString();
});

console.log(areas[0].href);

https://example.com/region?name=nord&zoom=3&utm_source=imagemap#info

Query-String entfernen

const area = document.getElementById('nord');
area.search = '';
console.log(area.href);

https://example.com/region#info

// Wichtig · Fallstricke

Wenn href fehlt oder keine gültige URL ergibt, liefert search einen leeren String. Das Setzen hat dann keine Wirkung.
Relative href-Werte werden gegen die Basis-URL des Dokuments (document.baseURI) aufgelöst. Nach dem Setzen steht im Attribut unter Umständen eine absolute URL.
Der Rückgabewert ist prozentkodiert. Zum Lesen einzelner Werte lieber URLSearchParams statt eigener String-Zerlegung verwenden – die Klasse dekodiert automatisch (auch + als Leerzeichen).
Ein ? ohne weitere Zeichen ergibt beim Lesen \"\". Man kann also nicht unterscheiden, ob gar kein oder ein leerer Query-String vorhanden ist.
Werte, die aus Benutzereingaben stammen, immer über URLSearchParams kodieren, damit keine Parameter eingeschleust werden können.
Wird von allen modernen Browsern unterstützt; gleiches Verhalten wie HTMLAnchorElement.search und URL.search.

Siehe auch

URL.search HTMLAreaElement.hash HTMLAreaElement.shape HTMLAreaElement.alt HTMLAreaElement.coords