EditContext: textupdate — Ereignis · JavaScript-Referenz

Signatur

editContext.addEventListener("textupdate", handler)

Beschreibung

Das Ereignis textupdate ist das wichtigste Ereignis der EditContext API. Es wird ausgelöst, sobald der Benutzer in einem Element, dessen Eigenschaft editContext auf eine EditContext-Instanz gesetzt ist, Text eingibt, löscht, ersetzt oder per IME (Eingabemethode, z. B. für Chinesisch oder Japanisch) zusammensetzt. Der Handler erhält ein TextUpdateEvent.

Anders als bei contenteditable verändert der Browser dabei nicht das DOM. Er aktualisiert nur das interne Textmodell (editContext.text, selectionStart, selectionEnd), bevor das Ereignis ausgelöst wird. Die Darstellung übernimmt allein Ihr Code, zum Beispiel auf einem <canvas> oder in einem selbst verwalteten DOM-Baum. Deshalb eignet sich die API vor allem für eigene Code-Editoren, Textverarbeitungen und Canvas-Anwendungen.

Registrieren können Sie das Ereignis mit editContext.addEventListener("textupdate", handler) oder über die Eigenschaft editContext.ontextupdate = handler. Die Eigenschaften des Ereignisses geben den ersetzten Bereich (updateRangeStart/updateRangeEnd), den eingefügten Text (text) und die neue Auswahl an. Damit lässt sich auch ein eigenes, separates Dokumentmodell nachführen.

Parameter

Name	Typ	Beschreibung
$handler Pflicht	(event: TextUpdateEvent) => void	Callback, der bei jeder Text- oder Auswahländerung aufgerufen wird.
$event.text	string	Der eingefügte Text, der den Bereich `updateRangeStart` bis `updateRangeEnd` ersetzt. Beim Löschen ist er leer (`""`).
$event.updateRangeStart	number	Startposition (UTF-16-Index) des ersetzten Bereichs im alten Text.
$event.updateRangeEnd	number	Endposition (exklusiv) des ersetzten Bereichs im alten Text.
$event.selectionStart	number	Beginn der Auswahl bzw. Position der Einfügemarke nach der Änderung.
$event.selectionEnd	number	Ende der Auswahl nach der Änderung. Ist der Wert gleich `selectionStart`, ist die Auswahl leer (nur Einfügemarke).

Rückgabewert

Typ

void

Beschreibung

Event-Handler liefern keinen Rückgabewert. textupdate lässt sich nicht abbrechen, preventDefault() hat keine Wirkung.

Beispiele

Canvas-Editor: Text bei jeder Eingabe neu zeichnen

// <canvas id="editor" width="400" height="80" tabindex="0"></canvas>
const canvas = document.querySelector('#editor');
const ctx = canvas.getContext('2d');

const editContext = new EditContext();
canvas.editContext = editContext;

const render = (text, selStart) => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.font = '20px monospace';
  ctx.fillText(text, 10, 40);
  // Einfügemarke zeichnen
  const x = 10 + ctx.measureText(text.slice(0, selStart)).width;
  ctx.fillRect(x, 22, 2, 24);
};

editContext.addEventListener('textupdate', (event) => {
  // editContext.text ist bereits aktualisiert
  render(editContext.text, event.selectionStart);
  console.log(`"${event.text}" bei ${event.updateRangeStart}–${event.updateRangeEnd}`);
});

canvas.focus();

"H" bei 0–0 "a" bei 1–1 "" bei 1–2 // nach Rücktaste

Eigenes Dokumentmodell mit den Bereichsangaben nachführen

const editor = document.querySelector('#editor');
const editContext = new EditContext({ text: 'Hallo Welt' });
editor.editContext = editContext;

// Eigenes Modell, z. B. für Undo oder Syntaxhervorhebung
let model = 'Hallo Welt';
const history = [];

const onTextUpdate = ({ text, updateRangeStart, updateRangeEnd, selectionStart }) => {
  history.push({ removed: model.slice(updateRangeStart, updateRangeEnd), inserted: text, at: updateRangeStart });
  model = model.slice(0, updateRangeStart) + text + model.slice(updateRangeEnd);
  editor.textContent = model;
  console.log(model, '| Marke bei', selectionStart);
};

editContext.addEventListener('textupdate', onTextUpdate);

Hallo Welt! | Marke bei 11

Handler über ontextupdate setzen und wieder entfernen

const editor = document.querySelector('#editor');
const editContext = new EditContext();
editor.editContext = editContext;

const logUpdate = (e) => console.log('Neuer Text:', editContext.text);

// Variante 1: on-Property (nur ein Handler möglich)
editContext.ontextupdate = logUpdate;

// Variante 2: addEventListener / removeEventListener
editContext.ontextupdate = null;
editContext.addEventListener('textupdate', logUpdate);

// Editor schreibgeschützt schalten
const setReadOnly = () => {
  editContext.removeEventListener('textupdate', logUpdate);
  editor.editContext = null; // Verknüpfung lösen
};

Neuer Text: a Neuer Text: ab

Funktionsprüfung mit Rückfall auf contenteditable

const editor = document.querySelector('#editor');

if ('EditContext' in window) {
  const editContext = new EditContext();
  editor.editContext = editContext;
  editContext.addEventListener('textupdate', () => {
    editor.textContent = editContext.text;
  });
} else {
  // Rückfall für Firefox/Safari
  editor.contentEditable = 'true';
  editor.addEventListener('input', () => console.log(editor.textContent));
}

Siehe auch

EditContext: textformatupdate EditContext: characterboundsupdate EditContext: compositionend EditContext: compositionstart AudioContext: sinkchange BaseAudioContext: statechange Element: pointerrawupdate