События (listeners)

Блок listeners в ChartOptions — колбэки на действия пользователя. Все события получают данные датума, поэтому чарт легко связывается с внешним UI: таблицами, фильтрами, drill-down-навигацией.

config.ts

import { getData } from './data';
import type { ChartOptions } from 'grafit-charts';

export function createOptions(): ChartOptions {
  return {
    data: getData(),
    title: { text: 'Chart events' },
    subtitle: { text: 'clicks, selection, wheel zoom, legend — events in the DevTools console' },
    series: [
      {
        type: 'bar',
        xField: 'feature',
        yField: 'usage',
        name: 'Usage, %',
      },
    ],
    selection: { enabled: true, mode: 'multiple' },
    zoom: { enabled: true },
    listeners: {
      nodeClick: ({ seriesId, datumIndex, datum }) => {
        console.log('nodeClick:', seriesId, datumIndex, datum);
      },
      selectionChange: ({ items }) => {
        console.log(
          'selectionChange:',
          // datum is there for a series that counts data rows; a histogram bin reports `node`
          items.map((item) => item.datum?.feature ?? item.node),
        );
      },
      zoomChange: ({ x }) => {
        console.log('zoomChange:', x.map((value) => value.toFixed(2)).join(' – '));
      },
      legendItemClick: ({ seriesId, visible }) => {
        console.log('legendItemClick:', seriesId, visible);
      },
    },
  };
}

data.ts

export function getData() {
  return [
    { feature: 'Search', usage: 86 },
    { feature: 'Filters', usage: 64 },
    { feature: 'Export', usage: 41 },
    { feature: 'Sharing', usage: 27 },
    { feature: 'API', usage: 18 },
  ];
}

Все события

Событие	Параметры	Когда срабатывает
nodeClick	{ seriesId; datumIndex; datum?; node? }	клик по узлу серии (бар, точка, сектор, ячейка…)
selectionChange	{ items: Array<{ seriesId; datumIndex; datum?; node? }> }	изменение выбора Data Selection (клики, рамка, сброс)
zoomChange	{ x: [от, до]; y: [от, до] } — доли домена 0..1	любое изменение зума: колесо, пан, рамка, навигатор, сброс
legendItemClick	{ seriesId: string; visible: boolean }	клик по элементу легенды (для секторов pie — 'seriesId#index')

Узел, который не является строкой данных

Большинство серий считает строки данных, и datum — та строка, по которой кликнули. Гистограмма считает столбцы — корзина за корзиной, группа внутри корзины, — и одной строки за ними нет: datum отсутствует, а node описывает то, во что попал клик.

Иерархия нумерует все узлы, которые рисует, включая вложенные, поэтому у treemap и sunburst datumIndex считает узлы, а не строки data. При этом datum — по-прежнему та строка, из которой прочитан узел: для вложенного это объект из children, что и нужно для drill-down по иерархии.

listeners: {
  nodeClick: ({ datum, node }) => {
    if (node?.kind === 'bin') {
      // { kind: 'bin', x0: 100, x1: 125, value: 61, raw: 61, count: 61, group: 'Pro' }
      filterRows((row) => row.response >= node.x0! && row.response < node.x1!);
      return;
    }
    openDetails(datum);
  },
}

binEdges экспортируется из пакета, поэтому такой фильтр может использовать те же границы, которые нарисовал график, а не пересчитывать их — см. Histogram.

selectionChange срабатывает только при включённом selection; zoomChange — при включённом zoom или навигаторе; nodeClick и legendItemClick работают всегда.

Паттерн: drill-down

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

const chart = Charts.create({
  ...options,
  listeners: {
    nodeClick: async ({ datum }) => {
      const details = await fetchDetails(datum.category);
      chart.update({ ...detailOptions, data: details });
    },
  },
});

Паттерн: связка с внешним UI

Выбор на чарте управляет таблицей рядом:

listeners: {
  selectionChange: ({ items }) => {
    table.setRowSelection(items.map((item) => item.datum.id));
  },
},

Обратное направление — управление чартом из приложения — через методы программного управления: chart.setSelection(targets, { silent: true }) выделит из таблицы, не отскочив обратно в листенер выше.

Замечания

• Колбэки — изолированные листья options: остальной объект сериализуем.
• datum — ссылка на исходный объект из data (не копия), включая вложенные строки children у иерархических серий.
• Для реакции на ховер используйте режимы тултипа и highlight; отдельного hover-события нет.