CropTarget.fromElement() — Methode · JavaScript-Referenz

Signatur

CropTarget.fromElement(element)

Beschreibung

Die statische Methode CropTarget.fromElement() gehört zur Region Capture API. Sie nimmt ein Element des aktuellen Dokuments entgegen und liefert ein Promise, das sich zu einem CropTarget auflöst. Dieses Objekt ist ein undurchsichtiges Token: Es identifiziert das Element, verrät aber selbst keine Informationen über dessen Inhalt oder Position.

Gebraucht wird die Methode zusammen mit navigator.mediaDevices.getDisplayMedia(). Wenn ein Nutzer den eigenen Tab teilt, lässt sich die entstandene Videospur mit MediaStreamTrack.cropTo(cropTarget) auf den sichtbaren Bereich des Elements zuschneiden. Typische Anwendungsfälle sind Videokonferenz-Web-Apps, die nur eine Präsentationsfläche und nicht die eigene Bedienoberfläche übertragen sollen, oder Editoren, die nur die Zeichenfläche streamen.

Weil ein CropTarget serialisierbar ist, kann es per postMessage() an andere Dokumente derselben Tab-Aufnahme weitergegeben werden, zum Beispiel von einem eingebetteten <iframe> an die übergeordnete Seite, die die Aufnahme steuert. Der Zuschnitt folgt dem Element dynamisch: Ändert es Größe oder Position, passt sich der Ausschnitt an.

Parameter

Name	Typ	Default	Beschreibung
$element Pflicht	Element		Das DOM-Element, auf dessen Begrenzungsrechteck die Videospur zugeschnitten werden soll. Unterstützt werden u. a. `<div>`, `<iframe>`, `<video>` und `<canvas>`.

Rückgabewert

Typ

Promise<CropTarget>

Beschreibung

Ein Promise, das sich zu einem CropTarget auflöst. Es wird mit einem NotSupportedError (DOMException) abgelehnt, wenn das Element nicht unterstützt wird.

Beispiele

Eigenen Tab aufnehmen und auf ein Element zuschneiden

const startCroppedCapture = async () => {
  const area = document.querySelector('#praesentation');

  // CropTarget erzeugen (vor oder nach getDisplayMedia möglich)
  const cropTarget = await CropTarget.fromElement(area);

  const stream = await navigator.mediaDevices.getDisplayMedia({
    video: true,
    preferCurrentTab: true // nur Chromium: aktuellen Tab vorschlagen
  });

  const [track] = stream.getVideoTracks();
  await track.cropTo(cropTarget);

  document.querySelector('#vorschau').srcObject = stream;
  console.log('Zuschnitt aktiv');
};

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

Zuschnitt aktiv

Feature-Erkennung mit Fallback

const supportsRegionCapture =
  'CropTarget' in window &&
  typeof CropTarget.fromElement === 'function';

const cropIfPossible = async (track, element) => {
  if (!supportsRegionCapture) {
    console.warn('Region Capture nicht verfügbar – ganzer Tab wird geteilt.');
    return false;
  }
  try {
    const target = await CropTarget.fromElement(element);
    await track.cropTo(target);
    return true;
  } catch (err) {
    console.error(`Zuschnitt fehlgeschlagen: ${err.name}`);
    return false;
  }
};

Region Capture nicht verfügbar – ganzer Tab wird geteilt. (z. B. in Firefox)

CropTarget aus einem iframe an die Elternseite senden

// Im iframe (gleicher Tab):
const sendCropTarget = async () => {
  const target = await CropTarget.fromElement(document.querySelector('#spielfeld'));
  window.parent.postMessage({ type: 'crop-target', target }, 'https://app.example.com');
};
sendCropTarget();

// In der Elternseite:
let videoTrack; // zuvor per getDisplayMedia() gesetzt
window.addEventListener('message', async (event) => {
  if (event.origin !== 'https://iframe.example.com') return;
  if (event.data?.type === 'crop-target' && videoTrack) {
    await videoTrack.cropTo(event.data.target);
    console.log('Auf iframe-Inhalt zugeschnitten');
  }
});

Auf iframe-Inhalt zugeschnitten

// Wichtig · Fallstricke

Kompatibilität: Nur in Chromium-basierten Desktop-Browsern (Chrome/Edge ab 104). Firefox und Safari unterstützen die API nicht – immer per Feature-Erkennung prüfen.
Nur Tab-Aufnahmen des eigenen Tabs: cropTo() funktioniert nur, wenn die Spur von getDisplayMedia() stammt und der Tab aufgenommen wird, in dem das Element liegt. Bei Fenster- oder Bildschirmaufnahmen schlägt der Aufruf fehl.
Nicht mit Element Capture verwechseln: Der Zuschnitt ist rein geometrisch. Überlagernde Elemente (Popups, Tooltips, Benachrichtigungen) über dem Bereich werden mit übertragen. Soll nur das Element selbst aufgenommen werden, ist RestrictionTarget (Element Capture API) die passende Wahl.
Ist das Element nicht sichtbar oder aus dem DOM entfernt, liefert die Spur keine neuen Frames. Mit track.cropTo(undefined) wird der Zuschnitt aufgehoben.
Sicherheit: Beim Empfang eines CropTarget per postMessage() immer event.origin prüfen und beim Senden eine konkrete Ziel-Origin statt '*' angeben.
Die Methode ist asynchron. Den Aufruf ohne await zu verwenden, ist ein häufiger Fehler.

Siehe auch

new HTMLGeolocationElement() RestrictionTarget.fromElement() DOMRect.fromRect() Sanitizer.allowElement() console.profileEnd()