TextUpdateEvent.updateRangeStart — Eigenschaft · JavaScript-Referenz

Signatur

TextUpdateEvent.updateRangeStart

Beschreibung

Die schreibgeschützte Eigenschaft updateRangeStart des Interfaces TextUpdateEvent gibt den Index des ersten Zeichens im Text eines EditContext an, das durch die aktuelle Eingabe ersetzt wird. Zusammen mit updateRangeEnd beschreibt sie den halboffenen Bereich [updateRangeStart, updateRangeEnd). Den neuen Inhalt findet man in event.text.

Man braucht die Eigenschaft beim Bau eigener Editoren (z. B. Code-Editoren auf Canvas-Basis), die über die EditContext API direkt Tastatur- und IME-Eingaben bekommen. Im textupdate-Handler spiegelt man die Änderung ins eigene Datenmodell. Das geht so: Text vor updateRangeStart behalten, event.text einfügen, Text ab updateRangeEnd anhängen. Danach zeichnet man die Ansicht neu.

Bei einer einfachen Einfügung ohne Auswahl haben updateRangeStart und updateRangeEnd denselben Wert. Ersetzt die Eingabe eine Auswahl, oder schreibt eine IME-Komposition (z. B. bei japanischer Eingabe) vorläufigen Text um, ist updateRangeStart kleiner als updateRangeEnd.

Rückgabewert

Typ

number

Beschreibung

Nicht-negativer Ganzzahl-Index (in UTF-16-Codeeinheiten) des Anfangs des zu ersetzenden Bereichs im Text von EditContext.text.

Beispiele

Ersetzungsbereich protokollieren

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

editContext.addEventListener('textupdate', (event) => {
  console.log(
    `Ersetze [${event.updateRangeStart}, ${event.updateRangeEnd}) durch "${event.text}"`
  );
});

Ersetze [0, 0) durch "H" Ersetze [1, 1) durch "a"

Eigenes Textmodell synchron halten

const canvas = document.querySelector('canvas');
const ctx2d = canvas.getContext('2d');
const editContext = new EditContext({ text: '' });
canvas.editContext = editContext;

let model = '';

const render = () => {
  ctx2d.clearRect(0, 0, canvas.width, canvas.height);
  ctx2d.font = '16px monospace';
  ctx2d.fillText(model, 10, 24);
};

editContext.addEventListener('textupdate', (event) => {
  const { updateRangeStart, updateRangeEnd, text } = event;
  model = model.slice(0, updateRangeStart) + text + model.slice(updateRangeEnd);
  render();
});

Einfügen von Ersetzen unterscheiden

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

editContext.addEventListener('textupdate', (e) => {
  const replaced = e.updateRangeEnd - e.updateRangeStart;
  if (replaced === 0) {
    console.log(`Einfügung an Position ${e.updateRangeStart}`);
  } else {
    console.log(`${replaced} Zeichen ab Position ${e.updateRangeStart} ersetzt`);
  }
});

Einfügung an Position 5 3 Zeichen ab Position 2 ersetzt

// Wichtig · Fallstricke

Kompatibilität: Die EditContext API ist experimentell und bislang nur in Chromium-Browsern verfügbar (Chrome/Edge ab 121). Vorher per Feature-Erkennung prüfen: if ('EditContext' in window) { … }, sonst auf contenteditable oder <textarea> zurückfallen.
Die Indizes zählen UTF-16-Codeeinheiten, keine Graphem-Cluster. Emojis oder Zeichen außerhalb der BMP belegen zwei Positionen. Nutzen Sie deshalb String.prototype.slice() und nicht Array.from()-Indizes.
Beim Auslösen von textupdate hat der Browser EditContext.text und die Auswahl bereits aktualisiert. Ein eigenes Modell müssen Sie trotzdem selbst anpassen und neu zeichnen.
Die Eigenschaft ist schreibgeschützt. Zuweisungen werden stillschweigend ignoriert. Um Text programmatisch zu ändern, nutzen Sie EditContext.updateText().

Siehe auch

TextUpdateEvent TextUpdateEvent.updateRangeEnd TextUpdateEvent.text EditContext EditContext.updateText() PerformanceTiming.domainLookupStart