RestrictionTarget — Schnittstelle · JavaScript-Referenz

Signatur

interface RestrictionTarget

Beschreibung

RestrictionTarget gehört zur Element Capture API, einer Erweiterung der Screen Capture API. Eine Instanz steht für ein bestimmtes DOM-Element. Man erzeugt sie nicht mit einem Konstruktor, sondern über die statische Methode RestrictionTarget.fromElement(element). Diese gibt ein Promise zurück, das mit dem RestrictionTarget erfüllt wird.

Übergibt man das Ziel an MediaStreamTrack.prototype.restrictTo() einer Videospur, die den aktuellen Tab aufzeichnet (Self-Capture über navigator.mediaDevices.getDisplayMedia()), enthält die Spur nur noch das gerenderte Element und seine Nachfahren. Anders als beim Zuschneiden per CropTarget (Region Capture) werden Inhalte, die das Element überdecken oder darunter liegen, nicht mit aufgezeichnet. Das gilt etwa für Pop-ups, Benachrichtigungen oder überlagernde Elemente. Das Ergebnis folgt dem Element auch, wenn es sich verschiebt oder durch Scrollen teilweise nicht sichtbar ist.

Typische Einsatzfälle sind Videokonferenz-Apps, die nur ein eingebettetes Dokument, eine Präsentation oder ein <iframe> teilen wollen, ohne private Bedienelemente oder Chat-Fenster mitzuübertragen. RestrictionTarget-Instanzen sind serialisierbar. Man kann sie also per postMessage() an ein anderes Dokument desselben Tabs schicken, etwa aus einem <iframe> an die Hauptseite, die die Aufnahme steuert.

Das Interface hat keine Instanz-Eigenschaften oder Instanz-Methoden. Sein einziger Zweck ist, als undurchsichtiger Verweis auf ein Element zu dienen.

Parameter

Name	Typ	Default	Beschreibung
$element Pflicht	Element		Parameter von `RestrictionTarget.fromElement()`: das Element, auf das die Aufnahme später beschränkt werden soll.

Rückgabewert

Typ

Promise<RestrictionTarget>

Beschreibung

RestrictionTarget.fromElement() gibt ein Promise zurück, das mit einer neuen RestrictionTarget-Instanz für das Element erfüllt wird. Ist das Element ungeeignet oder die API nicht verfügbar, wird es abgelehnt.

Beispiele

Aufnahme des eigenen Tabs auf ein Element beschränken

const startButton = document.querySelector('#start');
const preview = document.querySelector('#preview');
const demo = document.querySelector('#demo-bereich');

startButton.addEventListener('click', async () => {
  // Ziel für das Element erzeugen
  const target = await RestrictionTarget.fromElement(demo);

  // Aktuellen Tab aufzeichnen (Self-Capture)
  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: { displaySurface: 'browser' },
    preferCurrentTab: true
  });

  const [track] = stream.getVideoTracks();
  await track.restrictTo(target);

  preview.srcObject = stream;
  console.log('Aufnahme auf #demo-bereich beschränkt');
});

Aufnahme auf #demo-bereich beschränkt

Unterstützung prüfen und Beschränkung wieder aufheben

const supportsElementCapture = () =>
  'RestrictionTarget' in globalThis &&
  typeof RestrictionTarget.fromElement === 'function';

const toggleRestriction = async (track, element, aktiv) => {
  if (!supportsElementCapture()) {
    console.warn('Element Capture wird nicht unterstützt');
    return;
  }
  if (aktiv) {
    const target = await RestrictionTarget.fromElement(element);
    await track.restrictTo(target);
  } else {
    // null hebt die Beschränkung auf -> ganzer Tab
    await track.restrictTo(null);
  }
  console.log(`Beschränkung ${aktiv ? 'aktiv' : 'aufgehoben'}`);
};

Beschränkung aktiv

RestrictionTarget aus einem iframe an die Hauptseite senden

// Im iframe (gleicher Tab):
const player = document.querySelector('#player');
const target = await RestrictionTarget.fromElement(player);
window.parent.postMessage({ type: 'restriction-target', target }, 'https://app.example.com');

// In der Hauptseite, die die Aufnahme besitzt:
window.addEventListener('message', async (event) => {
  if (event.origin !== 'https://embed.example.com') return;
  if (event.data?.type !== 'restriction-target') return;
  await captureTrack.restrictTo(event.data.target);
  console.log('Aufnahme auf Player im iframe beschränkt');
});

Aufnahme auf Player im iframe beschränkt

// Wichtig · Fallstricke

Kompatibilität: Bisher nur in Chromium-Browsern ab Version 132 (Desktop). Firefox und Safari unterstützen die API nicht, deshalb immer mit 'RestrictionTarget' in globalThis prüfen. Nur in sicheren Kontexten (HTTPS) verfügbar.
Nur Self-Capture: restrictTo() funktioniert nur bei Videospuren, die den Tab aufzeichnen, in dem das Element liegt. Bei Fenster- oder Bildschirmaufnahmen wird das Promise abgelehnt.
Anforderungen an das Element: Damit tatsächlich Frames erzeugt werden, muss das Element beim Rendern einen eigenen Stapelkontext bilden (z. B. über isolation: isolate), in 3D abgeflacht sein und genau ein Box-Fragment haben. Ist das nicht erfüllt, liefert die Spur keine neuen Frames, es gibt aber keinen Fehler.
Unterschied zu CropTarget: Region Capture schneidet nur ein Rechteck aus und zeigt überdeckende Inhalte mit an. Element Capture zeigt nur das Element selbst.
Datenschutz: Die Beschränkung ist keine Sicherheitsgrenze gegenüber dem Nutzer. Die Aufnahmeerlaubnis gilt weiterhin für den ganzen Tab, und restrictTo(null) hebt die Beschränkung jederzeit auf. Beim Empfangen per postMessage immer event.origin prüfen.
Wird der Stream geklont (track.clone()), übernimmt der Klon die aktuelle Beschränkung. Spätere Änderungen gelten aber nur für die jeweilige Spur.

Siehe auch

MediaTrackConstraints AbstractRange CropTarget EventTarget CSSFunctionRule