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

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

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

Prop	Тип	Описание
tasks	Task[]	Массив объектов задач.
links	Link[]	Массив объектов связей.
templates	GanttTemplates	Переопределяет gantt.templates, такие как task_text, task_class, scale_cell_class.
config	GanttConfig	Объединяется с gantt.config, включая опции как scales, columns, autosize.
resources	Resource[]	Массив объектов ресурсов.
baselines	Baseline[]	Массив объектов базовых планов.
markers	Marker[]	Массив объектов маркеров для маркировки на временной шкале.
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-базированные inline-редакторы с интерфейсом встроенного inline редактора DHTMLX.
groupTasks	GroupConfig | boolean | null	Объект конфигурации группировки или false/null для отключения группировки (см. Grouping Tasks ).
filter	((task: Task) => boolean) | null	Функция, используемая для фильтрации задач Gantt.
resourceFilter	((resource: Resource) => boolean) | null	Функция, используемая для фильтрации ресурсов для Resource Panel.
modals	GanttModals	Позволяет заменить onBeforeTaskDelete и onBeforeLinkDelete модальные окна на пользовательские компоненты.
(Event Props)	Function	Обертка также поддерживает передачу пропсов-обработчиков событий, соответствующих событиям DHTMLX Gantt. Например, onTaskClick, onAfterTaskAdd и т. д. Если имя пропса совпадает с именем события, он прикрепляется автоматически.

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

<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" }
    ],
    // любой другой gantt.config, который вы хотите
  }}
  onTaskClick={(id, e) => {
    console.log('Task clicked:', id);
    return true; 
  }}
  templates={{
    task_text: (start, end, task) => `#${task.id}: ${task.text}`,
  }}
/>

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

Любое событие DHTMLX Gantt может быть передано как свойство. Например:

<ReactGantt

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

/>

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

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

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

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

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

• React хуки, специально предоставляемые оберткой, чтобы связать данные хранилищ и логику планирования Gantt

• Прямой доступ к экземпляру Gantt через ref, если встроенные хуки не покрывают все ваши потребности

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

Библиотека @dhx/react-gantt предоставляет набор опциональных хуков, которые соединяют React-компоненты с внутренними API Gantt. Эти хуки служат «мостом» к базовым методам и хранилищам Gantt. Вы можете вызывать эти хуки напрямую в своих компонентах или композировать их в собственные кастомные хуки для специализированных возможностей, например, для построения гистограмм ресурсов.

useGanttDatastore<T>(ganttRef, storeName)

Хук useGanttDatastore обеспечивает доступ только для чтения к конкретному хранилищу Gantt.
Распространённое использование — доступ к хранилищу ресурсов, baseline или любому другому встроенному или пользовательскому хранилищу.

Он предоставляет следующие функции:

• getItem(id) - возвращает указанный элемент из хранилища

• getItems() - возвращает все элементы в указанном хранилище

• hasChild(id: string | number) - проверяет, имеет ли элемент дочерние элементы

• getChildren(id: string | number) - получает дочерние элементы

import { useMemo } from 'react';
import { useGanttDatastore } from '@dhx/react-gantt';

function MyResourceList({ ganttRef }) {
  const resourceStore = useGanttDatastore(ganttRef, 'resource');

  const resourceIds = resourceStore.getItems().map(item => item.id);

  // для демонстрации — просто выводим данные
  useMemo(() => {
    console.log('Resource IDs:', resourceIds);
  }, [resourceIds]);

  return null; 
}

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

useResourceAssignments(ganttRef)

Хук useResourceAssignments обеспечивает доступ к методам Gantt, связанным с ресурсами, таким как получение назначений для ресурса или перечисление ресурсов, назначенных на данную задачу.

Он предоставляет следующие функции:

• getResourceAssignments(resourceId, taskId?) - мост к
• getTaskResources(taskId) - мост к

import React from 'react';
import { useResourceAssignments } from '@dhx/react-gantt';

export function ResourceUsage({ ganttRef, taskId }) {
  const { getTaskResources } = useResourceAssignments(ganttRef);

  const resources = getTaskResources(taskId);
  return (
    <div>
      Задаче {taskId} назначены ресурсы: 
      {resources.map(r => r.text).join(', ')}
    </div>
  );
}

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

useWorkTime(ganttRef)

Обеспечивает прямой мост к встроенным функциям DHTMLX Gantt worktime, таким как , , .

Вам понадобится этот хук для подсветки рабочего/нерабочего времени в соответствии с настройками календаря work calendar и для операций с датами.

Он предоставляет следующие функции:

• isWorkTime({ date:Date, unit?: string, task?:Task }) - мост к
• calculateEndDate({start:Date, duration:number, unit?: string, task?: Task}) - мост к
• calculateDuration({start:Date, end:Date, task?: Task}) - мост к
• getClosestWorkTime({ date:Date, unit?: string, task?: Task, dir?: "past"|"future" }) - мост к

import { useEffect, useRef, useState } from 'react';
import ReactGantt, {GanttTemplates, useWorkTime} from "@dhx/react-gantt";
import "@dhx/react-gantt/dist/react-gantt.css";

export default function GanttTemplatesDemo() {
  const ganttRef = useRef<ReactGanttRef>(null);

  const { isWorkTime }= useWorkTime(ganttRef);
  ...
  const templates: GanttTemplates = {
    timeline_cell_class: (task: Task, date: Date) => {
      return isWorkTime({date, task}) ? "" : "weekend";
    }
  };
  ...

Соединение хуков в ваши собственные кастомные хуки

Отличная практика — создавать собственные доменные или проектно-специфические хуки, используя эти фундаментальные мостовые хуки. Например, если вы хотите создать гистограмму ресурсов, можно сделать кастомный хук, который кэширует значения ёмкости, суммирует использование ресурсов и т. п.:

import { useMemo } from 'react';
import { useGanttDatastore, useResourceAssignments } from '@dhx/react-gantt';

export function useResourceHistogram(ganttRef) {
  const resourceStore = useGanttDatastore(ganttRef, 'resource');
  const { getResourceAssignments } = useResourceAssignments(ganttRef);

  // Пользовательская логика: кэширование ёмкости, детекция групп и т. д.
  // ...
  return {
    // напр. getCapacity, getAllocatedValue
  };
}

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

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

import React, { 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;

    // здесь можно вызывать ЛЮБОЙ метод API Gantt
    console.log('All tasks:', gantt.getTaskByTime());
    gantt.showDate(new Date());
  }, []);

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

заметка

Примечание: имейте в виду, что если вы изменяете tasks/links во встроенном экземпляре Gantt и одновременно передаете их как props в React, синхронизируйте данные или повторно разберите их. Иначе при следующем перерендеривании React ваши ручные изменения могут быть перезаписаны.

Если вы хотите выполнить что-то, что не доступно через проп, вы всё равно можете вызывать методы gantt напрямую. См. Accessing the Underlying Gantt API для получения дополнительной информации.