HTMLInputElement.dirName — Eigenschaft · JavaScript-Referenz

Signatur

HTMLInputElement.dirName

Beschreibung

Die Eigenschaft dirName spiegelt das HTML-Attribut dirname eines <input>-Elements wider. Sie enthält den Namen eines zusätzlichen Formularfelds. Unter diesem Namen überträgt der Browser beim Absenden die Schreibrichtung des eingegebenen Texts, also ltr (links nach rechts) oder rtl (rechts nach links).

Das ist vor allem bei mehrsprachigen Anwendungen nützlich. Schreibt ein Nutzer zum Beispiel in einem Kommentarfeld mit dir="auto" auf Arabisch oder Hebräisch, erkennt der Browser die Richtung automatisch. Der Server erfährt sie über das Zusatzfeld und kann den Text später mit der richtigen Richtung anzeigen, ohne sie selbst erraten zu müssen.

Ein Beispiel: <input name="kommentar" dirname="kommentar.dir"> sendet beim Absenden etwa kommentar=Hallo&kommentar.dir=ltr. Die Richtung ergibt sich aus dem dir-Attribut des Elements. Bei dir="auto" bestimmt der Browser sie aus dem ersten stark gerichteten Zeichen des Werts. Fehlt ein dir-Attribut, wird die Richtung vom Elternelement übernommen.

Die Eigenschaft ist ein einfacher String. Ist kein Attribut gesetzt, liefert sie einen leeren String. Wirksam ist sie bei textartigen Eingabetypen wie text, search, tel, url und email. Laut aktueller Spezifikation gilt sie außerdem für hidden, submit und reset. Für <textarea> gibt es mit HTMLTextAreaElement.dirName ein entsprechendes Gegenstück.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: der Name des Formularfelds, unter dem die Schreibrichtung übertragen wird. Beim Setzen wird das Attribut `dirname` aktualisiert.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des Attributs dirname, oder ein leerer String, wenn keines gesetzt ist.

Beispiele

dirName per JavaScript setzen und auslesen

// HTML: <input id="kommentar" name="kommentar" dir="auto">
const input = document.querySelector('#kommentar');

console.log(input.dirName); // noch kein Attribut gesetzt

input.dirName = 'kommentar.dir';
console.log(input.dirName);
console.log(input.getAttribute('dirname'));

"" kommentar.dir kommentar.dir

Schreibrichtung über FormData prüfen

// HTML:
// <form id="f">
//   <input name="nachricht" dir="auto" dirname="nachricht.dir">
// </form>
const form = document.querySelector('#f');
const feld = form.elements.nachricht;

feld.value = 'שלום עולם'; // hebräischer Text

const daten = new FormData(form);
for (const [key, value] of daten) {
  console.log(`${key} = ${value}`);
}

nachricht = שלום עולם nachricht.dir = rtl

Mehrsprachiges Formular per fetch absenden

const form = document.querySelector('#kommentar-form');

// Allen Textfeldern automatisch ein dirname-Feld geben
for (const el of form.querySelectorAll('input[type="text"][name]')) {
  el.dir = 'auto';
  el.dirName = `${el.name}.dir`;
}

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const body = new URLSearchParams(new FormData(form));
  console.log(body.toString());
  await fetch('/api/kommentare', { method: 'POST', body });
});

titel=Hello&titel.dir=ltr

// Wichtig · Fallstricke

Browserunterstützung: Firefox unterstützt dirname erst ab Version 116 (2023). Ältere Firefox-Versionen senden das Zusatzfeld nicht. Der Server sollte deshalb einen sinnvollen Standardwert verwenden, wenn das Feld fehlt.
Das Zusatzfeld wird nur gesendet, wenn das Element auch einen name hat und nicht disabled ist.
Ohne dir="auto" wird nicht der Inhalt ausgewertet. Stattdessen gilt die festgelegte oder geerbte Richtung, meist also ltr.
Der Wert ist frei wählbar. Kollidiert er mit dem name eines anderen Felds, entstehen doppelte Einträge im Formular. Übliche Konvention ist name.dir.
Die Richtung kommt vom Client und lässt sich manipulieren. Der Server sollte sie gegen die erlaubten Werte ltr und rtl prüfen, bevor er sie zum Beispiel ungeprüft als dir-Attribut in HTML ausgibt (XSS-Gefahr).

Siehe auch

HTMLTextAreaElement.dirName HTMLElement.dir HTMLInputElement.name FormData HTMLInputElement AnimationPlaybackEvent.timelineTime HTMLInputElement.capture