MediaTrackConstraints.logicalSurface — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.logicalSurface

Beschreibung

Die Eigenschaft logicalSurface des Wörterbuchs MediaTrackConstraints gehört zur Screen Capture API. Sie beschreibt, welche Anforderung an die gleichnamige einschränkbare Eigenschaft logicalSurface eines Video-Tracks gestellt wird. Diesen Track bekommt man von navigator.mediaDevices.getDisplayMedia().

Man unterscheidet zwei Arten von Anzeigeoberflächen:

Eine logische Oberfläche (true) ist z. B. der vollständige Inhalt eines Fensters oder Tabs. Sie kann auch Bereiche enthalten, die gerade verdeckt, außerhalb des Bildschirms oder wegen Scrollens nicht sichtbar sind.
Eine sichtbare Oberfläche (false) zeigt nur das, was tatsächlich auf dem Bildschirm zu sehen ist, etwa einen ganzen Monitor.

In der Spezifikation hat die Einschränkung den Typ ConstrainBoolean: entweder ein einfacher boolescher Wert oder ein Objekt mit exact bzw. ideal. Welcher Wert tatsächlich gilt, verrät MediaStreamTrack.getSettings().logicalSurface. Praktisch nutzt man die Eigenschaft vor allem, um nach der Auswahl durch den Nutzer die Art der Aufnahme zu prüfen oder mit applyConstraints() eine Präferenz festzulegen.

Bei Bildschirmaufnahmen entscheidet am Ende immer der Nutzer im Auswahldialog des Browsers, was aufgenommen wird. logicalSurface ist deshalb eher ein Hinweis für den Browser als eine sichere Garantie.

Parameter

Name	Typ	Default	Beschreibung
$logicalSurface	boolean \| { exact?: boolean, ideal?: boolean }		`true` verlangt bzw. bevorzugt eine logische Oberfläche (die Inhalte können teilweise unsichtbar sein), `false` eine vollständig sichtbare Oberfläche. Mit `ideal` ist es nur eine Präferenz, mit `exact` eine Pflichtvorgabe (bei `getDisplayMedia()` nicht erlaubt).

Rückgabewert

Typ

ConstrainBoolean

Beschreibung

Der gesetzte Einschränkungswert: ein boolean oder ein Objekt mit exact/ideal. Den tatsächlich verwendeten Wert liefert MediaTrackSettings.logicalSurface als boolean.

Beispiele

Unterstützung prüfen und Bildschirmaufnahme starten

const startCapture = async () => {
  const supported = navigator.mediaDevices.getSupportedConstraints();
  if (!supported.logicalSurface) {
    console.warn('logicalSurface wird von diesem Browser nicht unterstützt.');
  }

  // Bei getDisplayMedia() sind nur ideal-Werte bzw. einfache Werte erlaubt
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: { logicalSurface: true }
  });

  const [track] = stream.getVideoTracks();
  console.log('Logische Oberfläche:', track.getSettings().logicalSurface);
  return stream;
};

document.querySelector('#share').addEventListener('click', startCapture);

Logische Oberfläche: true

Art der Aufnahme auswerten und Hinweis anzeigen

const describeCapture = (track) => {
  const { displaySurface, logicalSurface } = track.getSettings();
  if (logicalSurface) {
    return `Es wird ein ${displaySurface} komplett aufgenommen – verdeckte Bereiche eingeschlossen.`;
  }
  return `Es wird nur der sichtbare Bereich (${displaySurface}) aufgenommen.`;
};

const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
console.log(describeCapture(stream.getVideoTracks()[0]));

Es wird ein window komplett aufgenommen – verdeckte Bereiche eingeschlossen.

Nachträglich mit applyConstraints() anpassen

const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
const [track] = stream.getVideoTracks();

try {
  await track.applyConstraints({ logicalSurface: { ideal: false } });
  console.log('Neue Einstellung:', track.getSettings().logicalSurface);
} catch (err) {
  // OverconstrainedError, falls die Vorgabe nicht erfüllbar ist
  console.error(err.name, err.constraint);
}

Neue Einstellung: false

// Wichtig · Fallstricke

Typ: Ältere MDN-Texte nennen hier ConstrainDOMString. Laut Screen-Capture-Spezifikation ist logicalSurface aber ein ConstrainBoolean, der Einstellungswert also ein boolean.
getDisplayMedia()-Einschränkungen: exact, min, max und advanced sind dort nicht erlaubt und führen zu einem TypeError. Pflichtvorgaben gehen höchstens später über applyConstraints().
Nutzer entscheidet: Was aufgenommen wird, wählt der Nutzer im Dialog. Die Einschränkung ändert die Auswahl oft gar nicht. Deshalb immer getSettings() auswerten.
Browser-Kompatibilität: Die Unterstützung ist uneinheitlich und in manchen Browsern gar nicht vorhanden. Vorher mit navigator.mediaDevices.getSupportedConstraints().logicalSurface prüfen.
Sicherheit: getDisplayMedia() braucht einen sicheren Kontext (HTTPS) und eine Nutzeraktion, etwa einen Klick. Logische Oberflächen können Inhalte enthalten, die der Nutzer gerade nicht sieht. Darauf sollte man in der Oberfläche hinweisen.

Siehe auch

MediaTrackConstraints.autoGainControl MediaTrackConstraints.displaySurface MediaTrackConstraints.frameRate MediaTrackConstraints.sampleRate MediaTrackConstraints.volume