BrowserCaptureMediaStreamTrack.restrictTo() — Methode · JavaScript-Referenz

Signatur

BrowserCaptureMediaStreamTrack.prototype.restrictTo(restrictionTarget)

Beschreibung

restrictTo() gehört zur Element Capture API. Die Methode wirkt auf einen Video-Track, den man über navigator.mediaDevices.getDisplayMedia() vom aktuellen Tab aufgenommen hat (Selbstaufnahme). Danach enthält der Track nur noch das Ziel-Element und seine Nachkommen. Alles, was davor liegt oder es verdeckt, etwa Overlays, Pop-ups oder benachbarte Elemente, ist nicht mehr zu sehen.

Das Ziel wird nicht direkt als Element übergeben. Man übergibt ein RestrictionTarget, das man vorher mit RestrictionTarget.fromElement(element) erzeugt. Das Ziel lässt sich also auch in einem anderen Dokument erstellen, etwa in einem <iframe>, und per postMessage() weitergeben.

Anders als bei cropTo() aus der Region Capture API wird hier nicht nur ein Rechteck ausgeschnitten. Aufgenommen wird der tatsächliche Inhalt des Elements, auch wenn es verschoben oder verdeckt wird. Typische Einsatzfälle sind Videokonferenz-Apps, die nur eine eingebettete Präsentation oder einen Editor teilen sollen, ohne private Chat-Bereiche zu zeigen.

Übergibt man null, wird die Beschränkung aufgehoben und der ganze Tab wieder aufgenommen. Das zurückgegebene Promise wird erfüllt, sobald die Änderung angewendet wurde. Die folgenden Frames sind dann schon beschränkt.

Parameter

Name	Typ	Default	Beschreibung
$restrictionTarget Pflicht	RestrictionTarget \| null		Ein mit `RestrictionTarget.fromElement()` erzeugtes Ziel. `null` hebt eine bestehende Beschränkung auf.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das erfüllt wird, wenn die Beschränkung angewendet (oder aufgehoben) wurde. Es wird mit einer DOMException abgelehnt, z. B. mit NotSupportedError, wenn der Track keine Selbstaufnahme des aktuellen Tabs ist, oder mit NotFoundError, wenn das Ziel nicht existiert.

Beispiele

Nur ein Element des eigenen Tabs teilen

const shareButton = document.querySelector('#share');
const demoArea = document.querySelector('#demo-area');

shareButton.addEventListener('click', async () => {
  // Selbstaufnahme des aktuellen Tabs anfordern
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    preferCurrentTab: true
  });
  const [track] = stream.getVideoTracks();

  if (!('restrictTo' in track)) {
    console.warn('Element Capture wird nicht unterstützt');
    return;
  }

  const target = await RestrictionTarget.fromElement(demoArea);
  await track.restrictTo(target);

  document.querySelector('video#preview').srcObject = stream;
  console.log('Nur #demo-area wird geteilt');
});

Nur #demo-area wird geteilt

Beschränkung wieder aufheben

const toggleRestriction = async (track, target, restricted) => {
  // null hebt die Beschränkung auf, dann wird der ganze Tab aufgenommen
  await track.restrictTo(restricted ? target : null);
  console.log(restricted ? 'Beschränkt' : 'Ganzer Tab');
};

// Beispielaufruf, nachdem track und target existieren:
// await toggleRestriction(track, target, false);

Ganzer Tab

Fehlerbehandlung bei Nicht-Selbstaufnahme

const restrictSafely = async (track, element) => {
  try {
    const target = await RestrictionTarget.fromElement(element);
    await track.restrictTo(target);
    return true;
  } catch (err) {
    // z. B. NotSupportedError, wenn ein anderer Tab oder Bildschirm gewählt wurde
    console.error(`${err.name}: ${err.message}`);
    return false;
  }
};

NotSupportedError: ... (wenn nicht der aktuelle Tab aufgenommen wird)

// Wichtig · Fallstricke

Nur bei Selbstaufnahme: Die Methode funktioniert nur, wenn der Nutzer im Auswahldialog den aktuellen Tab ausgewählt hat. Mit preferCurrentTab: true schlägt man ihm diesen Tab vor. Bei einem anderen Tab, einem Fenster oder dem ganzen Bildschirm wird das Promise abgelehnt.
Anforderungen an das Element: Das Ziel muss einen eigenen Stapelkontext (stacking context) bilden und darf nicht Teil eines 3D-Kontexts sein. Typische Lösung ist isolation: isolate per CSS, gesetzt über ein Stylesheet. Solange das Element diese Bedingungen nicht erfüllt, zum Beispiel weil es versteckt oder nicht gerendert ist, liefert der Track keine neuen Frames. Einen Fehler gibt es dabei nicht.
Klone: Hat der Track Klone (track.clone()), kann der Aufruf abgelehnt werden. Rufe restrictTo() daher vor dem Klonen auf.
Pro Track ist immer nur eine Beschränkung aktiv. Die Element Capture API (restrictTo()) und die Region Capture API (cropTo()) lassen sich zwar kombinieren, aber der Browser-Support ist unterschiedlich.
Browser-Unterstützung: Bisher nur in Chromium-Browsern auf dem Desktop (Chrome/Edge ab 132). Prüfe die Unterstützung mit 'restrictTo' in track oder typeof RestrictionTarget !== 'undefined'. Die API ist nur in einem sicheren Kontext (HTTPS) verfügbar.
Datenschutz: Die Beschränkung verhindert nicht, dass Inhalte innerhalb des Elements geteilt werden. Sensible Daten dürfen also nicht im Ziel-Element oder seinen Nachkommen liegen.

Siehe auch

BrowserCaptureMediaStreamTrack.clone() BrowserCaptureMediaStreamTrack.cropTo() CanvasCaptureMediaStreamTrack.requestFrame() new MediaStreamTrackGenerator() MediaStreamTrack.getSettings()