MediaTrackSupportedConstraints.logicalSurface — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackSupportedConstraints.logicalSurface

Beschreibung

Die Eigenschaft logicalSurface gehört zu dem Objekt, das navigator.mediaDevices.getSupportedConstraints() zurückgibt. Ist sie true, kennt der Browser die Einschränkung logicalSurface. Fehlt sie, unterstützt der Browser die Einschränkung nicht. Den Wert false liefert die Eigenschaft in der Praxis nie: Nicht unterstützte Einschränkungen tauchen im Objekt einfach nicht auf.

Die Einschränkung selbst betrifft nur die Bildschirmaufnahme mit getDisplayMedia(). Sie gibt an, ob die aufgenommene Fläche eine logische Fläche ist. Das ist ein Bereich, der ganz oder teilweise außerhalb des sichtbaren Bildschirms liegen kann, zum Beispiel ein verdecktes Fenster oder der gesamte Inhalt eines Browser-Tabs. Ist er false, handelt es sich um eine sichtbare Fläche, etwa einen ganzen Monitor.

Prüfen Sie die Eigenschaft, bevor Sie logicalSurface in einem Constraints-Objekt verwenden oder aus MediaStreamTrack.getSettings() auslesen. So können Sie die Oberfläche anpassen, zum Beispiel mit einem Hinweis wie „Fensterinhalt wird vollständig aufgenommen“. Außerdem vermeiden Sie falsche Annahmen in Browsern ohne Unterstützung.

Rückgabewert

Typ

boolean | undefined

Beschreibung

true, wenn die Einschränkung logicalSurface unterstützt wird. Wird sie nicht unterstützt, fehlt die Eigenschaft, und der Zugriff liefert undefined.

Beispiele

Unterstützung prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

if (supported.logicalSurface) {
  console.log('logicalSurface wird unterstützt');
} else {
  console.log('logicalSurface wird nicht unterstützt');
}

logicalSurface wird unterstützt

Einstellung einer Bildschirmaufnahme auslesen

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

  if (navigator.mediaDevices.getSupportedConstraints().logicalSurface) {
    const { logicalSurface, displaySurface } = track.getSettings();
    console.log(`Fläche: ${displaySurface}, logisch: ${logicalSurface}`);
  } else {
    console.log('Keine Information über logische Flächen verfügbar');
  }
  return stream;
};

// Muss durch eine Benutzeraktion ausgelöst werden
document.querySelector('#share').addEventListener('click', startCapture);

Fläche: window, logisch: true

Alle Bildschirmaufnahme-Einschränkungen tabellarisch auflisten

const keys = ['displaySurface', 'logicalSurface', 'cursor'];
const supported = navigator.mediaDevices.getSupportedConstraints();

console.table(
  keys.map((key) => ({ constraint: key, unterstützt: Boolean(supported[key]) }))
);

┌─────────┬──────────────────┬─────────────┐ │ (index) │ constraint │ unterstützt │ │ 0 │ 'displaySurface' │ true │ │ 1 │ 'logicalSurface' │ true │ │ 2 │ 'cursor' │ false │ └─────────┴──────────────────┴─────────────┘

// Wichtig · Fallstricke

Kein false: Nicht unterstützte Einschränkungen fehlen im Objekt. Prüfen Sie deshalb auf Wahrheitswert (if (supported.logicalSurface)) und nicht mit === false.
Unterstützung heißt nicht Steuerbarkeit: Die Spezifikation verbietet, logicalSurface als Einschränkung an getDisplayMedia() zu übergeben. Solche Werte werden ignoriert oder führen zu einem TypeError. Die Wahl der Fläche trifft allein der Benutzer. Den Wert können Sie nur über getSettings() lesen.
Nur für Bildschirmaufnahmen: Bei Kamera- oder Mikrofon-Tracks aus getUserMedia() hat die Einschränkung keine Bedeutung.
Kompatibilität: Chromium-Browser und Firefox unterstützen die Eigenschaft, Safari nicht. Sie ist nur in sicheren Kontexten (HTTPS) verfügbar, weil navigator.mediaDevices sonst undefined ist.

Siehe auch

MediaTrackConstraints.logicalSurface MediaTrackConstraints.sampleRate MediaTrackSupportedConstraints.displaySurface MediaTrackSupportedConstraints.frameRate MediaTrackSupportedConstraints.sampleRate