EditContext.attachedElements() — Methode · JavaScript-Referenz

Signatur

EditContext.prototype.attachedElements()

Beschreibung

Mit der Methode attachedElements() der Schnittstelle EditContext findet man heraus, welches DOM-Element gerade mit einem bestimmten EditContext verbunden ist. Ein Element wird verbunden, indem man seiner Eigenschaft editContext eine Instanz zuweist, z. B. element.editContext = new EditContext().

Die Methode gibt immer ein Array zurück, auch wenn ein EditContext nach der aktuellen Spezifikation höchstens mit einem Element verbunden sein kann. Das Array enthält also entweder genau ein Element oder gar keins. Die Rückgabe als Array ist so gewählt, damit die Schnittstelle später auch mehrere Elemente unterstützen kann.

In der Praxis nützt die Methode vor allem in Editor-Frameworks, in denen ein EditContext-Objekt zwischen Komponenten weitergegeben wird. Man kann damit das zugehörige Element für Fokus, Layout-Berechnungen (etwa updateControlBounds()) oder zum Aufräumen ermitteln, ohne einen separaten Verweis speichern zu müssen.

Rückgabewert

Typ

Array<HTMLElement>

Beschreibung

Ein Array mit dem verbundenen Element (Länge 1) oder ein leeres Array (Länge 0), wenn der EditContext derzeit keinem Element zugeordnet ist.

Beispiele

Verbundenes Element abfragen

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

console.log(ctx.attachedElements().length); // noch nicht verbunden

editor.editContext = ctx;
const [element] = ctx.attachedElements();
console.log(element === editor);

0 true

Verbindung lösen und prüfen

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

// Editor deaktivieren
editor.editContext = null;
console.log(ctx.attachedElements());

[]

Element über den Kontext fokussieren und Grenzen melden

const focusEditor = (ctx) => {
  const [el] = ctx.attachedElements();
  if (!el) {
    console.warn('EditContext ist keinem Element zugeordnet');
    return;
  }
  el.focus();
  ctx.updateControlBounds(el.getBoundingClientRect());
};

if ('EditContext' in window) {
  const canvas = document.querySelector('canvas');
  canvas.editContext = new EditContext({ text: 'Hallo' });
  focusEditor(canvas.editContext);
}

// Wichtig · Fallstricke

Browser-Kompatibilität: Die EditContext-API gilt als experimentell und steht nur in Chromium-Browsern (ab Version 121) zur Verfügung. Vor der Nutzung sollte man per 'EditContext' in window prüfen, ob sie unterstützt wird.
Der Rückgabewert ist immer ein Array. Prüfen Sie deshalb length bzw. destrukturieren Sie mit const [el] = ..., statt eine direkte Elementreferenz zu erwarten.
Nur bestimmte Elemente können einen EditContext erhalten, z. B. <canvas>, <div>, <span>, <p>, <section> oder Überschriften. Bei anderen Elementen wirft die Zuweisung einen NotSupportedError.
Ein EditContext, der bereits einem Element zugeordnet ist, lässt sich keinem zweiten Element zuweisen; das führt ebenfalls zu einem NotSupportedError.
Das zurückgegebene Array ist eine Momentaufnahme und wird nicht automatisch aktualisiert.

Siehe auch

MutationEvent.initMutationEvent() new RTCDTMFToneChangeEvent() EditContext.updateSelection() EditContext.characterBounds() EditContext.updateText()