URL.username — Eigenschaft · JavaScript-Referenz

Signatur

URL.prototype.username

Beschreibung

Die Eigenschaft username eines URL-Objekts enthält den Benutzernamen aus dem Userinfo-Teil einer URL. Das ist der Abschnitt zwischen :// und dem ersten : oder @, z. B. max in ftp://max:geheim@example.com/. Gibt es keinen Benutzernamen, ist der Wert ein leerer String "", niemals null.

Man kann die Eigenschaft lesen und schreiben. Beim Setzen werden Sonderzeichen automatisch prozentkodiert, und zwar nach dem sogenannten „userinfo percent-encode set“. Zum Beispiel wird @ zu %40, : zu %3A und ein Leerzeichen zu %20. Beim Lesen bekommt man den kodierten Wert zurück. Den Klartext erhält man mit decodeURIComponent(). Jede Änderung wirkt sich sofort auf href, toString() und toJSON() aus.

Typische Einsatzfälle:

Zugangsdaten aus Verbindungs-URLs auslesen, z. B. bei Datenbank-URLs wie postgres://user:pw@host/db in Node.js.
URLs vor dem Protokollieren oder Anzeigen von Zugangsdaten bereinigen.
Benutzernamen mit Sonderzeichen sicher in eine URL einsetzen, ohne selbst kodieren zu müssen.

Hat eine URL keinen Host (z. B. mailto:) oder verwendet sie das Schema file:, kann sie keinen Benutzernamen enthalten. In diesem Fall wird eine Zuweisung stillschweigend ignoriert, es gibt keinen Fehler.

Parameter

Name	Typ	Default	Beschreibung
$wert (beim Setzen)	string		Neuer Benutzername. Andere Werte werden in einen String umgewandelt. Sonderzeichen werden automatisch prozentkodiert. `""` entfernt den Benutzernamen.

Rückgabewert

Typ

string

Beschreibung

Der prozentkodierte Benutzername der URL. Gibt es keinen, ist der Wert "".

Beispiele

Benutzernamen aus einer Datenbank-URL auslesen

const dbUrl = new URL('postgres://app_user:s3cr3t@db.example.com:5432/shop');

console.log(dbUrl.username);
console.log(dbUrl.password);
console.log(dbUrl.hostname);

// Ohne Zugangsdaten ergibt sich ein leerer String
console.log(new URL('https://example.com/').username === '');

app_user s3cr3t db.example.com true

Benutzernamen mit Sonderzeichen setzen (automatische Kodierung)

const url = new URL('https://example.com/api');
url.username = 'max muster@firma';

console.log(url.username);
console.log(url.href);

// Klartext zurückgewinnen
console.log(decodeURIComponent(url.username));

max%20muster%40firma https://max%20muster%40firma@example.com/api max muster@firma

Zugangsdaten vor dem Protokollieren entfernen

const redactUrl = (input) => {
  const url = new URL(input);
  if (url.username || url.password) {
    url.username = '';
    url.password = '';
  }
  return url.href;
};

console.log(redactUrl('https://admin:topsecret@intern.example.com/status'));

https://intern.example.com/status

Zuweisung wird bei URLs ohne Host ignoriert

const mail = new URL('mailto:info@example.com');
mail.username = 'max';
console.log(mail.username, mail.href);

const file = new URL('file:///home/max/doc.txt');
file.username = 'max';
console.log(JSON.stringify(file.username));

mailto:info@example.com ""

// Wichtig · Fallstricke

Kodierter Wert: username liefert den prozentkodierten Wert. Wenn Sie ihn vergleichen oder anzeigen wollen, dekodieren Sie ihn vorher mit decodeURIComponent().
Stilles Ignorieren: Bei URLs ohne Host (z. B. mailto:, data:) und bei file:-URLs hat eine Zuweisung keine Wirkung. Es wird auch kein Fehler geworfen.
Sicherheit: Zugangsdaten in URLs gelten als veraltet und riskant. Sie landen in Logs, im Verlauf und im Referer. fetch() bzw. new Request() werfen einen TypeError, wenn die URL Zugangsdaten enthält. Übergeben Sie diese stattdessen im Authorization-Header. Browser zeigen bei solchen URLs teilweise Warnungen an oder entfernen die Zugangsdaten. Außerdem nutzen Phishing-Seiten Adressen wie https://bank.de@boese.example/, um Nutzer zu täuschen.
Wird username geleert, während noch ein Passwort gesetzt ist, entsteht eine URL der Form https://:pw@host/.
Kompatibilität: Die Eigenschaft wird in allen modernen Browsern, in Web Workern und in Node.js unterstützt (global ab Version 10, über das Modul url ab Version 7).

Siehe auch

URL.password URL.href URL.host URL.origin URL FileSystem.name