Настройка содержимого tooltip

Визуальные подсказки (tooltip) в Kepler.gl формируются на основе данных слоя и конфигурации взаимодействий. Tooltip в системе построен как реакция на наведение курсора и может быть полностью управляемым через interactionConfig, форматирование полей и переопределение отображаемого компонента.

Базовая модель формирования tooltip

Tooltip в Kepler.gl не является статическим элементом интерфейса. Его содержимое формируется динамически из:

  • активного слоя (layer)
  • текущей позиции курсора (hovered object)
  • набора полей данных (fields)
  • настроек взаимодействия (interactionConfig)

При наведении на геометрический объект библиотека извлекает свойства объекта и сопоставляет их с конфигурацией отображения.

interactionConfig как центр управления tooltip

Основная точка настройки tooltip — объект interactionConfig внутри состояния визуализации.

const interactionConfig = {
  tooltip: {
    enabled: true,
    fieldsToShow: {
      trips: ['start_time', 'end_time', 'distance'],
      points: ['name', 'value']
    },
    compareMode: false,
    compareType: 'absolute',
    customTitle: 'Информация об объекте'
  }
};

Ключевые параметры:

  • enabled — включает/выключает tooltip
  • fieldsToShow — определяет список отображаемых полей по слоям
  • compareMode — включает сравнение объектов (двойной tooltip)
  • compareType — способ сравнения (absolute, relative)
  • customTitle — заголовок tooltip

Управление отображаемыми полями

Параметр fieldsToShow позволяет точно контролировать содержимое tooltip на уровне каждого слоя.

fieldsToShow: {
  city_layer: ['city', 'population', 'growth_rate'],
  taxi_layer: ['trip_distance', 'fare_amount']
}

Если слой не указан, Kepler.gl использует все доступные поля из данных, что часто приводит к перегруженному tooltip.

Форматирование значений полей

Kepler.gl поддерживает форматирование значений через formatValue или через описание поля в dataset metadata.

const dataset = {
  fields: [
    {
      name: 'population',
      format: 'number',
      formatValue: v => `${v.toLocaleString()} чел.`
    },
    {
      name: 'timestamp',
      format: 'date',
      formatValue: v => new Date(v).toLocaleString()
    }
  ]
};

Типовые сценарии форматирования:

  • числовые значения (разделение разрядов, единицы измерения)
  • даты и время (локализация формата)
  • географические координаты (округление)
  • денежные значения (валюта)

Контроль порядка отображения полей

Порядок полей в tooltip определяется массивом fieldsToShow. Это позволяет управлять логической структурой подсказки.

fieldsToShow: {
  orders_layer: [
    'order_id',
    'customer_name',
    'order_total',
    'status'
  ]
}

Порядок важен, поскольку tooltip отображает данные сверху вниз без автоматической сортировки по смыслу или типу.

Переопределение tooltip на уровне слоя

Каждый слой может иметь собственную конфигурацию взаимодействий, включая tooltip.

const layerConfig = {
  id: 'points_layer',
  type: 'point',
  config: {
    dataId: 'points_dataset',
    label: 'Точки интереса',
    color: [255, 0, 0],
    interactionConfig: {
      tooltip: {
        fieldsToShow: {
          points_dataset: ['name', 'category', 'rating']
        },
        enabled: true
      }
    }
  }
};

Такой подход позволяет создавать разные tooltip-структуры для разных визуальных слоев на одной карте.

Tooltip в режиме сравнения объектов

Режим сравнения (compareMode) позволяет отображать два объекта одновременно.

interactionConfig: {
  tooltip: {
    enabled: true,
    compareMode: true,
    compareType: 'absolute'
  }
}

В этом режиме tooltip делится на две колонки:

  • левый объект (первый hover)
  • правый объект (второй hover)

Используется при анализе изменений, маршрутов или плотностей.

Кастомизация через React-компонент

Kepler.gl построен на React и позволяет полностью заменить стандартный tooltip компонент.

function CustomTooltip({ object, fields }) {
  return (
    <div className="tooltip">
      <h4>{object.properties.name}</h4>
      <ul>
        {fields.map(f => (
          <li key={f.name}>
            {f.name}: {object.properties[f.name]}
          </li>
        ))}
      </ul>
    </div>
  );
}

Подмена осуществляется через кастомную интеграцию KeplerGl:

<KeplerGl
  id="map"
  mapboxApiAccessToken={token}
  getTooltip={CustomTooltip}
/>

Использование Redux-состояния для управления tooltip

Kepler.gl хранит состояние tooltip внутри глобального состояния приложения.

state.keplerGl.map.visState.interactionConfig.tooltip

Изменение этого состояния позволяет динамически управлять tooltip без пересоздания карты.

Пример обновления через action:

dispatch(
  updateVisData({
    interactionConfig: {
      tooltip: {
        enabled: false
      }
    }
  })
);

Условное отображение полей

Tooltip можно адаптировать под условия данных.

fieldsToShow: {
  sales_layer: salesType === 'retail'
    ? ['store', 'revenue']
    : ['region', 'wholesale_volume']
}

Такой подход используется при переключении режимов аналитики в интерфейсах.

Работа с вложенными структурами данных

Если данные содержат вложенные объекты, tooltip отображает только плоские значения. Для работы с вложенностью требуется предварительная нормализация.

const normalized = data.map(d => ({
  ...d,
  city_name: d.city.name,
  city_population: d.city.population
}));

После этого tooltip получает доступ к уже развернутым полям.

Скрытие служебных полей

Часто dataset содержит технические поля, не предназначенные для отображения. Их исключают через fieldsToShow.

fieldsToShow: {
  layer: ['name', 'value']
}

Альтернативный подход — фильтрация метаданных поля:

{
  name: 'internal_id',
  hidden: true
}

Формирование tooltip для сложных слоёв

Для слоёв типа arc, hexbin, heatmap tooltip формируется на основе агрегированных значений.

Пример:

fieldsToShow: {
  heat_layer: ['density', 'avg_value', 'max_value']
}

В таких случаях tooltip показывает статистические характеристики, а не отдельные объекты.

Контроль поведения при наведении

Tooltip активируется через механизм hover-событий WebGL (через deck.gl слой, используемый внутри Kepler.gl, основанный на Mapbox GL JS-экосистеме).

Параметры взаимодействия:

  • задержка отображения
  • чувствительность к движению курсора
  • приоритет слоя при пересечении объектов

Динамическая генерация содержимого tooltip

Tooltip может формироваться не только из полей, но и из вычисляемых значений.

fieldsToShow: {
  layer: ['name', 'value', 'calculated_score']
}

Где calculated_score создаётся на этапе подготовки данных:

score = revenue / population;

Локализация и форматирование чисел

Для мультиязычных интерфейсов tooltip поддерживает локализованные форматы через JavaScript Intl API:

formatValue: v =>
  new Intl.NumberFormat('ru-RU', {
    style: 'currency',
    currency: 'RUB'
  }).format(v);

Управление плотностью информации

Tooltip в Kepler.gl должен балансировать между информативностью и перегрузкой. Основные механизмы управления:

  • ограничение fieldsToShow
  • агрегация данных на уровне слоя
  • кастомное форматирование
  • скрытие технических полей
  • разделение tooltip по слоям

Переиспользование конфигурации tooltip

Конфигурации tooltip часто выносятся в отдельные модули:

export const tooltipConfig = {
  tooltip: {
    enabled: true,
    fieldsToShow: {
      default: ['name', 'value']
    }
  }
};

Это позволяет унифицировать поведение подсказок в разных визуализациях и слоях.

Оглавление