ScreenDetailed.devicePixelRatio — Eigenschaft · JavaScript-Referenz

Signatur

ScreenDetailed.devicePixelRatio

Beschreibung

Die Eigenschaft devicePixelRatio eines ScreenDetailed-Objekts gibt an, wie viele physische Gerätepixel auf ein CSS-Pixel des jeweiligen Bildschirms kommen. Ein Wert von 1 steht für ein klassisches Display, 2 für ein typisches HiDPI- bzw. „Retina“-Display. Auch Zwischenwerte wie 1.25 oder 1.5 kommen oft vor, zum Beispiel bei skalierten Windows-Displays.

Anders als window.devicePixelRatio bezieht sich der Wert nicht auf den Bildschirm, auf dem das aktuelle Fenster gerade liegt. Er gilt für genau den Bildschirm, den das ScreenDetailed-Objekt beschreibt. Das braucht man in Mehrschirm-Umgebungen: Bevor eine Anwendung ein Fenster auf einem zweiten Monitor öffnet, kann sie prüfen, ob dieser Monitor hochauflösende Inhalte braucht. Das ist z. B. wichtig bei Präsentationen, Handelsplattformen oder Bildbearbeitung.

An ein ScreenDetailed-Objekt kommt man über window.getScreenDetails(). Die Methode liefert ein ScreenDetails-Objekt mit der Liste screens und dem aktuellen Bildschirm currentScreen. Dafür braucht es die Berechtigung window-management, früher window-placement genannt.

Der Wert ist nicht in jedem Fall fest. Er ändert sich, wenn Nutzer die Skalierung im Betriebssystem ändern. Auf das Ereignis change des jeweiligen ScreenDetailed-Objekts kann man reagieren und so aktuell bleiben.

Rückgabewert

Typ

number

Beschreibung

Gleitkommazahl größer als 0, z. B. 1, 1.5 oder 2: das Verhältnis von physischen Pixeln zu CSS-Pixeln auf diesem Bildschirm. Die Eigenschaft ist schreibgeschützt.

Beispiele

Pixel-Verhältnis aller angeschlossenen Bildschirme auflisten

const listScreens = async () => {
  if (!('getScreenDetails' in window)) {
    console.log('Window Management API wird nicht unterstützt.');
    return;
  }
  // Fragt beim ersten Aufruf nach der Berechtigung "window-management"
  const details = await window.getScreenDetails();
  for (const screen of details.screens) {
    console.log(`${screen.label || 'Unbenannt'}: ${screen.devicePixelRatio}x`);
  }
};

listScreens();

Integrierter Bildschirm: 2x DELL U2720Q: 1.5x

HiDPI-Bildschirm für ein Präsentationsfenster wählen

const openOnSharpestScreen = async (url) => {
  const { screens } = await window.getScreenDetails();
  // Bildschirm mit dem höchsten Pixel-Verhältnis suchen
  const target = screens.reduce((best, s) =>
    s.devicePixelRatio > best.devicePixelRatio ? s : best
  );
  const features = [
    `left=${target.availLeft}`,
    `top=${target.availTop}`,
    `width=${target.availWidth}`,
    `height=${target.availHeight}`
  ].join(',');
  window.open(url, '_blank', features);
  return target.devicePixelRatio;
};

// Muss durch eine Nutzeraktion ausgelöst werden (Pop-up-Blocker)
document.querySelector('#present').addEventListener('click', async () => {
  const dpr = await openOnSharpestScreen('/slides.html');
  console.log(`Geöffnet auf Bildschirm mit DPR ${dpr}`);
});

Geöffnet auf Bildschirm mit DPR 2

Canvas-Auflösung an den aktuellen Bildschirm anpassen und Änderungen verfolgen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

const resizeCanvas = (dpr) => {
  const { width, height } = canvas.getBoundingClientRect();
  canvas.width = Math.round(width * dpr);
  canvas.height = Math.round(height * dpr);
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
  console.log(`Canvas auf DPR ${dpr} skaliert`);
};

const init = async () => {
  const details = await window.getScreenDetails();
  const apply = () => resizeCanvas(details.currentScreen.devicePixelRatio);
  apply();
  // Fenster wurde auf einen anderen Bildschirm verschoben
  details.addEventListener('currentscreenchange', () => {
    apply();
    // Skalierung des neuen Bildschirms wurde geändert
    details.currentScreen.onchange = apply;
  });
  details.currentScreen.onchange = apply;
};

init();

Canvas auf DPR 1.25 skaliert

// Wichtig · Fallstricke

Browser-Unterstützung: Die Eigenschaft gehört zur Window Management API. Sie ist nur in Chromium-Browsern verfügbar (Chrome/Edge ab Version 100), nicht in Firefox und Safari. Prüfe vor der Nutzung mit 'getScreenDetails' in window, ob die API vorhanden ist.
Berechtigung und sicherer Kontext: getScreenDetails() läuft nur über HTTPS und verlangt die Berechtigung window-management. Lehnt der Nutzer ab, wird das Promise mit einem NotAllowedError abgelehnt. In iframes muss die Permissions Policy window-management erlaubt sein.
Nicht mit window.devicePixelRatio verwechseln: window.devicePixelRatio berücksichtigt auch den Browser-Zoom. Der Wert von ScreenDetailed.devicePixelRatio beschreibt dagegen die Skalierung des Bildschirms selbst. Für das Rendern im aktuellen Fenster ist deshalb oft window.devicePixelRatio die passendere Größe.
Kein fester Wert: Der Wert kann gebrochen sein, z. B. 1.25, und sich zur Laufzeit ändern. Bei Canvas-Größen daher runden und auf das Ereignis change hören.
Datenschutz: Bildschirm-Details eignen sich zum Fingerprinting. Frage die Berechtigung deshalb erst an, wenn sie wirklich gebraucht wird, und idealerweise nach einer Nutzeraktion.

Siehe auch

MediaTrackSettings.screenPixelRatio ScreenDetailed.availLeft ScreenDetailed.availTop ScreenDetailed.isInternal ScreenDetailed.isPrimary