TextEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface TextEvent extends UIEvent

Beschreibung

TextEvent ist eine veraltete Schnittstelle aus einem frühen Entwurf von DOM Level 3 Events. Sie erbt von UIEvent und beschreibt Ereignisse, bei denen Text in ein bearbeitbares Element eingefügt wird – durch Tastatur, IME, Einfügen aus der Zwischenablage, Drag & Drop oder Spracheingabe. In der Praxis tritt sie fast nur als Event-Objekt des Events textInput auf.

Die wichtigste Eigenschaft ist data (schreibgeschützt, string). Sie enthält den Text, der gerade eingefügt werden soll. Weil textInput vor der Änderung am DOM ausgelöst wird und abbrechbar ist, kann man die Eingabe mit preventDefault() verhindern. Früher war das der übliche Weg, Eingaben zu filtern, bevor es beforeinput gab.

Einen Konstruktor gibt es nicht. Instanzen erzeugt man nur über document.createEvent("TextEvent") und die veraltete Methode initTextEvent(). Für neuen Code nutzt man stattdessen InputEvent mit den Events beforeinput und input. Sie sind standardisiert, laufen in allen Browsern und liefern über inputType und data mehr Informationen.

Parameter

Name	Typ	Default	Beschreibung
$data	string		Eigenschaft (schreibgeschützt): der Text, der eingefügt wird, z. B. ein Zeichen, ein IME-Ergebnis oder der Inhalt aus der Zwischenablage.
$initTextEvent(type, bubbles, cancelable, view, data)	function		Methode (veraltet): initialisiert ein Objekt, das mit `document.createEvent("TextEvent")` erzeugt wurde. `type`: `string`, `bubbles`/`cancelable`: `boolean`, `view`: `Window \| null`, `data`: `string`.

Rückgabewert

Typ

TextEvent

Beschreibung

Das Event-Objekt, das Handler von textInput erhalten. Es enthält die geerbten UIEvent-Eigenschaften und data.

Beispiele

textInput abfangen und nur Ziffern zulassen (Altcode)

const feld = document.querySelector('#plz');

const nurZiffern = (event) => {
  // event ist ein TextEvent
  console.log('Eingabe:', event.data);
  if (!/^\d+$/.test(event.data)) {
    event.preventDefault(); // Eingabe wird verworfen
  }
};

feld.addEventListener('textInput', nurZiffern);

// Später wieder entfernen
// feld.removeEventListener('textInput', nurZiffern);

Eingabe: 4 Eingabe: a (wird verhindert)

TextEvent über createEvent erzeugen und auslösen

const feld = document.querySelector('#notiz');

feld.addEventListener('textInput', (e) => {
  console.log(e instanceof TextEvent, e.type, e.data);
});

if ('TextEvent' in window) {
  const ev = document.createEvent('TextEvent');
  ev.initTextEvent('textInput', true, true, window, 'Hallo');
  feld.dispatchEvent(ev);
} else {
  console.log('TextEvent wird nicht unterstützt');
}

true textInput Hallo

Moderner Ersatz: beforeinput mit InputEvent

const feld = document.querySelector('#plz');

feld.addEventListener('beforeinput', (event) => {
  // event ist ein InputEvent
  if (event.inputType.startsWith('insert') && event.data && !/^\d+$/.test(event.data)) {
    event.preventDefault();
  }
  console.log(event.inputType, event.data);
});

insertText 4 insertFromPaste 12345

// Wichtig · Fallstricke

Veraltet: TextEvent ist nicht Teil der aktuellen UI-Events-Spezifikation. Die Browser behalten es nur aus Kompatibilitätsgründen. In neuem Code besser beforeinput/input (InputEvent) verwenden.
Kompatibilität: Chromium-Browser und Safari lösen textInput seit Langem aus. Firefox unterstützt es erst seit Version 126. Ältere Firefox-Versionen kennen weder das Event noch die Schnittstelle, deshalb die Unterstützung prüfen, z. B. mit 'TextEvent' in window.
Einen Konstruktor new TextEvent() gibt es nicht; der Aufruf wirft einen TypeError. Nur document.createEvent('TextEvent') funktioniert.
Es gibt keine Event-Handler-Eigenschaft wie ontextinput. Das Event lässt sich nur mit addEventListener('textInput', …) abonnieren. Achtung auf die Groß-/Kleinschreibung: textInput.
Löschungen (Backspace, Entf) lösen kein textInput aus, IME-Komposition verhält sich je nach Browser unterschiedlich. Zuverlässiger ist beforeinput mit inputType.
Eine Validierung per preventDefault() auf der Client-Seite ersetzt nie die Prüfung auf dem Server.

Siehe auch

TimeEvent BlobEvent DragEvent Element Event