MediaTrackConstraints.displaySurface — Eigenschaft · JavaScript-Referenz

Signatur

MediaTrackConstraints.displaySurface

Beschreibung

Die Eigenschaft displaySurface des Wörterbuchs MediaTrackConstraints gibt an, welche Art von Bildschirmoberfläche Sie bei der Bildschirmfreigabe mit navigator.mediaDevices.getDisplayMedia() bevorzugen. Mögliche Werte sind "monitor" (ganzer Bildschirm), "window" (einzelnes Anwendungsfenster) und "browser" (ein Browser-Tab).

Anders als bei getUserMedia() ist der Wert bei getDisplayMedia() nur ein Hinweis. Der Browser wählt damit zum Beispiel vor, welcher Reiter im Auswahldialog zuerst angezeigt wird. Die endgültige Entscheidung trifft immer die Person, die den Bildschirm freigibt. Die Angaben exact und min/max sind hier nicht erlaubt. Wenn Sie { exact: ... } verwenden, lehnt der Browser den Aufruf mit einem TypeError ab.

Welche Oberfläche tatsächlich gewählt wurde, lesen Sie nach der Freigabe über MediaStreamTrack.getSettings().displaySurface aus. So kann eine Anwendung ihre Oberfläche anpassen, z. B. einen Hinweis einblenden, wenn statt eines Tabs der ganze Bildschirm geteilt wird und dadurch private Inhalte sichtbar werden könnten.

Parameter

Name	Typ	Default	Beschreibung
$displaySurface	string \| string[] \| { ideal: string \| string[] }		Bevorzugte Oberfläche: `"monitor"`, `"window"` oder `"browser"`. Sie können einen einfachen String, ein Array oder ein Objekt mit `ideal` angeben. `exact` ist bei `getDisplayMedia()` nicht erlaubt.

Rückgabewert

Typ

ConstrainDOMString

Beschreibung

Der hinterlegte Wert der Einschränkung, also ein String, ein String-Array oder ein Objekt mit ideal.

Beispiele

Tab-Freigabe im Auswahldialog vorschlagen

const shareTab = async () => {
  try {
    const stream = await navigator.mediaDevices.getDisplayMedia({
      video: { displaySurface: 'browser' },
      audio: true
    });
    document.querySelector('video').srcObject = stream;
  } catch (err) {
    console.error('Freigabe abgebrochen:', err.name);
  }
};

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

Tatsächlich gewählte Oberfläche prüfen

const startCapture = async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: { displaySurface: { ideal: 'window' } }
  });
  const [track] = stream.getVideoTracks();
  const { displaySurface } = track.getSettings();
  console.log('Gewählt:', displaySurface);

  if (displaySurface === 'monitor') {
    console.warn('Achtung: Der gesamte Bildschirm wird geteilt.');
  }
  return stream;
};

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

Gewählt: monitor Achtung: Der gesamte Bildschirm wird geteilt.

Unterstützung per Feature-Erkennung prüfen

const supported = navigator.mediaDevices.getSupportedConstraints();

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

displaySurface wird unterstützt

// Wichtig · Fallstricke

Nur ein Hinweis: Den Wert vorzugeben garantiert nicht, dass diese Oberfläche auch gewählt wird. Prüfen Sie das Ergebnis deshalb immer mit getSettings().
{ exact: 'monitor' }, min und max führen bei getDisplayMedia() zu einem TypeError.
Für getDisplayMedia() brauchen Sie eine Nutzeraktion (z. B. einen Klick) und einen sicheren Kontext (HTTPS).
Chromium-Browser nutzen den Wert, um den passenden Reiter im Auswahldialog vorzuwählen. Firefox und Safari berücksichtigen ihn kaum oder gar nicht. Auf Mobilgeräten ist getDisplayMedia() meist nicht verfügbar.
Datenschutz: Wenn der ganze Bildschirm ("monitor") geteilt wird, können Benachrichtigungen und andere Fenster sichtbar werden. Mit monitorTypeSurfaces: "exclude" (nur Chromium) können Sie diese Option im Auswahldialog ausblenden.

Siehe auch

MediaSource.canConstructInDedicatedWorker MediaStreamTrackProcessor.discardedFrames MediaTrackConstraints.logicalSurface MediaTrackConstraints.sampleRate MediaTrackConstraints.frameRate