Signatur
Beschreibung
Die schreibgeschützte Eigenschaft sourceCharPosition des Interfaces PerformanceScriptTiming gibt eine Zahl zurück. Sie steht für die Zeichenposition (Offset ab Dateianfang) des Skript-Einstiegspunkts, der zu einem Long Animation Frame (LoAF) beigetragen hat. Zusammen mit sourceURL und sourceFunctionName lässt sich damit die Stelle im Code finden, die das Rendering blockiert hat.
PerformanceScriptTiming-Objekte bekommen Sie nicht direkt. Sie liegen im Array scripts eines PerformanceLongAnimationFrameTiming-Eintrags, den ein PerformanceObserver mit dem Typ "long-animation-frame" liefert. Aufgenommen werden nur Skripte, die mindestens 5 ms lang liefen.
Das ist vor allem beim Real User Monitoring (RUM) nützlich: Mit der Kombination aus URL, Funktionsname und Zeichenposition kann man einen Engpass auch in minifiziertem Code genau zuordnen, zum Beispiel über Source Maps. Kann der Browser die Position nicht bestimmen, liefert die Eigenschaft -1.
Rückgabewert
-1, wenn die Position unbekannt ist.Beispiele
Zeichenpositionen blockierender Skripte ausgeben
const observer = new PerformanceObserver((list) => {
for (const frame of list.getEntries()) {
for (const script of frame.scripts) {
console.log(
`${script.sourceURL} – ${script.sourceFunctionName || '(anonym)'} @ Zeichen ${script.sourceCharPosition}`,
`Dauer: ${Math.round(script.duration)} ms`
);
}
}
});
observer.observe({ type: 'long-animation-frame', buffered: true });Engpässe für RUM zusammenfassen und senden
const hotspots = new Map();
new PerformanceObserver((list) => {
for (const frame of list.getEntries()) {
for (const { sourceURL, sourceCharPosition, duration } of frame.scripts) {
if (sourceCharPosition < 0) continue; // Position unbekannt
const key = `${sourceURL}:${sourceCharPosition}`;
hotspots.set(key, (hotspots.get(key) ?? 0) + duration);
}
}
}).observe({ type: 'long-animation-frame', buffered: true });
addEventListener('visibilitychange', () => {
if (document.visibilityState === 'hidden' && hotspots.size) {
navigator.sendBeacon('/rum/loaf', JSON.stringify([...hotspots]));
}
});Unterstützung prüfen
const supported =
typeof PerformanceObserver !== 'undefined' &&
PerformanceObserver.supportedEntryTypes.includes('long-animation-frame');
console.log(supported ? 'LoAF wird unterstützt' : 'LoAF nicht verfügbar');// Wichtig · Fallstricke
- Kompatibilität: Die Eigenschaft ist experimentell und nur in Chromium-Browsern verfügbar (ab Chrome/Edge 123). Prüfen Sie die Unterstützung vor der Nutzung über
PerformanceObserver.supportedEntryTypes. - Der Wert ist ein Zeichen-Offset und keine Zeilen- oder Spaltennummer. Wenn Sie ihn einer Source Map zuordnen wollen, müssen Sie ihn zuerst in Zeile und Spalte umrechnen.
- Rechnen Sie mit
-1, etwa bei Event-Handlern, Inline-Skripten oder wenn der Browser den Einstiegspunkt nicht bestimmen kann. - Bei Cross-Origin-Skripten ohne passende CORS-Freigabe können die Quellangaben fehlen oder eingeschränkt sein.
- Die Position gibt den Einstiegspunkt an, also etwa die aufgerufene Callback-Funktion. Die langsame Zeile selbst kann tiefer im Aufrufstapel liegen.