Объект CLSMetric: поля и типы

Объект CLSMetric используется в библиотеке Web Vitals для представления метрики Cumulative Layout Shift (CLS), которая измеряет визуальную стабильность страницы. CLS фиксирует неожиданные смещения элементов в процессе загрузки и взаимодействия с пользователем, что критично для оценки качества пользовательского опыта.

Основные поля объекта CLSMetric

CLSMetric является специализированным объектом метрики, наследующим базовые свойства из общей структуры Metric, но включает дополнительные детали, специфичные для CLS. Рассмотрим ключевые поля:

1. name (string) Название метрики. Для CLS это всегда "CLS". Используется для идентификации метрики в логах, аналитике и колбэках.

   console.log(metric.name); // "CLS"

2. value (number) Численное значение CLS на данный момент. Значение представляет собой суммарный коэффициент смещения элементов страницы, вычисляемый по алгоритму:

   [ CLS = ( )]

   где impact fraction — доля области видимой страницы, затронутая смещением, а distance fraction — нормализованное расстояние смещения относительно размера экрана.

   if (metric.value > 0.1) {
       console.warn("CLS выше рекомендуемого порога");
   }

3. delta (number) Отражает разницу в значении CLS между текущим измерением и предыдущим событием. Полезно для наблюдения за динамикой смещений на странице, особенно при ленивой загрузке контента или динамическом рендеринге.

   console.log(metric.delta); // изменение CLS с момента предыдущего события

4. id (string) Уникальный идентификатор метрики. Формат обычно включает тип метрики и уникальную последовательность, что позволяет различать события при многократных измерениях на одной странице.

   console.log(metric.id); // "v1-CLS-1234567890"

5. entries (LayoutShift[]) Массив объектов LayoutShift, представляющий все отдельные смещения, которые влияют на текущее значение CLS. Каждый элемент массива содержит детальную информацию о конкретном смещении:

   • value (number) — величина отдельного смещения.
   • sources (ShiftSource[]) — массив элементов DOM, участвующих в смещении.
   • hadRecentInput (boolean) — указывает, произошло ли смещение вследствие взаимодействия пользователя (например, клик или скролл), что обычно не учитывается в CLS.

   Пример структуры entries:

   metric.entries.forEach(entry => {
       console.log(entry.value, entry.sources, entry.hadRecentInput);
   });

Особенности обработки CLSMetric

• Агрегация смещений: Значение value всегда суммирует только те смещения, которые произошли без недавнего пользовательского взаимодействия (hadRecentInput === false). Это гарантирует, что метрика отражает только неожиданные смещения.
• Фиксация событий: Библиотека Web Vitals генерирует событие каждый раз, когда наблюдается новый значимый сдвиг. delta позволяет отслеживать прогрессию CLS в реальном времени.
• Использование в аналитике: CLSMetric удобно отправлять в аналитические системы, так как все поля имеют типы, полностью совместимые с JSON.

Пример получения CLSMetric через библиотеку Web Vitals

import { getCLS } from 'web-vitals';

getCLS((metric) => {
    console.log('CLS value:', metric.value);
    console.log('CLS delta:', metric.delta);
    console.log('CLS entries count:', metric.entries.length);
});

В данном примере объект metric имеет все описанные выше поля и позволяет детально анализировать смещения элементов страницы.

Резюме структуры CLSMetric

Эта структура обеспечивает полное представление о визуальной стабильности страницы и позволяет интегрировать измерения CLS в систему мониторинга производительности и пользовательского опыта.