TextUpdateEvent.text — Eigenschaft · JavaScript-Referenz

Signatur

TextUpdateEvent.text

Beschreibung

Die Eigenschaft text eines TextUpdateEvent liefert die Zeichenkette, die der Benutzer oder der Eingabemethoden-Editor (IME) gerade eingegeben hat. Das Ereignis wird von einem EditContext ausgelöst, wenn sich dessen Textinhalt durch Benutzereingaben ändert.

Zusammen mit updateRangeStart und updateRangeEnd beschreibt text genau, welcher Teil des Textes ersetzt wurde: Die Zeichen im Bereich [updateRangeStart, updateRangeEnd) werden durch text ersetzt. Ist text ein leerer String, wurde Text gelöscht (z. B. mit der Rücktaste), ohne dass etwas eingefügt wurde.

Wichtig: Der EditContext hat seinen internen Text beim Auslösen des Ereignisses schon aktualisiert. Die Eigenschaft ist vor allem für eigene Editoren nützlich (z. B. auf Basis von Canvas), die ihr eigenes Textmodell oder ihre Darstellung schrittweise nachziehen wollen, statt jedes Mal den ganzen Text neu zu zeichnen.

Rückgabewert

Typ

string

Beschreibung

Der eingefügte Text. Ein leerer String bedeutet, dass im Bereich nur gelöscht wurde.

Beispiele

Eingegebenen Text protokollieren

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

editContext.addEventListener('textupdate', (event) => {
  console.log(`Eingefügt: "${event.text}" an Position ${event.updateRangeStart}–${event.updateRangeEnd}`);
});

Eingefügt: "a" an Position 0–0

Eigenes Textmodell inkrementell nachziehen

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

let model = '';

editContext.addEventListener('textupdate', (event) => {
  const { text, updateRangeStart, updateRangeEnd } = event;
  model = model.slice(0, updateRangeStart) + text + model.slice(updateRangeEnd);
  // Nach der Änderung stimmt das Modell mit editContext.text überein
  console.log(model === editContext.text);
  render(model);
});

const render = (value) => {
  const ctx = canvas.getContext('2d');
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.font = '16px sans-serif';
  ctx.fillText(value, 10, 24);
};

true

Löschen von Einfügen unterscheiden

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

editContext.addEventListener('textupdate', ({ text, updateRangeStart, updateRangeEnd }) => {
  if (text === '') {
    console.log(`Gelöscht: ${updateRangeEnd - updateRangeStart} Zeichen`);
  } else {
    console.log(`Eingefügt: ${text.length} Zeichen`);
  }
});

Gelöscht: 1 Zeichen

// Wichtig · Fallstricke

Kompatibilität: Die EditContext-API ist experimentell und nur in Chromium-Browsern verfügbar (ab Chrome/Edge 121). Vorher mit 'EditContext' in window prüfen und notfalls auf contenteditable oder <textarea> zurückfallen.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ohne Fehler ignoriert (im Strict Mode gibt es einen TypeError).
Bei IME-Komposition (z. B. Japanisch, Chinesisch) können viele textupdate-Ereignisse hintereinander kommen, die denselben Bereich immer wieder ersetzen. text enthält dann jeweils den aktuellen Kompositionsstand, nicht das Endergebnis.
text kann mehrere Zeichen, Emojis oder Surrogatpaare enthalten. text.length zählt UTF-16-Codeeinheiten, keine sichtbaren Zeichen.
Den Text nicht ungeprüft über innerHTML ins DOM schreiben, sonst droht XSS. Besser textContent verwenden.

Siehe auch

PeriodicSyncEvent.tag TextUpdateEvent.selectionEnd TextUpdateEvent.selectionStart TextUpdateEvent.updateRangeEnd TextUpdateEvent.updateRangeStart