RestrictionTarget.fromElement() — Methode · JavaScript-Referenz

Signatur

RestrictionTarget.fromElement(element)

Beschreibung

Die statische Methode RestrictionTarget.fromElement() gehört zur Element Capture API. Sie nimmt ein DOM-Element entgegen und liefert ein Promise, das zu einem RestrictionTarget aufgelöst wird. Dieses Objekt übergibt man anschließend an MediaStreamTrack.restrictTo() (genauer: BrowserCaptureMediaStreamTrack.prototype.restrictTo()). Ab dann enthält die Videospur nur noch das Element samt seiner Nachfahren – alles, was im Tab davor oder darüber liegt (Overlays, Pop-ups, andere Inhalte), wird nicht mit aufgenommen.

Typischer Einsatzfall ist die Selbstaufnahme des aktuellen Tabs: Eine Web-App (z. B. ein Videokonferenz-Tool oder ein Präsentationseditor) nimmt mit navigator.mediaDevices.getDisplayMedia({ preferCurrentTab: true }) den eigenen Tab auf und möchte nur einen bestimmten Bereich – etwa eine Folie oder ein <iframe> – teilen, ohne private Chat-Nachrichten oder Bedienelemente preiszugeben.

Im Unterschied zum älteren CropTarget (Region Capture), das nur einen rechteckigen Bildschirmausschnitt zuschneidet, nimmt RestrictionTarget tatsächlich nur den Render-Baum des Elements auf. Überlagernde Inhalte werden also ausgeblendet statt mitgeschnitten.

Damit das Element beim Aufnehmen berücksichtigt wird, muss es zum Zeitpunkt der Aufnahme geeignet sein: Es muss einen eigenen Stapelkontext bilden (z. B. über isolation: isolate), flach gerendert werden (transform-style: flat) und tatsächlich dargestellt werden (nicht display: none). Ist das nicht erfüllt, liefert die Spur einfach keine neuen Frames, bis das Element wieder geeignet ist.

Parameter

Name	Typ	Default	Beschreibung
$element Pflicht	Element		Das DOM-Element, auf das die Aufnahme beschränkt werden soll. Die Aufnahme umfasst das Element und alle seine Nachfahren.

Rückgabewert

Typ

Promise<RestrictionTarget>

Beschreibung

Ein Promise, das zu einem RestrictionTarget aufgelöst wird. Das Objekt ist serialisierbar und kann per postMessage() an andere Dokumente (z. B. ein übergeordnetes Fenster) weitergereicht werden. Wird mit NotSupportedError abgelehnt, wenn die Umgebung das Feature nicht unterstützt.

Beispiele

Tab-Aufnahme auf eine Folie beschränken

// HTML: <div id="folie" style="isolation: isolate; transform-style: flat">…</div>
const startFolienFreigabe = async () => {
  if (!('RestrictionTarget' in self)) {
    console.warn('Element Capture wird nicht unterstützt');
    return;
  }

  const folie = document.querySelector('#folie');
  const target = await RestrictionTarget.fromElement(folie);

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

  await track.restrictTo(target);
  document.querySelector('video').srcObject = stream;
  console.log('Aufnahme auf Folie beschränkt');
};

document.querySelector('#teilen').addEventListener('click', startFolienFreigabe);

Aufnahme auf Folie beschränkt

Beschränkung wieder aufheben

const toggleBeschraenkung = async (track, target, aktiv) => {
  // null entfernt die Beschränkung – der ganze Tab wird wieder aufgenommen
  await track.restrictTo(aktiv ? target : null);
  console.log(aktiv ? 'Nur Element' : 'Ganzer Tab');
};

// Beispielnutzung nach erfolgreicher Aufnahme:
// await toggleBeschraenkung(track, target, false);

Ganzer Tab

RestrictionTarget aus einem iframe an das Elternfenster senden

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

// Im Elternfenster (das die Aufnahme besitzt):
window.addEventListener('message', async (event) => {
  if (event.origin !== 'https://app.example.com') return;
  if (event.data?.type === 'restriction-target') {
    await track.restrictTo(event.data.target);
  }
});

// Wichtig · Fallstricke

Browser-Kompatibilität: Bisher nur in Chromium-basierten Desktop-Browsern (ab Chrome 132). Firefox und Safari unterstützen die Methode nicht. Vorher per 'RestrictionTarget' in self prüfen.
restrictTo() funktioniert nur bei Spuren aus einer Selbstaufnahme des aktuellen Tabs. Bei Fenster- oder Bildschirmaufnahmen oder bei anderen Tabs wird das Promise abgelehnt.
Das Element muss einen eigenen Stapelkontext bilden (isolation: isolate) und flach gerendert werden (transform-style: flat). Sonst liefert die Spur ohne Fehlermeldung einfach keine Frames mehr. Das ist ein häufiger Grund für ein „eingefrorenes“ Video.
Der Aufruf von fromElement() selbst verursacht kaum Aufwand. Es ist sinnvoll, das Ziel schon vor dem Start der Aufnahme zu erzeugen, damit restrictTo() danach ohne Verzögerung greift.
Datenschutz: Die Beschränkung dient der Privatsphäre, ist aber keine Sicherheitsgrenze. Bis restrictTo() aufgelöst ist, können kurz Frames des gesamten Tabs übertragen werden. Deshalb erst nach dem Auflösen senden. Beim Empfang per postMessage() immer event.origin prüfen.
Nicht verwechseln mit CropTarget.fromElement(): Dort wird nur zugeschnitten, und überlagernde Inhalte bleiben sichtbar.

Siehe auch

CropTarget.fromElement() new SpeechSynthesisErrorEvent() Selection.deleteFromDocument() SVGAnimationElement.endElement() Sanitizer.allowElement()