ShadowRoot.fullscreenElement — Eigenschaft · JavaScript-Referenz

Signatur

ShadowRoot.fullscreenElement

Beschreibung

Die schreibgeschützte Eigenschaft fullscreenElement eines ShadowRoot liefert das Element innerhalb dieses Shadow Tree, das sich gerade im Vollbildmodus befindet. Gibt es dort kein solches Element, ist der Wert null.

Die Eigenschaft ist das Gegenstück zu Document.fullscreenElement und stammt aus dem Mixin DocumentOrShadowRoot. Wichtig ist das Retargeting, also die Umlenkung auf den Host: Liegt das Vollbild-Element in einem Shadow DOM, gibt document.fullscreenElement nicht das eigentliche innere Element zurück, sondern nur das Host-Element der Web Component. Das tatsächliche Element im Shadow Tree erhält man nur über shadowRoot.fullscreenElement.

Gebraucht wird die Eigenschaft vor allem in Web Components, die einen eigenen Video-Player, eine Bildergalerie oder eine Kartenansicht mit Vollbild-Umschalter enthalten. Die Komponente kann damit prüfen, ob eines ihrer eigenen Elemente im Vollbild läuft, und ihre Oberfläche entsprechend anpassen, zum Beispiel das Symbol des Buttons umschalten.

Rückgabewert

Typ

Element | null

Beschreibung

Das Element im Shadow Tree, das sich gerade im Vollbildmodus befindet, oder null, wenn kein Element dieses Shadow Tree im Vollbild ist.

Beispiele

Unterschied zwischen document und shadowRoot

const host = document.createElement('div');
document.body.append(host);
const root = host.attachShadow({ mode: 'open' });
root.innerHTML = '<video id="clip" src="film.mp4" controls></video>';

const video = root.getElementById('clip');

document.addEventListener('fullscreenchange', () => {
  console.log('document:', document.fullscreenElement);
  console.log('shadowRoot:', root.fullscreenElement);
});

// Muss durch eine Nutzeraktion ausgelöst werden
document.body.addEventListener('click', () => video.requestFullscreen(), { once: true });

document: <div> (Host-Element, umgelenkt) shadowRoot: <video id="clip">

Web Component mit Vollbild-Umschalter

class GalleryView extends HTMLElement {
  constructor() {
    super();
    const root = this.attachShadow({ mode: 'open' });
    root.innerHTML = `
      <figure id="stage"><img src="bild.jpg" alt="Bild"></figure>
      <button id="toggle">Vollbild</button>`;

    this.stage = root.getElementById('stage');
    this.button = root.getElementById('toggle');

    this.button.addEventListener('click', async () => {
      if (root.fullscreenElement === this.stage) {
        await document.exitFullscreen();
      } else {
        await this.stage.requestFullscreen();
      }
    });

    this.onChange = () => {
      const active = root.fullscreenElement === this.stage;
      this.button.textContent = active ? 'Vollbild beenden' : 'Vollbild';
    };
  }

  connectedCallback() {
    document.addEventListener('fullscreenchange', this.onChange);
  }

  disconnectedCallback() {
    document.removeEventListener('fullscreenchange', this.onChange);
  }
}

customElements.define('gallery-view', GalleryView);

Ohne Vollbild ist der Wert null

const host = document.createElement('section');
const root = host.attachShadow({ mode: 'open' });
root.innerHTML = '<p>Inhalt</p>';

console.log(root.fullscreenElement);

null

// Wichtig · Fallstricke

Retargeting: document.fullscreenElement liefert bei Vollbild-Elementen im Shadow DOM nur den Host. Wer das genaue Element vergleichen will, muss shadowRoot.fullscreenElement verwenden.
Verschachtelte Shadow Roots: Auch in einem äußeren Shadow Root wird der Wert auf den Host des inneren Shadow Root umgelenkt. Nur der Shadow Root, der das Element direkt enthält, liefert das Element selbst.
Geschlossene Shadow Roots (mode: 'closed'): Von außen kommt man nicht an den Shadow Root heran. Die Komponente muss sich dann intern selbst einen Verweis darauf merken.
Schreibgeschützt: Wer der Eigenschaft einen Wert zuweist, bewirkt nichts. Das Vollbild wird mit Element.requestFullscreen() gestartet und mit document.exitFullscreen() beendet. Es gibt kein ShadowRoot.exitFullscreen().
Nutzeraktion erforderlich: requestFullscreen() funktioniert nur nach einer Nutzeraktion, etwa einem Klick. In iframes braucht es außerdem allow="fullscreen".
Kompatibilität: In Safari ist die Eigenschaft erst ab Version 16.4 verfügbar. In älteren WebKit-Versionen gab es nur Varianten mit Präfix am Dokument, zum Beispiel webkitFullscreenElement, und keine am ShadowRoot. Vorher sollte man die Unterstützung prüfen, etwa mit 'fullscreenElement' in ShadowRoot.prototype.

Siehe auch

Document.fullscreenElement Element.requestFullscreen() Document.exitFullscreen() ShadowRoot ShadowRoot.pointerLockElement Element.attachShadow()