@iyotsuba/gantt-react

Yotsuba Gantt 的 React 18 / 19 组件包。复用无框架 Core，提供虚拟滚动、六档时间维度、密集数据聚焦、任务依赖、拖动吸附、多图联动和 Render Props。

安装

pnpm add @iyotsuba/gantt-react @iyotsuba/gantt-core

import { useState } from 'react'
import { YgGantt, type GanttTask, type ViewPresetId } from '@iyotsuba/gantt-react'
import '@iyotsuba/gantt-react/style.css'

export function ProjectPlan() {
  const [view, setView] = useState<ViewPresetId>('week')
  const tasks: GanttTask[] = [
    {
      id: 'design',
      title: '交互设计',
      start: '2026-08-03',
      end: '2026-08-12',
      progress: 68,
      owner: { name: '小叶' },
      color: '#1f9d68',
    },
  ]

  return (
    <YgGantt
      tasks={tasks}
      view={view}
      onViewChange={setView}
      onTaskClick={({ task }) => console.log(task)}
      onTaskDoubleClick={(task) => console.log('详情', task)}
    />
  )
}

大数据

120 行以上默认启用行虚拟化，180 个时间格以上默认启用列虚拟化。10,000 条任务模式只创建当前视口与 overscan 内的行。可通过 ref.current.getRenderStats() 获取真实渲染量。

const gantt = useRef<YgGanttReactHandle>(null)

<YgGantt
  ref={gantt}
  tasks={tasks}
  rowVirtualizationThreshold={120}
  rowOverscan={4}
  onVisibleRangeChange={(range) => loadWindow(range)}
/>

多图联动

同一个 groupId 下的图表可按 scroll、view 或 all 联动；不传 groupId 或设置 sync="none" 时完全独立。

<YgGantt tasks={productTasks} groupId="release" sync="all" />
<YgGantt tasks={deliveryTasks} groupId="release" sync="all" />

滚动锚点在原生滚动事件中同步写入，接收端直接更新 scrollLeft，不会等待下一次 React 渲染。

Render Props

| 属性 | 参数 | 用途 | | --- | --- | --- | | renderTaskHeader | - | 自定义任务列表头 | | renderTask | task, rowIndex, selected | 自定义任务单元格 | | renderOwner | task, rowIndex | 自定义负责人 | | renderProgress | task, progress | 自定义进度展示 | | renderBar | task, selected, progress, width, height | 自定义任务条内容 | | renderDependency | link, source, target, path, style | 替换依赖线 SVG | | renderEdgeIndicator | side, task, rowIndex, jump | 替换每行边界入口 | | renderEmpty | - | 空数据状态 |

事件

| 属性 | 说明 | | --- | --- | | onTaskClick | 单击任务行或任务条，载荷包含 source | | onTaskDoubleClick | 双击任务，适合打开 Dialog / Drawer | | onLinkDoubleClick | 双击依赖线 | | onTaskChange | 拖动或调整任务边界后给出不可变变更载荷 | | onViewChange | 受控时间维度变更 | | onVisibleRangeChange | 当前日期和行窗口，适合远程分页 | | onSidebarWidthChange | 左侧任务表宽度变化 |

实例方法

gantt.current?.focus({ strategy: 'dense', scope: 'viewport' })
gantt.current?.scrollToDate('2026-08-12')
gantt.current?.scrollTaskIntoView('design')
gantt.current?.scrollToRow(2400)
gantt.current?.fitToData()
gantt.current?.setView('month')
gantt.current?.selectTask('design')
gantt.current?.getRenderStats()

完整 Props、Core 数据模型和跨框架示例见 官方中文文档。