URL.href — Eigenschaft · JavaScript-Referenz

Signatur

URL.href

Beschreibung

Die Eigenschaft href eines URL-Objekts enthält die gesamte URL: Protokoll, Zugangsdaten, Host, Port, Pfad, Suchparameter und Fragment. Beim Lesen bekommt man die normalisierte Form zurück, etwa kleingeschriebene Schemata und Hostnamen, aufgelöste ./- und ../-Segmente und prozentkodierte Sonderzeichen. Der Wert ist identisch mit dem Ergebnis von url.toString() und url.toJSON().

Man kann href auch beschreiben. Dann wird der neue String vollständig neu geparst, und alle anderen Eigenschaften (protocol, host, pathname, search, hash …) sowie das zugehörige searchParams-Objekt werden sofort angepasst. Das bietet sich an, wenn man ein bestehendes URL-Objekt mit einer ganz neuen Adresse weiterverwenden will.

In der Praxis braucht man href vor allem, nachdem man eine URL über die Einzeleigenschaften oder über searchParams aufgebaut hat. Das Ergebnis gibt man dann als String an fetch(), location.assign(), ein <a>-Element oder eine Logging-Funktion weiter.

Parameter

Name	Typ	Default	Beschreibung
$value	string		Nur beim Setzen: eine neue absolute URL. Sie wird neu geparst und ersetzt alle Bestandteile. Relative URLs sind hier nicht erlaubt.

Rückgabewert

Typ

string

Beschreibung

Die vollständige, normalisierte URL als String (gleiches Ergebnis wie URL.prototype.toString()).

Beispiele

Normalisierte URL auslesen

const url = new URL('HTTPS://Example.COM:443/a/./b/../c?q=ä ö#Top');
console.log(url.href);

https://example.com/a/c?q=%C3%A4%20%C3%B6#Top

URL mit searchParams aufbauen und an fetch übergeben

const api = new URL('https://api.example.com/v1/search');
api.searchParams.set('term', 'Kaffee & Kuchen');
api.searchParams.set('limit', '10');

console.log(api.href);
// const res = await fetch(api.href);

https://api.example.com/v1/search?term=Kaffee+%26+Kuchen&limit=10

href setzen – alle Teile werden neu berechnet

const url = new URL('https://alt.example.org/pfad?x=1');
url.href = 'http://neu.example.net:8080/start#info';

console.log(url.protocol, url.host, url.pathname, url.search, url.hash);
console.log(url.searchParams.has('x'));

http: neu.example.net:8080 /start #info false

Ungültige Zuweisung abfangen

const url = new URL('https://example.com/');
try {
  url.href = '/nur-relativ';
} catch (err) {
  console.log(err.name);
}
console.log(url.href);

TypeError https://example.com/

// Wichtig · Fallstricke

Wenn man href einen ungültigen oder relativen String zuweist, wird ein TypeError geworfen. Das Objekt bleibt dabei unverändert. Deshalb Zuweisungen mit Benutzereingaben in try/catch kapseln oder vorher mit URL.canParse() prüfen.
Der gelesene Wert ist normalisiert und kann vom Eingabe-String abweichen, z. B. bei Groß-/Kleinschreibung, Standard-Ports wie :443, die entfernt werden, oder bei der Prozentkodierung. Beim String-Vergleich von URLs immer href beider Seiten vergleichen, nicht den Rohstring.
Die Suchparameter werden unterschiedlich kodiert: Über searchParams wird ein Leerzeichen zu +, über search oder den Konstruktor zu %20.
href enthält auch Zugangsdaten (user:pass@). Vorsicht beim Loggen oder Anzeigen.
Sicherheit: href eines URL-Objekts prüft nicht, ob das Schema harmlos ist. Vor dem Einsetzen in a.href oder location url.protocol auf erlaubte Werte wie https: prüfen, damit keine javascript:-URLs durchrutschen (XSS).
Nicht zu verwechseln mit location.href oder HTMLAnchorElement.href: Eine Zuweisung an location.href löst eine Navigation aus, eine Zuweisung an URL.href nicht.

Siehe auch

URL URL.prototype.toString() URL.searchParams URL.origin URL.canParse() Location.href SyncEvent.tag