ShadowRoot.slotAssignment — Eigenschaft · JavaScript-Referenz

Signatur

ShadowRoot.slotAssignment

Beschreibung

Die schreibgeschützte Eigenschaft slotAssignment zeigt, wie die Kindknoten des Host-Elements den <slot>-Elementen im Shadow-DOM zugeordnet werden. Der Modus wird einmalig beim Aufruf von Element.prototype.attachShadow() über die Option slotAssignment festgelegt und lässt sich danach nicht mehr ändern.

"named" (Standard): Der Browser ordnet Light-DOM-Kinder automatisch zu. Elemente mit slot="name" landen im gleichnamigen Slot, alle übrigen Knoten im Standard-Slot ohne Namen.
"manual": Es gibt keine automatische Zuordnung. Die Komponente legt selbst fest, welcher Knoten in welchem Slot erscheint, und ruft dafür HTMLSlotElement.prototype.assign() auf. Das slot-Attribut der Kinder wird dabei ignoriert.

Die Eigenschaft ist vor allem für generischen Code nützlich, zum Beispiel für Bibliotheken, Hilfsfunktionen oder Werkzeuge zur Fehlersuche. Dieser Code muss erkennen, ob ein Shadow-Root manuell verwaltet wird, bevor er Slots befüllt oder Zuweisungen auswertet. Der manuelle Modus eignet sich für Komponenten wie Tabs, Karussells oder Listen. Dort soll je nach Zustand ein anderes Kind angezeigt werden, ohne dass das Light-DOM umgebaut oder mit slot-Attributen versehen werden muss.

Rückgabewert

Typ

"named" | "manual"

Beschreibung

Ein String mit dem Zuweisungsmodus. Er ist "named", wenn bei attachShadow() nichts angegeben wurde.

Beispiele

Modus nach attachShadow() auslesen

const hostA = document.createElement('div');
const hostB = document.createElement('div');

const rootA = hostA.attachShadow({ mode: 'open' });
const rootB = hostB.attachShadow({ mode: 'open', slotAssignment: 'manual' });

console.log(rootA.slotAssignment);
console.log(rootB.slotAssignment);

named manual

Tab-Komponente mit manueller Slot-Zuweisung

class SimpleTabs extends HTMLElement {
  #slot;

  constructor() {
    super();
    const root = this.attachShadow({ mode: 'open', slotAssignment: 'manual' });
    root.innerHTML = '<nav part="nav"></nav><slot></slot>';
    this.#slot = root.querySelector('slot');
  }

  connectedCallback() {
    this.show(0);
  }

  show(index) {
    const panel = this.children[index];
    // Nur im manuellen Modus ist assign() wirksam
    if (panel && this.shadowRoot.slotAssignment === 'manual') {
      this.#slot.assign(panel);
    }
  }
}

customElements.define('simple-tabs', SimpleTabs);

const tabs = document.createElement('simple-tabs');
tabs.innerHTML = '<p>Tab 1</p><p>Tab 2</p>';
document.body.append(tabs);
tabs.show(1);
console.log(tabs.shadowRoot.querySelector('slot').assignedElements()[0].textContent);

Tab 2

Generische Hilfsfunktion, die beide Modi unterstützt

const placeInSlot = (host, node, slotName = '') => {
  const root = host.shadowRoot;
  if (!root) throw new Error('Kein offener Shadow-Root vorhanden');

  if (root.slotAssignment === 'manual') {
    const selector = slotName ? `slot[name="${slotName}"]` : 'slot:not([name])';
    const slot = root.querySelector(selector);
    host.append(node);
    slot?.assign(...slot.assignedNodes(), node);
  } else {
    if (slotName) node.slot = slotName;
    host.append(node);
  }
};

const host = document.createElement('div');
host.attachShadow({ mode: 'open' }).innerHTML = '<slot name="title"></slot>';
const h = document.createElement('h2');
h.textContent = 'Hallo';
placeInSlot(host, h, 'title');
console.log(host.shadowRoot.slotAssignment, h.assignedSlot?.name);

named title

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie root.slotAssignment = 'manual' wird stillschweigend ignoriert und löst im Strict Mode einen TypeError aus. Der Modus kann nur über attachShadow() gesetzt werden.
assign() im Modus "named": Der Aufruf wirft keinen Fehler, hat aber keine sichtbare Wirkung. Die Zuordnung erfolgt weiterhin über das slot-Attribut.
Nur direkte Kinder: Im manuellen Modus lassen sich nur direkte Kindknoten des Host-Elements zuweisen. Wird ein Knoten aus dem Host entfernt, verliert er seine Zuweisung. Wird er einem anderen Slot zugewiesen, verschwindet er aus dem bisherigen.
Deklaratives Shadow DOM: In <template shadowrootmode> gibt es bislang kein Attribut für den manuellen Modus. Solche Shadow-Roots haben immer den Modus "named".
Kompatibilität: In älteren Browsern, etwa Safari vor 16.4 oder Firefox vor 92, ist die Eigenschaft undefined. Zur Erkennung eignet sich 'slotAssignment' in ShadowRoot.prototype.
Bei geschlossenen Shadow-Roots (mode: 'closed') ist host.shadowRoot gleich null. Dann lässt sich die Eigenschaft nur über die intern gespeicherte Referenz auf den Shadow-Root auslesen.

Siehe auch

Element.prototype.attachShadow() HTMLSlotElement.prototype.assign() HTMLSlotElement.prototype.assignedNodes() Element.assignedSlot ShadowRoot.mode ShadowRoot HTMLTemplateElement.shadowRootSlotAssignment