ScreenDetailed.isInternal — Eigenschaft · JavaScript-Referenz

Signatur

ScreenDetailed.isInternal

Beschreibung

Die Eigenschaft isInternal gehört zum Interface ScreenDetailed der Window Management API (früher „Multi-Screen Window Placement API“). Sie gibt an, ob ein Bildschirm fest im Gerät verbaut ist, etwa das eingebaute Display eines Laptops oder Tablets (true), oder ob es sich um einen externen Monitor, Beamer oder ein ähnliches Anzeigegerät handelt (false).

Ein ScreenDetailed-Objekt erhältst du nicht direkt über window.screen. Du bekommst es über window.getScreenDetails(). Diese Methode liefert ein ScreenDetails-Objekt mit den Eigenschaften screens (alle angeschlossenen Bildschirme) und currentScreen (der Bildschirm, auf dem das aktuelle Fenster liegt).

Typische Anwendungsfälle:

Präsentationsprogramme: Die Referentenansicht bleibt auf dem internen Laptop-Display, die Folien laufen auf dem externen Beamer.
Handels- oder Dashboard-Anwendungen, die Zusatzfenster bevorzugt auf externen Monitoren öffnen.
Vollbild-Anwendungen, die gezielt einen bestimmten Bildschirm ansteuern, zum Beispiel mit element.requestFullscreen({ screen }).

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Bildschirm fest im Gerät verbaut ist, sonst false. Der Wert ist schreibgeschützt.

Beispiele

Internen und externen Bildschirm ermitteln

const listScreens = async () => {
  if (!('getScreenDetails' in window)) {
    console.log('Window Management API wird nicht unterstützt.');
    return;
  }
  const details = await window.getScreenDetails();
  for (const screen of details.screens) {
    const art = screen.isInternal ? 'intern' : 'extern';
    console.log(`${screen.label}: ${art} (${screen.width}×${screen.height})`);
  }
};

listScreens();

Built-in Retina Display: intern (1512×982) DELL U2720Q: extern (2560×1440)

Präsentation im Vollbild auf dem externen Bildschirm starten

const startPresentation = async (slidesElement) => {
  const { screens } = await window.getScreenDetails();
  // Bevorzugt einen externen Bildschirm (Beamer), sonst den ersten Bildschirm
  const target = screens.find((s) => !s.isInternal) ?? screens[0];
  await slidesElement.requestFullscreen({ screen: target });
};

// requestFullscreen braucht eine Nutzergeste, deshalb im Klick-Handler aufrufen
document.querySelector('#start').addEventListener('click', () => {
  startPresentation(document.querySelector('#slides'));
});

Auf das Anschließen und Trennen von Bildschirmen reagieren

const details = await window.getScreenDetails();

const report = () => {
  const externe = details.screens.filter((s) => !s.isInternal).length;
  console.log(`Externe Bildschirme: ${externe}`);
};

details.addEventListener('screenschange', report);
report();

Externe Bildschirme: 1

// Wichtig · Fallstricke

Browser-Unterstützung: Die Eigenschaft ist nur in Chromium-basierten Browsern verfügbar (ab Chrome/Edge 100). Firefox und Safari unterstützen sie nicht. Prüfe deshalb vorher mit 'getScreenDetails' in window, ob die API vorhanden ist.
Berechtigung: getScreenDetails() fragt beim ersten Aufruf die Berechtigung window-management ab (früher window-placement). Lehnt der Nutzer ab, wird das Promise mit einem Fehler abgewiesen. Den aktuellen Status liefert navigator.permissions.query({ name: 'window-management' }).
Sicherer Kontext: Die API funktioniert nur über HTTPS. In iframe-Elementen muss sie zusätzlich per Permissions-Policy (allow="window-management") freigegeben sein.
Das einfache window.screen-Objekt (Typ Screen) hat keine Eigenschaft isInternal. Sie gibt es nur auf ScreenDetailed-Objekten.
Die Erkennung hängt vom Betriebssystem ab. Bei Desktop-PCs ohne eingebautes Display ist isInternal für alle Bildschirme false. Plane also einen Fallback ein.
Datenschutz: Die Angaben zu den Bildschirmen lassen sich für Browser-Fingerprinting nutzen. Deshalb verlangt der Browser die ausdrückliche Zustimmung des Nutzers.

Siehe auch

ResizeObserverSize.inlineSize ScreenDetailed.isPrimary ScreenDetailed.label ScreenDetailed.availLeft ScreenDetailed.availTop