跳到主要内容

使用 ReactGantt 中的 DHTMLX Gantt 属性

本页概述了 React Gantt 支持的 props，并解释了它们与 DHTMLX Gantt 功能的对应关系。

可用 Props​

Prop类型说明
tasksTask[]一个 任务对象数组。
linksLink[]一个 链接对象数组。
templatesGanttTemplates重写 gantt.templates，如 task_text、task_class、scale_cell_class。
configGanttConfig合并到 gantt.config，包含如 scales、columns、autosize 等选项。
resourcesResource[]一个 资源对象数组。
baselinesBaseline[]一个 基线对象数组。
markersMarker[]用于 时间线标记的标记对象数组。
pluginsGanttPlugins需启用的 Gantt 扩展（如 critical_path、auto_scheduling 等）。
data( load?: string, save?: string|RouterFunction, batchSave?: BatchChanges)支持通过内置 Gantt 传输加载数据，并提供回调以处理 Gantt 数据的更改。
localestring设置 gantt.i18n.setLocale(locale)。默认值为 "en"。
themestring应用 gantt.setSkin(theme)。默认值为 "terrace"。
customLightboxReactElement | null用于替换默认 Lightbox 的 React 组件（参见 自定义 Lightbox）。
inlineEditors( [editorType: string]: React.ComponentType )允许将基于 React 的内联编辑器映射到 DHTMLX 的内联编辑器接口。
groupTasksGroupConfig | boolean | null指定分组配置，或设置为 false 或 null 以禁用分组（参见 任务分组）。
filter((task: Task) => boolean) | null用于过滤显示的 Gantt 任务的函数。
resourceFilter((resource: Resource) => boolean) | null过滤 资源面板中显示的资源。
modalsGanttModals允许自定义组件替换 onBeforeTaskDelete 和 onBeforeLinkDelete 弹窗。
(Event Props)Function支持与 DHTMLX Gantt 事件同名的事件处理 props，例如 onTaskClick、onAfterTaskAdd 等。名称匹配的 props 会自动绑定。

使用示例​

<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}`,
  } }
/>

事件 Props 的使用​

任何 DHTMLX Gantt 事件都可以作为 prop 传递。例如:

<ReactGantt

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

/>

当你传递如 onBeforeTaskAdd 这样的 prop 时，封装组件会在内部调用 gantt.attachEvent("onBeforeTaskAdd", handler)。完整事件列表请参考 DHTMLX Gantt API。

组合 Props 与 DHTMLX API​

@dhx/react-gantt 库旨在通过声明式 props（如 tasks、links、resources、templates 等）覆盖大多数日常需求。但在某些情况下，您可能需要更深入地访问 Gantt 引擎，例如:

针对这些场景，有两种方式可以直接与底层 DHTMLX Gantt 功能交互:

  • React hooks:由封装库提供，连接到 Gantt 的数据存储和调度逻辑

  • 通过 ref 直接访问 Gantt 实例（如果 hooks 无法满足所有需求）

使用内置 hooks​

@dhx/react-gantt 提供若干可选 hooks，将 React 组件与内部 Gantt API 连接。这些 hooks 是 Gantt 方法和数据存储的桥梁。你可以在组件中直接使用它们，也可以组合成自定义 hooks，用于如资源直方图等特定功能。

useGanttDatastore<T>(ganttRef, storeName)​

useGanttDatastore hook 提供对特定 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; 
}

当你需要直接访问某个数据存储中的底层数据时（例如判断资源是组还是个人），该 hook 很有用。

useResourceAssignments(ganttRef)​

useResourceAssignments hook 提供与资源相关的方法，包括获取资源的分配信息或列出分配给任务的资源。

包含以下函数:

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>
  );
}

该 hook 便于实现自定义的资源使用逻辑，例如计算分配工时或按负责人分组任务。

useWorkTime(ganttRef)​

此 hook 提供对 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";
    }
  };
  ...

组合 hooks 构建自定义 hooks​

推荐将这些基础 hooks 组合，构建你自己的领域或项目专用 hooks。例如，为实现资源直方图，你可以开发一个自定义 hook 用于缓存容量值并汇总资源使用情况:

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
  };
}

通过 ref 直接访问 Gantt 实例​

虽然 hooks 能覆盖大多数高级需求，但你仍可以通过 ref 直接访问整个 Gantt 实例:

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}"
    />
  );
}
信息

如果你直接在 Gantt 实例上修改 tasks 或 links，同时又作为 React props 提供它们，请确保同步或重新解析数据。否则 React 下次渲染时可能会覆盖你手动的更改。

如果你需要执行 props 未覆盖的操作，依然可以直接调用 gantt 方法。更多细节参见 Accessing the Underlying Gantt API。