HTMLElement.editContext — Eigenschaft · JavaScript-Referenz

Signatur

HTMLElement.editContext

Beschreibung

Mit der Eigenschaft editContext verbindet man ein HTML-Element mit einem EditContext-Objekt aus der EditContext API. Danach kann das Element den Fokus bekommen und Texteingaben annehmen. Das gilt für Tastatur, Eingabemethoden (IME) für Chinesisch, Japanisch und Koreanisch, virtuelle Tastaturen und Handschrift. Anders als bei contenteditable ändert der Browser das DOM aber nicht selbst. Er meldet nur über Ereignisse wie textupdate, was sich ändern soll. Die Anwendung hält den Text in ihrem eigenen Datenmodell und zeichnet ihn selbst, zum Beispiel ins DOM oder auf ein <canvas>.

Die API ist für aufwendige Editoren gedacht, etwa Code-Editoren, Office-Anwendungen im Browser oder Editoren auf Canvas-Basis. Solche Editoren brauchen die volle Kontrolle über Darstellung und Datenmodell und sollen trotzdem mit allen Eingabemethoden des Betriebssystems funktionieren. Früher brauchte man dafür Umwege wie versteckte <textarea>-Elemente.

Beim Lesen liefert die Eigenschaft das verbundene EditContext oder null. Beim Setzen weist man ein EditContext zu oder löst die Verbindung mit null wieder. Das funktioniert nur bei bestimmten Elementen: bei <canvas> und bei allen Elementen, die auch attachShadow() erlauben. Dazu gehören <div>, <span>, <p>, <article>, <section>, <main>, Überschriften und eigene Elemente (Custom Elements).

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	EditContext \| null	null	Beim Setzen: das `EditContext`, das mit dem Element verbunden werden soll, oder `null`, um die Verbindung zu lösen.

Rückgabewert

Typ

EditContext | null

Beschreibung

Das mit dem Element verbundene EditContext-Objekt oder null, wenn keins verbunden ist.

Beispiele

EditContext zuweisen und prüfen

// HTML: <div id="editor"></div>
const editor = document.getElementById('editor');

if ('EditContext' in window) {
  const ctx = new EditContext({ text: 'Hallo', selectionStart: 5, selectionEnd: 5 });
  editor.editContext = ctx;

  console.log(editor.editContext === ctx);
  console.log(editor.editContext.text);
} else {
  console.log('EditContext API wird nicht unterstützt');
}

true Hallo

Einfacher Editor mit eigener Darstellung

// HTML: <div id="editor" style="border:1px solid #999;min-height:2em"></div>
const editor = document.getElementById('editor');
const ctx = new EditContext();
editor.editContext = ctx;

const render = () => {
  // Der Browser ändert das DOM nicht selbst, das übernimmt die Anwendung
  editor.textContent = ctx.text;
};

ctx.addEventListener('textupdate', (event) => {
  console.log(`Neuer Text "${event.text}" im Bereich ${event.updateRangeStart}–${event.updateRangeEnd}`);
  render();
});

// Rechteck des Editors mitteilen, damit IME-Fenster richtig platziert werden
const updateBounds = () => ctx.updateControlBounds(editor.getBoundingClientRect());
updateBounds();
window.addEventListener('resize', updateBounds);

editor.focus();

Neuer Text "a" im Bereich 0–0 (nach Eingabe von „a“)

Canvas-Editor mit Positionen für die Eingabemethode

// HTML: <canvas id="c" width="400" height="60"></canvas>
const canvas = document.getElementById('c');
const g = canvas.getContext('2d');
const ctx = new EditContext();
canvas.editContext = ctx;

g.font = '20px monospace';
const charWidth = g.measureText('M').width;

const draw = () => {
  g.clearRect(0, 0, canvas.width, canvas.height);
  g.fillText(ctx.text, 10, 35);
};

ctx.addEventListener('textupdate', draw);

// Die Eingabemethode fragt nach den Positionen der Zeichen (für das Kandidatenfenster)
ctx.addEventListener('characterboundsupdate', (e) => {
  const r = canvas.getBoundingClientRect();
  const bounds = [];
  for (let i = e.rangeStart; i < e.rangeEnd; i++) {
    bounds.push(new DOMRect(r.left + 10 + i * charWidth, r.top + 15, charWidth, 24));
  }
  ctx.updateCharacterBounds(e.rangeStart, bounds);
});

canvas.focus();

Verbindung wieder lösen

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

// Später, etwa im Nur-Lesen-Modus:
editor.editContext = null;
console.log(editor.editContext);

null

// Wichtig · Fallstricke

Browser-Unterstützung: Die API ist experimentell und nur in Chromium-Browsern verfügbar (Chrome/Edge ab Version 121). Firefox und Safari unterstützen sie nicht. Prüfe die Unterstützung mit 'EditContext' in window und sieh eine Ausweichlösung vor, zum Beispiel contenteditable oder eine versteckte <textarea>.
Nur bestimmte Elemente: Wird die Eigenschaft bei einem nicht erlaubten Element gesetzt, etwa <input>, <a> oder <img>, wirft der Browser eine NotSupportedError-DOMException.
Nur an ein Element gleichzeitig: Ein EditContext kann nur mit einem Element verbunden sein. Wird es einem zweiten Element zugewiesen, wirft der Browser ebenfalls einen NotSupportedError. Welche Elemente verbunden sind, liefert editContext.attachedElements().
Keine automatische Darstellung: Der Browser fügt keinen Text ins DOM ein und zeichnet weder Cursor noch Auswahl. Das muss die Anwendung selbst erledigen. Sie sollte außerdem updateSelection(), updateControlBounds() und updateSelectionBounds() aufrufen, sonst erscheinen IME-Fenster an der falschen Stelle.
Verhältnis zu contenteditable: Hat ein Element ein EditContext, gilt dieses statt contenteditable. Das Element wird fokussierbar.
Barrierefreiheit: Weil die Anwendung selbst zeichnet, besonders auf <canvas>, braucht sie passende ARIA-Rollen und -Attribute (z. B. role=\"textbox\"). Sonst können Screenreader den Inhalt nicht erfassen.

Siehe auch

HTMLElement.innerText HTMLElement.outerText HTMLElement.autocorrect HTMLElement.dataset HTMLElement.inert