EditContext.updateText() — Methode · JavaScript-Referenz

Signatur

EditContext.prototype.updateText(rangeStart, rangeEnd, text)

Beschreibung

Die Methode updateText() gleicht den internen Textzustand eines EditContext an den Text an, den deine Anwendung selbst verwaltet. Die EditContext-API trennt die Texteingabe (Tastatur, IME, virtuelle Tastatur, Diktat) von der Darstellung. Den sichtbaren Text rendert deine Anwendung selbst, zum Beispiel in ein <canvas> oder in eigene DOM-Knoten. Damit Eingabemethoden wie eine IME passende Vorschläge und Komposition liefern, muss der Text im EditContext immer mit deinem Modell übereinstimmen.

Brauchst du den Aufruf, wenn der Text nicht durch das Betriebssystem oder die IME geändert wird, sondern durch deine Anwendung. Typische Fälle: Einfügen aus der Zwischenablage, Rückgängig/Wiederholen, Suchen und Ersetzen, Autokorrektur, Laden eines Dokuments oder Änderungen durch andere Nutzer beim gemeinsamen Bearbeiten. Tippt der Nutzer normal, aktualisiert der Browser den internen Text selbst und löst das Ereignis textupdate aus. Dann ist updateText() nicht nötig.

Die Positionen rangeStart und rangeEnd sind Offsets in UTF-16-Codeeinheiten, genau wie bei String.prototype.slice(). Sind beide Werte gleich, wird text an dieser Stelle eingefügt. Ist text leer, wird der Bereich gelöscht. Die Auswahl passt die Methode nicht an. Das erledigst du danach mit updateSelection().

Parameter

Name	Typ	Beschreibung
$rangeStart Pflicht	number	Startposition des zu ersetzenden Bereichs, gemessen in UTF-16-Codeeinheiten ab Textanfang.
$rangeEnd Pflicht	number	Endposition (exklusiv) des zu ersetzenden Bereichs. Ist sie gleich `rangeStart`, wird nur eingefügt.
$text Pflicht	string	Neuer Text, der den Bereich ersetzt. Ein leerer String löscht den Bereich.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Das Ergebnis siehst du in der Eigenschaft EditContext.text.

Beispiele

Grundlegende Textersetzung

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

// "Welt" (Position 6 bis 10) durch "Leser" ersetzen
editContext.updateText(6, 10, 'Leser');
console.log(editContext.text);

// Am Ende einfügen (Start = Ende)
editContext.updateText(editContext.text.length, editContext.text.length, '!');
console.log(editContext.text);

// Bereich löschen (leerer String)
editContext.updateText(0, 6, '');
console.log(editContext.text);

Hallo Leser Hallo Leser! Leser!

Einfügen aus der Zwischenablage synchronisieren

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

const render = () => {
  editor.textContent = editContext.text;
};

// Normales Tippen: Der Browser aktualisiert den Text selbst
editContext.addEventListener('textupdate', render);

// Einfügen: Das übernimmt die Anwendung, also Text selbst anpassen
editor.addEventListener('paste', (event) => {
  event.preventDefault();
  const pasted = event.clipboardData.getData('text/plain');
  const { selectionStart: start, selectionEnd: end } = editContext;

  editContext.updateText(start, end, pasted);
  // Cursor hinter den eingefügten Text setzen
  const caret = start + pasted.length;
  editContext.updateSelection(caret, caret);
  render();
});

Rückgängig-Funktion mit eigenem Verlauf

const editContext = new EditContext({ text: '' });
const history = [];

editContext.addEventListener('textupdate', (e) => {
  // Vorherigen Inhalt des Bereichs merken, um ihn wiederherstellen zu können
  const before = editContext.text; // bereits aktualisiert
  history.push({
    start: e.updateRangeStart,
    end: e.updateRangeStart + e.text.length,
    removed: e.removedText ?? ''
  });
});

const undo = () => {
  const last = history.pop();
  if (!last) return;
  editContext.updateText(last.start, last.end, last.removed);
  const caret = last.start + last.removed.length;
  editContext.updateSelection(caret, caret);
};

// Simulation ohne echte Eingabe: Änderung vormerken und rückgängig machen
editContext.updateText(0, 0, 'Entwurf');
history.push({ start: 0, end: 7, removed: '' });
undo();
console.log(JSON.stringify(editContext.text));

""

// Wichtig · Fallstricke

Kein Ereignis: updateText() löst kein textupdate-Ereignis aus. Nach dem Aufruf musst du die Darstellung selbst neu zeichnen.
Auswahl anpassen: Die Auswahl verschiebt sich nicht automatisch. Setze sie danach mit updateSelection(), sonst stehen IME und Cursor an einer falschen Stelle.
Nicht während einer Komposition aufrufen: Läuft gerade eine IME-Komposition (zwischen compositionstart und compositionend), können Änderungen am Text sie stören oder abbrechen.
UTF-16-Offsets: Emojis und andere Zeichen außerhalb der BMP belegen zwei Codeeinheiten. Liegen die Offsets mitten in einem Surrogatpaar, entsteht ungültiger Text.
Kompatibilität: Die EditContext-API ist experimentell und bisher nur in Chromium-Browsern verfügbar (Chrome/Edge ab 121). Prüfe die Unterstützung mit 'EditContext' in window und sieh eine Ausweichlösung vor, etwa contenteditable oder ein <textarea>.
Kein XSS-Risiko durch die Methode selbst: Der Text wird nur gespeichert. Schreibst du ihn aber über innerHTML ins DOM, musst du ihn escapen. Nutze besser textContent.

Siehe auch

EditContext EditContext.updateSelection() EditContext.text EditContext.updateControlBounds() TextUpdateEvent EditContext.attachedElements()