Функция onFCP и объект FCPMetric

First Contentful Paint (FCP) — ключевой показатель производительности, фиксирующий момент, когда пользователь видит первый визуальный контент на странице. В библиотеке Web Vitals измерение FCP реализуется с помощью функции onFCP, которая обеспечивает точное отслеживание этого события в реальном времени и предоставляет детализированные метрики через объект FCPMetric.

Функция onFCP

Функция onFCP используется для регистрации обратного вызова, который вызывается, когда браузер зафиксировал первый контентный элемент на странице. Она имеет следующий сигнатурный вид:

import { onFCP } from 'web-vitals';

onFCP(callback: (metric: FCPMetric) => void, reportAllChanges?: boolean);

Параметры функции:

  • callback — функция обратного вызова, которая принимает объект FCPMetric. Это основной способ получения данных о FCP.
  • reportAllChanges (необязательный, по умолчанию false) — если установлен в true, обратный вызов будет вызываться при каждом изменении метрики, а не только при первом измерении. Это полезно для динамических страниц с подгружаемым контентом.

Объект FCPMetric

Объект FCPMetric содержит все данные, необходимые для аналитики и мониторинга производительности. Его структура:

interface FCPMetric {
  name: 'FCP';
  value: number;
  delta: number;
  id: string;
  entries: PerformanceEntry[];
  rating?: 'good' | 'needs-improvement' | 'poor';
}

Описание полей:

  • name — строка 'FCP', указывает тип метрики.
  • value — численное значение метрики в миллисекундах, отражает время до появления первого контента.
  • delta — разница между текущим и предыдущим значением метрики. Позволяет отслеживать изменения при повторных измерениях.
  • id — уникальный идентификатор метрики, полезен для корреляции с другими метриками или аналитическими событиями.
  • entries — массив объектов PerformanceEntry, предоставляющий низкоуровневые данные производительности, включая точное время каждого зарегистрированного события.
  • rating (опционально) — классификация производительности: 'good' (до 1.8 с), 'needs-improvement' (1.8–3 с), 'poor' (более 3 с).

Пример использования onFCP

Простой пример регистрации FCP:

import { onFCP } from 'web-vitals';

onFCP((metric) => {
  console.log('FCP:', metric.value);
  console.log('ID метрики:', metric.id);
  console.log('Performance entries:', metric.entries);
  if (metric.rating) {
    console.log('Рейтинг FCP:', metric.rating);
  }
});

В этом примере при срабатывании события FCP в консоль выводятся:

  • Время появления первого контента.
  • Уникальный идентификатор метрики.
  • Детальные записи производительности.
  • Классификация FCP по шкале качества.

Отслеживание изменений на динамических страницах

Если страница подгружает контент асинхронно, одно измерение FCP может быть недостаточным. В этом случае можно включить повторные отчёты:

onFCP((metric) => {
  console.log('Обновлённый FCP:', metric.value);
}, true);

Параметр true заставляет onFCP отправлять новые значения при каждом обновлении метрики, что полезно для Single Page Applications (SPA), где контент может загружаться после первоначального рендера.

Взаимодействие с другими Web Vitals

Объект FCPMetric легко интегрируется с другими метриками Web Vitals, такими как LCP или CLS. Поскольку каждая метрика имеет уникальный идентификатор и массив entries, их можно объединять для построения полного профиля производительности страницы:

import { onFCP, onLCP } from 'web-vitals';

onFCP((fcp) => console.log('FCP:', fcp.value));
onLCP((lcp) => console.log('LCP:', lcp.value));

Такой подход позволяет:

  • Сравнивать время первого отображения контента с временем загрузки основного контента.
  • Выявлять узкие места в рендеринге страницы.
  • Строить метрики для пользовательской аналитики или A/B тестов.

Важные нюансы использования

  • Совместимость браузеров: FCP поддерживается большинством современных браузеров, однако на старых версиях Safari и IE возможны ограничения.
  • Асинхронный рендеринг: при динамическом добавлении элементов важно учитывать, что FCP фиксируется на первый видимый элемент, а не на весь контент страницы.
  • Влияние сторонних скриптов: медленные скрипты могут отложить FCP, поэтому мониторинг с использованием onFCP помогает выявлять проблемные зависимости.

onFCP вместе с объектом FCPMetric предоставляет детализированный инструмент для анализа пользовательского опыта. Он фиксирует ключевой момент отображения контента, позволяет классифицировать производительность и интегрируется с остальными метриками Web Vitals, что делает его незаменимым для профессионального мониторинга веб-приложений.

Оглавление