new TextUpdateEvent() — Methode · JavaScript-Referenz

Signatur

new TextUpdateEvent(type, options)

Beschreibung

Der Konstruktor TextUpdateEvent() gehört zur EditContext API. Mit dieser API bauen Sie eigene Editoren, etwa auf Basis von <canvas> oder eigener DOM-Darstellung. Der Browser übernimmt dabei die komplette Texteingabe einschließlich IME (Eingabemethoden für Sprachen wie Japanisch oder Chinesisch). Ändert der Nutzer Text, feuert der Browser am EditContext ein textupdate-Ereignis vom Typ TextUpdateEvent.

Im normalen Betrieb erzeugt der Browser diese Ereignisse selbst. Den Konstruktor brauchen Sie vor allem für Unit-Tests, für Simulationen von Eingaben (z. B. bei Makros oder beim Wiedergeben einer Aufzeichnung) und für eigene Abstraktionsschichten. Dort sollen synthetische Ereignisse dieselbe Form haben wie echte.

Das Ereignis beschreibt, welcher Bereich (updateRangeStart bis updateRangeEnd) durch welchen Text (text) ersetzt wird. Außerdem enthält es die neue Auswahl bzw. Cursorposition (selectionStart, selectionEnd). Alle Positionen sind Offsets in UTF-16-Codeeinheiten im Text des EditContext.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Die EditContext API verwendet `"textupdate"`.
$options	Object	{}	Optionales Initialisierungsobjekt. Zusätzlich zu den `Event`-Optionen (`bubbles`, `cancelable`, `composed`) sind möglich: `updateRangeStart` (`number`, Standard `0`): Beginn des ersetzten Bereichs. `updateRangeEnd` (`number`, Standard `0`): Ende des ersetzten Bereichs (exklusiv). `text` (`string`, Standard `""`): eingefügter Text. `selectionStart` (`number`, Standard `0`): Anfang der Auswahl nach der Änderung. `selectionEnd` (`number`, Standard `0`): Ende der Auswahl nach der Änderung.

Rückgabewert

Typ

TextUpdateEvent

Beschreibung

Ein neues TextUpdateEvent-Objekt. Die Eigenschaften text, updateRangeStart, updateRangeEnd, selectionStart und selectionEnd sind schreibgeschützt.

Beispiele

Ereignis erzeugen und Eigenschaften auslesen

// Simuliert: Das Zeichen "a" wird an Position 5 eingefügt
const event = new TextUpdateEvent("textupdate", {
  updateRangeStart: 5,
  updateRangeEnd: 5,
  text: "a",
  selectionStart: 6,
  selectionEnd: 6,
});

console.log(event.type, event.text, event.updateRangeStart, event.selectionEnd);

textupdate a 5 6

textupdate-Handler per Unit-Test prüfen

const editContext = new EditContext({ text: "Hallo Welt" });

// Echte Handler-Logik: Modell anpassen
let model = editContext.text;
const onTextUpdate = (e) => {
  model = model.slice(0, e.updateRangeStart) + e.text + model.slice(e.updateRangeEnd);
  console.log(`Neuer Text: "${model}" | Cursor: ${e.selectionStart}`);
};
editContext.addEventListener("textupdate", onTextUpdate);

// Synthetische Eingabe: "Welt" (6–10) durch "Leute" ersetzen
editContext.dispatchEvent(new TextUpdateEvent("textupdate", {
  updateRangeStart: 6,
  updateRangeEnd: 10,
  text: "Leute",
  selectionStart: 11,
  selectionEnd: 11,
}));

Neuer Text: "Hallo Leute" | Cursor: 11

Funktionserkennung mit Rückfallebene

const supportsEditContext = "EditContext" in window && "TextUpdateEvent" in window;

if (supportsEditContext) {
  const editor = document.querySelector("#editor");
  editor.editContext = new EditContext();
  editor.editContext.addEventListener("textupdate", (e) => {
    editor.textContent = editor.editContext.text;
  });
} else {
  // Rückfall auf contenteditable
  document.querySelector("#editor").contentEditable = "true";
  console.log("EditContext nicht verfügbar – contenteditable wird genutzt");
}

// Wichtig · Fallstricke

Experimentelle API: TextUpdateEvent und EditContext gibt es derzeit nur in Chromium-basierten Browsern (Chrome/Edge ab Version 121). Firefox und Safari unterstützen sie nicht. Prüfen Sie die Unterstützung vorher, z. B. mit \"TextUpdateEvent\" in window.
Synthetische Ereignisse ändern keinen Zustand: Ein per dispatchEvent() ausgelöstes Ereignis ruft nur die Listener auf. Den Text im EditContext (editContext.text) ändert es nicht. Dafür brauchen Sie editContext.updateText() und editContext.updateSelection(). event.isTrusted ist bei solchen Ereignissen false.
Alle Offsets zählen UTF-16-Codeeinheiten, keine Zeichen. Emojis und andere Zeichen außerhalb der BMP belegen zwei Positionen.
Wird type weggelassen, wirft der Konstruktor einen TypeError. Ohne new aufgerufen, wirft er ebenfalls einen TypeError.
Während einer IME-Komposition kommen oft mehrere textupdate-Ereignisse hintereinander. Zusätzliche Ereignisse wie compositionstart, compositionend und textformatupdate berücksichtigen, damit die Darstellung korrekt bleibt.

Siehe auch

new CharacterBoundsUpdateEvent() new ExtendableEvent() new TextFormatUpdateEvent() new FormDataEvent() new MessageEvent()