Signatur
Beschreibung
CropTarget gehört zur Region Capture API, einer Erweiterung der Screen Capture API. Ein CropTarget ist ein nicht durchschaubarer Verweis auf ein Element im aktuellen Dokument. Übergibt man ihn an BrowserCaptureMediaStreamTrack.cropTo(), enthält ein Videotrack aus der Aufnahme des eigenen Tabs nur noch den Bereich, den dieses Element auf dem Bildschirm einnimmt. Alles andere wird weggeschnitten.
Typische Einsatzfälle sind Web-Videokonferenzen, die neben einer eingebetteten Präsentation (etwa einem <iframe>) laufen und nur diese Präsentation übertragen sollen. Auch Aufzeichnungen einzelner Bereiche einer Seite wie Canvas, Editor oder Vorschau gehören dazu, ohne dass Bedienelemente oder private Inhalte im Bild landen.
Die Schnittstelle hat keinen öffentlichen Konstruktor. Instanzen erzeugt man nur mit der statischen, asynchronen Methode CropTarget.fromElement(element). Sie gibt ein Promise<CropTarget> zurück. Der Zuschnitt folgt dem Element auch dann, wenn es sich verschiebt oder seine Größe ändert. Ein CropTarget ist serialisierbar und lässt sich deshalb per postMessage() an ein anderes Dokument im selben Tab schicken, zum Beispiel an ein <iframe>, das die Aufnahme verwaltet.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $element Pflicht | Element | Parameter von CropTarget.fromElement(): das Element, auf dessen sichtbaren Bereich die Aufnahme zugeschnitten werden soll. Ältere Chrome-Versionen akzeptieren nur <div> und <iframe>. |
Rückgabewert
CropTarget.fromElement() gibt ein Promise zurück, das mit einer CropTarget-Instanz für das Element erfüllt wird. Das Promise wird abgelehnt, wenn das Element nicht geeignet ist.Beispiele
Eigenen Tab aufnehmen und auf ein Element zuschneiden
const startCroppedCapture = async () => {
if (!('CropTarget' in self && 'fromElement' in CropTarget)) {
console.warn('Region Capture wird nicht unterstützt');
return null;
}
const area = document.querySelector('#praesentation');
const cropTarget = await CropTarget.fromElement(area);
// Nutzer um Freigabe des aktuellen Tabs bitten
const stream = await navigator.mediaDevices.getDisplayMedia({
video: true,
preferCurrentTab: true
});
const [track] = stream.getVideoTracks();
await track.cropTo(cropTarget);
document.querySelector('video#vorschau').srcObject = stream;
console.log('Zuschnitt aktiv');
return track;
};
document.querySelector('#start').addEventListener('click', startCroppedCapture);Zuschnitt zur Laufzeit wechseln oder aufheben
// track: Videotrack aus getDisplayMedia() (eigener Tab)
const switchCrop = async (track, selector) => {
if (selector === null) {
await track.cropTo(null); // Zuschnitt aufheben, wieder ganzer Tab
console.log('Ganzer Tab wird übertragen');
return;
}
const target = await CropTarget.fromElement(document.querySelector(selector));
await track.cropTo(target);
console.log(`Zuschnitt auf ${selector}`);
};
// Beispielaufrufe:
// await switchCrop(track, '#editor');
// await switchCrop(track, null);CropTarget per postMessage an ein iframe übergeben
// Im Hauptdokument: Ziel erzeugen und an das Konferenz-iframe schicken
const iframe = document.querySelector('iframe#konferenz');
const cropTarget = await CropTarget.fromElement(document.querySelector('#folien'));
iframe.contentWindow.postMessage({ cropTarget }, 'https://konferenz.example');
// Im iframe (https://konferenz.example):
window.addEventListener('message', async (event) => {
if (event.origin !== 'https://parent.example') return;
const stream = await navigator.mediaDevices.getDisplayMedia({ preferCurrentTab: true });
const [track] = stream.getVideoTracks();
await track.cropTo(event.data.cropTarget);
console.log('Folienbereich wird übertragen');
});// Wichtig · Fallstricke
- Kompatibilität: Nur Chromium-Browser ab Version 104 auf dem Desktop unterstützen die API. Firefox und Safari kennen sie nicht. Vor der Nutzung sollte man deshalb prüfen, ob sie vorhanden ist (
'CropTarget' in self). - Nur der eigene Tab:
cropTo()funktioniert nur, wenn der aufgenommene Tab derjenige ist, in dem das Element liegt. Bei Fenstern, Bildschirmen oder fremden Tabs wird das Promise abgelehnt. - Die API braucht einen sicheren Kontext (HTTPS).
getDisplayMedia()braucht außerdem eine Nutzeraktion, etwa einen Klick. - Zuschnitt heißt nicht Ausblenden: Alles, was das Element optisch überdeckt, zum Beispiel Pop-ups, Tooltips oder überlappende Elemente, erscheint trotzdem im Bild. Wer nur das Element selbst ohne Überlagerungen aufnehmen will, nutzt die neuere Element Capture API mit
RestrictionTarget(Chrome 132+). - Wird das Element entfernt oder unsichtbar, liefert der Track keine neuen Bilder mehr. Er wird dabei nicht beendet.
- Beim Senden über
postMessage()immerevent.originprüfen und eine konkrete Ziel-Herkunft angeben. Der Empfang funktioniert nur innerhalb desselben Tabs.