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

На этой странице представлен обзор поддерживаемых свойств (props) React Gantt и объясняется, как они соответствуют возможностям DHTMLX Gantt.

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

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-редакторы с интерфейсом встроенных редакторов DHTMLX.
groupTasks	GroupConfig | boolean | null	Задает конфигурацию группировки или отключает группировку при значении false или null (см. Группировка задач).
filter	((task: Task) => boolean) | null	Функция для фильтрации отображаемых задач Gantt.
resourceFilter	((resource: Resource) => boolean) | null	Фильтрует ресурсы, отображаемые в панели ресурсов.
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; 
  }}

/>

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

Комбинирование свойств и DHTMLX API

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

• Расчет рабочего времени
• Автоматическое планирование или расширенные возможности, такие как работа с ресурсами
• Использование отдельных методов из Gantt API

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

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

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

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

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

useGanttDatastore<T>(ganttRef, storeName)

Хук useGanttDatastore предоставляет только для чтения доступ к определенному хранилищу данных Gantt. Обычно используется для доступа к хранилищу ресурсов, базовым планам или другим встроенным/кастомным хранилищам.

Включает следующие функции:

• 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 предоставляет методы, связанные с ресурсами, включая получение назначений для ресурса или список ресурсов, назначенных задаче.

Доступные функции:

• getResourceAssignments(resourceId, taskId?) - соответствует getResourceAssignments

• getTaskResources(taskId) - соответствует getTaskResources

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>
      Task {taskId} assigned to: 
      {resources.map(r => r.text).join(', ')}
    </div>
  );
}

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

useWorkTime(ganttRef)

Этот хук предоставляет доступ к встроенным функциям рабочего времени DHTMLX Gantt, таким как isWorkTime, calculateEndDate и calculateDuration.

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

Доступные функции:

• isWorkTime(( date:Date, unit?: string, task?:Task )) - соответствует isWorkTime

• calculateEndDate((start:Date, duration:number, unit?: string, task?: Task)) - соответствует calculateEndDate

• calculateDuration((start:Date, end:Date, task?: Task)) - соответствует calculateDuration

• getClosestWorkTime(( date:Date, unit?: string, task?: Task, dir?: "past"|"future" )) - соответствует getClosestWorkTime

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;

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

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

((info Учтите, что если вы изменяете tasks или links напрямую через экземпляр Gantt, одновременно передавая их как props в React, необходимо синхронизировать данные или повторно парсить их. В противном случае следующий рендер React может перезаписать ваши изменения. ))

Если необходимо выполнить действия, не реализованные через props, всегда можно вызвать методы gantt напрямую. Подробнее см. в разделе Accessing the Underlying Gantt API.