Signatur
Beschreibung
Die Eigenschaft displaySurface gehört zum Wörterbuch MediaTrackSupportedConstraints, das navigator.mediaDevices.getSupportedConstraints() zurückgibt. Ist sie vorhanden und hat den Wert true, versteht der Benutzeragent die Einschränkung displaySurface. Fehlt sie, wird die Einschränkung nicht unterstützt. Den Wert false gibt es in der Praxis nicht.
Über die Einschränkung displaySurface legt man fest, welche Art von Bildschirmoberfläche bei einer Bildschirmfreigabe mit getDisplayMedia() bevorzugt werden soll: "monitor" (ganzer Bildschirm), "window" (einzelnes Anwendungsfenster) oder "browser" (Browser-Tab). Liest man die Einstellungen eines laufenden Tracks mit MediaStreamTrack.getSettings() aus, erfährt man außerdem, welche Oberfläche der Nutzer tatsächlich gewählt hat.
Die Eigenschaft ist gedacht für die Funktionserkennung. Bevor man displaySurface als Hinweis an getDisplayMedia() übergibt oder in der Oberfläche anzeigt (z. B. „Sie teilen gerade einen Tab“), sollte man prüfen, ob der Browser die Einschränkung überhaupt kennt.
Rückgabewert
true, wenn die Einschränkung displaySurface unterstützt wird. Wird sie nicht unterstützt, fehlt die Eigenschaft (undefined).Beispiele
Unterstützung prüfen
const supported = navigator.mediaDevices.getSupportedConstraints();
if (supported.displaySurface) {
console.log('displaySurface wird unterstützt');
} else {
console.log('displaySurface wird nicht unterstützt');
}Browser-Tab als bevorzugte Freigabe vorschlagen
const startTabShare = async () => {
const { displaySurface } = navigator.mediaDevices.getSupportedConstraints();
const videoConstraints = displaySurface
? { displaySurface: 'browser' } // nur ein Hinweis, der Nutzer entscheidet selbst
: true;
const stream = await navigator.mediaDevices.getDisplayMedia({
video: videoConstraints,
audio: false
});
document.querySelector('video').srcObject = stream;
return stream;
};
document.querySelector('#share').addEventListener('click', () => {
startTabShare().catch((err) => console.error('Freigabe abgebrochen:', err.name));
});Tatsächlich gewählte Oberfläche auswerten
const describeShare = async () => {
const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
const [track] = stream.getVideoTracks();
if (!navigator.mediaDevices.getSupportedConstraints().displaySurface) {
return 'Unbekannte Oberfläche';
}
const labels = { monitor: 'ganzer Bildschirm', window: 'Fenster', browser: 'Browser-Tab' };
const { displaySurface } = track.getSettings();
return `Sie teilen: ${labels[displaySurface] ?? displaySurface}`;
};
describeShare().then(console.log);// Wichtig · Fallstricke
- Nur ein Hinweis: Die Einschränkung
displaySurfaceist beigetDisplayMedia()lediglich eine Vorgabe dafür, welche Option im Auswahldialog vorausgewählt wird. Der Nutzer kann trotzdem jede andere Oberfläche wählen. Werte wieexactodermin/maxsind nicht erlaubt und führen zu einemTypeError. - Das Ergebnis immer prüfen: Die tatsächlich geteilte Oberfläche erfährt man nur über
track.getSettings().displaySurface. Auf die übergebene Vorgabe sollte man sich nicht verlassen. - Fehlt statt
false: Wird die Einschränkung nicht unterstützt, fehlt die Eigenschaft einfach. Deshalb auf Wahrheitswert prüfen (if (supported.displaySurface)) und nicht mit=== falsevergleichen. - Browser-Kompatibilität: Chromium-Browser werten die Vorgabe seit Version 107 im Auswahldialog aus. Firefox und Safari melden die Unterstützung zwar, liefern den Wert aber teils nur in
getSettings()und übergehen die Vorgabe im Dialog.getDisplayMedia()funktioniert nur in sicheren Kontexten (HTTPS) und muss durch eine Nutzeraktion ausgelöst werden. Auf Mobilgeräten ist es weitgehend nicht verfügbar.