EditContext.updateSelection() — Methode · JavaScript-Referenz

Signatur

EditContext.prototype.updateSelection(start, end)

Beschreibung

Die Methode updateSelection() aktualisiert den internen Auswahlzustand eines EditContext-Objekts. Mit der EditContext API bauen Entwickler eigene Editoren, etwa auf Basis von <canvas> oder mit selbst gerendertem DOM. Der Browser weiß dabei nicht von sich aus, wo der Nutzer den Cursor gesetzt oder welchen Text er markiert hat. Deshalb muss die Anwendung jede Änderung der Auswahl selbst melden.

Der Aufruf ist vor allem in diesen Fällen nötig:

wenn der Nutzer den Cursor mit Pfeiltasten, Pos1/Ende oder per Mausklick verschiebt,
wenn Text per Maus oder mit Umschalt+Pfeiltaste markiert wird,
nachdem die Anwendung den Text selbst geändert hat, z. B. durch Rückgängig/Wiederholen oder Einfügen aus der Zwischenablage (zusammen mit updateText()).

Die Positionen start und end sind Offsets in UTF-16-Codeeinheiten innerhalb von editContext.text. Liegt start hinter end, wird eine rückwärts gerichtete Auswahl beschrieben, bei der der Anker hinter dem Fokus liegt. Sind beide Werte gleich, handelt es sich um einen einfachen Cursor ohne Markierung. Nach dem Aufruf geben die Eigenschaften selectionStart und selectionEnd die neuen Werte zurück.

Wichtig: updateSelection() ändert nur den Zustand und zeichnet nichts. Cursor und Markierung muss die Anwendung weiterhin selbst darstellen. Außerdem löst die Methode kein textupdate-Ereignis aus.

Parameter

Name	Typ	Default	Beschreibung
$start Pflicht	number		Offset des Auswahlanfangs (Anker) in UTF-16-Codeeinheiten innerhalb von `editContext.text`.
$end Pflicht	number		Offset des Auswahlendes (Fokus). Ist der Wert gleich `start`, steht dort ein Cursor ohne Markierung. Ist er kleiner als `start`, ist die Auswahl rückwärts gerichtet.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Der neue Zustand ist anschließend über selectionStart und selectionEnd abrufbar.

Beispiele

Cursor ans Ende des Textes setzen

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

// Cursor hinter das letzte Zeichen setzen
editContext.updateSelection(editContext.text.length, editContext.text.length);

console.log(editContext.selectionStart, editContext.selectionEnd);

10 10

Cursor-Bewegung mit Pfeiltasten synchronisieren

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

const render = () => {
  // Eigene Darstellung von Text und Cursor (vereinfacht)
  const { text, selectionStart: s, selectionEnd: e } = editContext;
  editor.textContent = `${text.slice(0, s)}|${text.slice(e)}`;
};

editContext.addEventListener('textupdate', render);

editor.addEventListener('keydown', (event) => {
  const { selectionStart: s, selectionEnd: e, text } = editContext;
  if (event.key === 'ArrowLeft') {
    const pos = s === e ? Math.max(0, s - 1) : Math.min(s, e);
    editContext.updateSelection(pos, pos);
  } else if (event.key === 'ArrowRight') {
    const pos = s === e ? Math.min(text.length, e + 1) : Math.max(s, e);
    editContext.updateSelection(pos, pos);
  } else {
    return;
  }
  event.preventDefault();
  render();
});

Rückwärts gerichtete Auswahl mit Umschalt+Pfeil links

const editContext = new EditContext({
  text: 'programmierung.net',
  selectionStart: 14,
  selectionEnd: 14
});

// Anker bleibt bei 14, der Fokus wandert zweimal nach links
let anchor = 14;
let focus = 14;
for (let i = 0; i < 2; i++) {
  focus = Math.max(0, focus - 1);
  editContext.updateSelection(anchor, focus);
}

console.log(editContext.selectionStart, editContext.selectionEnd);
console.log(editContext.text.slice(Math.min(anchor, focus), Math.max(anchor, focus)));

14 12 ng

Text ersetzen und Auswahl nachführen (z. B. beim Einfügen)

const pasteText = (editContext, insert) => {
  const start = Math.min(editContext.selectionStart, editContext.selectionEnd);
  const end = Math.max(editContext.selectionStart, editContext.selectionEnd);

  // Text im EditContext ersetzen …
  editContext.updateText(start, end, insert);
  // … und den Cursor hinter den eingefügten Text setzen
  const caret = start + insert.length;
  editContext.updateSelection(caret, caret);
};

const ctx = new EditContext({ text: 'Hallo !', selectionStart: 6, selectionEnd: 6 });
pasteText(ctx, 'Welt');
console.log(ctx.text, ctx.selectionStart);

Hallo Welt! 10

// Wichtig · Fallstricke

Browser-Kompatibilität: Die EditContext API ist experimentell und bisher nur in Chromium-basierten Browsern ab Version 121 verfügbar. Prüfe die Unterstützung vorher, z. B. mit 'EditContext' in window, und sieh eine Ausweichlösung vor, etwa ein contenteditable-Element oder ein <textarea>.
Keine automatische Darstellung: Die Methode ändert nur den internen Zustand. Cursor und Markierung musst du selbst zeichnen. Liegen Anzeige und EditContext-Zustand auseinander, setzt die IME den Text an der falschen Stelle ein.
UTF-16-Offsets: Die Positionen zählen UTF-16-Codeeinheiten, keine Grapheme. Emojis oder kombinierte Zeichen können mehrere Einheiten belegen. Setze den Cursor nicht mitten in ein Ersatzzeichenpaar (Surrogatpaar).
Werte außerhalb des Textes: Liegen start oder end hinter der Textlänge, werden sie auf text.length begrenzt. Verlasse dich aber nicht darauf und prüfe die Werte selbst.
Die Methode löst kein textupdate-Ereignis aus. Rufe deine Rendering-Logik selbst auf.
Melde zusätzlich die Bildschirmposition von Auswahl und Steuerelement mit updateSelectionBounds() und updateControlBounds(). Nur so kann das Betriebssystem das IME-Fenster korrekt neben dem Cursor anzeigen.

Siehe auch

EditContext EditContext.updateText() EditContext.updateSelectionBounds() EditContext.updateControlBounds() EditContext.selectionStart EditContext.selectionEnd