在 ReactGantt 中使用 DHTMLX Gantt 属性

本页描述 React Gantt 接受的属性，以及它们如何映射到 DHTMLX Gantt 的特性。

可用属性

属性	类型	描述
tasks	Task[]	一个 task objects 的数组。
links	Link[]	一个 link objects 的数组。
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[]	一个 resource objects 的数组。
baselines	Baseline[]	一个 baseline objects 的数组。
markers	Marker[]	用于 timeline markers 的标记对象数组。
plugins	GanttPlugins	Gantt extensions 需要被激活，例如 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	用于替换内置 Lightbox 的 React 组件（参见 Custom Lightbox）。
inlineEditors	( [editorType: string]: React.ComponentType )	允许将基于 React 的内联编辑器映射到 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 模态框。
htmlTemplatePolicy	HtmlTemplatePolicy	控制从模板函数返回的字符串值的呈现方式。 "basic-sanitize"（默认）对返回的 HTML 进行白名单净化：保留安全的格式、类、有限的内联样式、data-* 属性和 img，同时移除脚本、事件处理程序和危险 URL。 "escape" 将字符串渲染为文本； "unsafe-html" 按原样渲染字符串（pre-v10 行为）；一个自定义的消毒对象（mode: "sanitize"，带有 sanitize(html) 函数）可以让你接入诸如 DOMPurify 的库。若要对每个模板进行单独控制，请使用导出的 allowRawHTML() 助手对各自的模板函数进行包裹。请参阅 Migration notes。
(Event Props)	Function	包装器同样支持传递与 DHTMLX Gantt 事件对应的事件处理程序属性。例如 onTaskClick、onAfterTaskAdd 等。如果属性名与事件名匹配，将自动附加。

Type Exports

@dhx/react-gantt 包 re-导出若干 TypeScript 类型，可用于给你的应用代码标注类型：

Export	Description
Task	内部 Gantt 任务对象。日期是 Date 对象；包括以 $ 前缀的系统属性。在事件处理程序中使用，以及在处理 Gantt 拥有的数据时使用。
Link	内部 Gantt 链接对象。在事件处理程序中使用，以及在处理 Gantt 拥有的数据时使用。
SerializedTask	面向用户的任务形状，用于存储状态、初始数据和保存回调载荷。日期属性接受 Date | string。
SerializedLink	面向用户的链接形状，用于存储状态、初始数据和保存回调载荷。

何时使用 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}`,
  }}
/>

使用事件属性

你可以将任意 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 引擎的场景。举例来说，可能涉及到：

• Worktime calculations
• Auto scheduling 逻辑，或诸如 resource computations 这样的高级功能
• 调用 Gantt API 的任何专用方法

在这些情况下，你可以使用两种额外的方式来接入底层的 DHTMLX Gantt 功能：

• React hooks 这是包装器专门提供的，用于桥接 Gantt 的数据存储和调度逻辑

• 通过引用（ref）直接访问 Gantt 实例，如果内置的钩子无法覆盖你所有需求

使用内置钩子

@dhx/react-gantt 库提供了用于事件订阅、资源管理、数据存储访问、撤销/重做、缩放、选取和工作时间计算的钩子。

完整参考请查看专门的 Hooks 页面，包括：

• useGanttEvent - 带生命周期管理的事件订阅
• useResourceAssignments - 资源分配查询和变更
• useGanttDatastore - 只读的数据存储访问
• useUndoRedo - 撤销/重做的状态与操作
• useZoom - 缩放控制和状态
• useSelection - 任务选择跟踪
• useWorkTime - 工作时间计算

使用 ref 直接访问 Gantt 实例

虽然钩子可以满足大多数高级需求，但你可能仍然想要对整个 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 实例中的 tasks 或 links 的同时又通过 React 属性提供了它们，请确保两者保持同步。否则，下一次 React 重新渲染可能会覆盖你手动的修改。

更多细节请参阅 Accessing the Underlying Gantt API。