Написание собственного плагина

Плагины в Chart.js представляют собой расширяемый механизм, позволяющий вмешиваться в процесс инициализации, рендеринга и обновления графиков без изменения исходного кода библиотеки. Архитектура плагинов построена вокруг набора хуков жизненного цикла, через которые можно модифицировать данные, конфигурацию, отрисовку на Canvas и поведение графика.

Плагин в Chart.js — это объект, содержащий набор методов-хуков. Каждый хук вызывается в определённый момент жизненного цикла графика. Плагин может:

  • модифицировать данные перед отрисовкой;
  • добавлять кастомную графику поверх canvas;
  • реагировать на обновление или ресайз;
  • изменять поведение тултипов и легенды;
  • внедрять собственные визуальные элементы.

Базовая структура плагина:

const myPlugin = {
  id: 'myPlugin',

  beforeInit(chart, args, options) {},
  afterInit(chart, args, options) {},

  beforeUpdate(chart, args, options) {},
  afterUpdate(chart, args, options) {},

  beforeDraw(chart, args, options) {},
  afterDraw(chart, args, options) {},

  resize(chart, size, options) {},
  destroy(chart, options) {}
};

Ключевым обязательным полем является id. Оно используется для идентификации плагина внутри системы регистрации.

Контекст выполнения плагина

Каждый хук получает доступ к объекту chart, который содержит полное состояние графика:

  • chart.data — входные данные;
  • chart.options — конфигурация;
  • chart.ctx — CanvasRenderingContext2D;
  • chart.width и chart.height — размеры области отрисовки;
  • chart.scales — оси и их вычисленные параметры;
  • chart._metasets — внутренние структуры datasets.

Контекст позволяет не только читать состояние, но и изменять его. Однако прямые изменения внутренних полей требуют аккуратности, так как могут привести к неконсистентности рендера.

Жизненный цикл плагина

Жизненный цикл построен вокруг процесса обновления графика.

Инициализация

beforeInit вызывается до построения внутренних структур графика. На этом этапе можно:

  • модифицировать конфигурацию;
  • подменять данные;
  • добавлять служебные поля.

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

Обновление данных

beforeUpdate — точка вмешательства перед перерасчётом шкал и датасетов. afterUpdate — момент, когда уже пересчитаны элементы графика, но отрисовка ещё не выполнена.

Отрисовка

beforeDraw — вызывается перед началом рисования всех элементов. afterDraw — вызывается после завершения отрисовки.

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

Изменение размеров

resize позволяет реагировать на изменение размеров контейнера. Используется для пересчёта кастомных слоёв или внешних оверлеев.

Уничтожение

destroy вызывается при удалении графика. В этом хуке освобождаются ресурсы, удаляются слушатели событий, очищаются таймеры.

Регистрация плагина

Плагин может быть зарегистрирован глобально или локально.

Глобальная регистрация

Chart.register(myPlugin);

В этом случае плагин применяется ко всем графикам.

Локальная регистрация

const config = {
  type: 'line',
  data: {...},
  options: {
    plugins: {
      myPlugin: {
        enabled: true
      }
    }
  },
  plugins: [myPlugin]
};

Локальная регистрация ограничивает область действия конкретным графиком.

Параметры плагина

Плагин может получать настройки через объект options.plugins.

options: {
  plugins: {
    myPlugin: {
      color: 'red',
      fontSize: 12
    }
  }
}

Доступ к этим параметрам осуществляется через третий аргумент хука:

afterDraw(chart, args, options) {
  const color = options.color;
}

Работа с Canvas

Основной сценарий плагинов — кастомная отрисовка через chart.ctx.

Пример добавления текста поверх графика:

const textPlugin = {
  id: 'textPlugin',

  afterDraw(chart) {
    const { ctx, width, height } = chart;

    ctx.save();
    ctx.font = '16px sans-serif';
    ctx.fillStyle = 'black';
    ctx.textAlign = 'center';

    ctx.fillText('Custom overlay', width / 2, height / 2);

    ctx.restore();
  }
};

Использование ctx.save() и ctx.restore() критично для предотвращения утечек состояния Canvas (цветов, трансформаций, шрифтов).

Манипуляция данными

Плагины могут изменять входные данные до их обработки:

beforeUpdate(chart) {
  chart.data.datasets.forEach(dataset => {
    dataset.borderWidth = 3;
  });
}

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

Работа с метаданными графика

Chart.js хранит внутренние метаданные datasets, которые доступны через:

chart.getDatasetMeta(index);

Плагин может использовать это для анализа элементов:

afterUpdate(chart) {
  const meta = chart.getDatasetMeta(0);

  meta.data.forEach(point => {
    // доступ к координатам элемента
  });
}

Создание оверлеев и кастомных слоёв

Распространённый сценарий — добавление визуальных слоёв поверх графика.

const overlayPlugin = {
  id: 'overlayPlugin',

  afterDraw(chart) {
    const { ctx } = chart;

    ctx.save();
    ctx.fillStyle = 'rgba(0,0,0,0.1)';
    ctx.fillRect(10, 10, 100, 50);
    ctx.restore();
  }
};

Такие слои не участвуют в системе layout Chart.js и рисуются поверх canvas.

Управление состоянием плагина

Плагин может хранить состояние через замыкания или через объект chart.

Пример хранения данных:

const statePlugin = {
  id: 'statePlugin',

  beforeInit(chart) {
    chart.$state = {
      initializedAt: Date.now()
    };
  }
};

Использование chart.$state позволяет избежать глобальных переменных и привязать данные к конкретному экземпляру графика.

Взаимодействие с тултипами и легендой

Плагины могут изменять поведение встроенных компонентов через options.

Пример отключения тултипа при определённом условии:

const tooltipPlugin = {
  id: 'tooltipPlugin',

  beforeTooltipDraw(chart, args, options) {
    if (chart.data.datasets.length > 3) {
      return false;
    }
  }
};

Приоритеты выполнения плагинов

Если зарегистрировано несколько плагинов, они выполняются в порядке регистрации. Это важно при наличии зависимостей между плагинами, например:

  • один плагин модифицирует данные;
  • другой плагин использует уже изменённые данные для рендера.

Типичные ошибки при разработке плагинов

Частые проблемы связаны с:

  • прямым изменением внутренних _ полей;
  • отсутствием ctx.restore() после рисования;
  • изменением данных после afterUpdate;
  • конфликтом нескольких плагинов на одном hook;
  • отсутствием уникального id.

Корректная архитектура плагина предполагает минимальное вмешательство в ядро и строгое соблюдение фаз жизненного цикла.

Оглавление