Использование свойств DHTMLX Gantt в ReactGantt

Эта страница описывает принимаемые React Gantt свойства и то, как они сопоставляются с возможностями DHTMLX Gantt.

Доступные свойства

Свойство	Тип	Описание
tasks	Task[]	Массив объектов задачи.
links	Link[]	Массив объектов связи.
templates	GanttTemplates	Переопределяет gantt.templates, например: task_text, task_class, scale_cell_class.
config	GanttConfig	Объединён в gantt.config, например: scales_config, columns_config, autosize_config.
calendars	Calendar[]	Массив рабочих календарей. Пример: Working Calendars.
resources	Resource[]	Массив объектов ресурсов.
baselines	Baseline[]	Массив базовых объектов.
markers	Marker[]	Массив объектов маркеров для timeline markers.
plugins	GanttPlugins	Расширения Gantt, которые нужно активировать (например: critical_path, auto_scheduling).
data	( load?: string, save?: string|RouterFunction, batchSave?: BatchChanges)	Позволяет загружать данные через встроенный транспорт Gantt и предоставляет колбэки для изменений, внесённых в данные Gantt.
locale	string	Устанавливает gantt.i18n.setLocale(locale). По умолчанию — "en".
theme	string	Применяет gantt.setSkin(theme). По умолчанию — "terrace".
customLightbox	ReactElement | null	React-компонент, заменяющий встроенный Lightbox (см. [Custom Lightbox]).
inlineEditors	( [editorType: string]: React.ComponentType )	Позволяет сопоставлять ваши инлайн-редакторы на базе React с интерфейсом встроенного редактора DHTMLX.
groupTasks	GroupConfig | boolean | null	Объект конфигурации группировки или false/null для отключения группировки (см. Группировка задач).
filter	((task: Task) => boolean) | null	Функция, используемая для фильтрации задач Gantt.
resourceFilter	((resource: Resource) => boolean) | null	Функция, используемая для фильтрации ресурсов для Панели ресурсов.
modals	GanttModals	Позволяет заменять модальные окна onBeforeTaskDelete и onBeforeLinkDelete пользовательскими компонентами.
htmlTemplatePolicy	HtmlTemplatePolicy	Контролирует, как строки, возвращаемые из функций-шаблонов, рендерятся. "basic-sanitize" (по умолчанию) — whitelist-санитизация возвращаемого HTML: безопасное форматирование, классы, ограниченные встроенные стили, data-* атрибуты и img сохраняются; скрипты, обработчики событий и опасные URL-адреса удаляются. "escape" рендерит строку как текст; "unsafe-html" рендерит исходную строку (поведение до v10); пользовательский объект санитайзера (mode: "sanitize" с функцией sanitize(html)) позволяет подключить такую библиотеку, как DOMPurify. Для управления на уровне отдельных шаблонов оборачивайте отдельные функции-шаблоны экспортируемым помощником allowRawHTML(). Migration notes.
(Event Props)	Function	Обёртка также поддерживает передачу пропсов-обработчиков событий, соответствующих событиям DHTMLX Gantt. Например, onTaskClick, onAfterTaskAdd и т.д. Если имя пропса совпадает с названием события, оно автоматически прикрепляется.

Экспортируемые типы

Пакет @dhx/react-gantt повторно экспортирует несколько типов TypeScript, которые можно использовать для аннотирования вашего кода приложения:

Экспорт	Описание
Task	Внутренний объект задачи Gantt. Даты представлены как объекты Date; включает системные свойства с префиксом $. Используйте внутри обработчиков событий и при работе с данными, которые принадлежит Gantt.
Link	Внутренний объект связи Gantt. Используйте внутри обработчиков событий и при работе с данными, которые принадлежит Gantt.
SerializedTask	Модель задачи, предназначенная для данных, которыми вы владеете: состояние хранилища, ответы API и начальные данные. Поля дат принимают `Date
SerializedLink	Модель связи, предназначенная для данных, которыми вы владеете: состояние хранилища, начальные данные и payloads для сохранения.

Когда использовать SerializedTask / SerializedLink vs Task / Link:

• SerializedTask / SerializedLink — для данных, которыми вы владеете: состояние хранилища, ответы API, исходные данные. Поля дат принимают строки (например, даты в ISO-формате).
• Task / Link — для данных, которыми владеет Gantt: внутри обработчиков событий, после того, как Gantt распарсит данные. Поля дат — объекты Date. У Task есть внутренние свойства с префиксом $.

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

<ReactGantt
  tasks={tasks}
  links={links}
  theme="material"
  locale="en"
  config={{
    scales: [
      { unit: "year", step: 1, format: "%Y" },
      { unit: "month", step: 1, format: "%M" }
    ],
    columns: [
      { name: "text", tree: true, width: '*' },
      { name: "start_date", align: "center" },
      { name: "duration", align: "center" },
      { name: "add" }
    ],
    // any other gantt.config you want
  }}
  onTaskClick={(id, e) => {
    console.log('Task clicked:', id);
    return true; 
  }}
  templates={{
    task_text: (start, end, task) => `#${task.id}: ${task.text}`,
  }}
/>

Использование пропсов-ивентов (Event Props)

Вы можете передавать любой событие-Prop DHTMLX Gantt. Например:

<ReactGantt

  onTaskClick={(id, e) => {
    console.log('Task clicked:', id);
    return true; 
  }}

/>

Внутри обёртка вызывает gantt.attachEvent("onBeforeTaskAdd", handler), если вы передаёте проп с именем onBeforeTaskAdd. Для полного списка событий смотрите DHTMLX Gantt API.

Сочетание пропсов и API DHTMLX

Библиотека @dhx/react-gantt задумана как можно более декларативной для повседневного использования — большинство сценариев можно решить с помощью стандартных пропсов (таких как tasks, links, resources, templates и т. п.). Однако могут быть ситуации, когда нужен более глубокий доступ к движку Gantt. Например, для:

• расчётов рабочего времени
• логики автоматического планирования или продвинутых функций, таких как вычисления ресурсов
• вызова любых специализированных методов API Gantt

В таких случаях можно воспользоваться двумя дополнительными подходами, чтобы получить доступ к базовой функциональности DHTMLX Gantt:

• [React hooks] специально предоставляемые обёрткой для связывания хранилищ данных Gantt и логики планирования
• Direct access к экземпляру Gantt через ref, если встроенные хуки не покрывают все ваши потребности

Использование встроенных хуков

Библиотека @dhx/react-gantt предоставляет хуки для подписки на события, управления ресурсами, доступа к datastore, undo/redo, зума, выбора и расчётов рабочего времени.

См. отдельную страницу Hooks для полного справочника, включая:

• useGanttEvent — подписки на события с управлением жизненным циклом
• useResourceAssignments — запросы и изменения назначений ресурсов
• useGanttDatastore — доступ только для чтения к datastore
• useUndoRedo — состояние undo/redo и действия
• useZoom — управление зумом и состояние
• useSelection — трекинг выбора задач
• useWorkTime — расчёты рабочего времени

Прямой доступ к экземпляру Gantt через ref

Хотя хуки удовлетворяют большинство продвинутых потребностей, иногда может потребоваться прямой доступ ко всему экземпляру Gantt. Для этого доступ через ref остаётся доступным:

import { useRef, useEffect } from 'react';
import ReactGantt, { ReactGanttRef } from '@dhx/react-gantt';

export function DirectRefExample({ tasks, links }) {
  const ganttRef = useRef<ReactGanttRef>(null);

  useEffect(() => {
    const gantt = ganttRef.current?.instance;
    if (!gantt) return;
    gantt.showDate(new Date());
  }, []);

  return <ReactGantt ref={ganttRef} tasks={tasks} links={links} />;
}

заметка

Если вы изменяете задачи или связи через прямой экземпляр Gantt, пока они также подаются как пропсы React, держите их синхронизированными. Иначе следующая перерисовка React может перезаписать ваши ручные изменения.

См. раздел Accessing the Underlying Gantt API для дополнительной информации.