常见问题

整理了 GanttFlow 使用过程中最常见的问题，按类别组织，方便快速查找。

安装问题

Q: 安装失败，提示 peerDependencies 警告？

A: 这是正常的警告，不影响使用。GanttFlow 的 peerDependencies 是可选的：

# 如果你只使用 React
npm install @agions/gantt-flow react react-dom

# 如果你只使用 Vue
npm install @agions/gantt-flow vue

# 如果两个框架都要用
npm install @agions/gantt-flow react vue

Q: 安装太慢/失败？

A: 尝试以下方法：

# 使用淘宝镜像
npm install @agions/gantt-flow --registry=https://registry.npmmirror.com

# 或者清理缓存重试
npm cache clean --force
npm install @agions/gantt-flow

---

使用问题

Q: 样式没有生效，组件看起来没有样式？

A: 请确保引入了样式文件：

// 在入口文件或组件文件中添加
import "@agions/gantt-flow/style"

Q: 任务不显示或位置不正确？

A: 检查以下几点：

1. 任务数据格式是否正确：

// ✅ 正确格式
{ id: "1", name: "任务", start: "2024-01-01", end: "2024-01-10" }

// ❌ 错误格式
{ id: "1", name: "任务", start: "2024/01/01", end: "01-10-2024" }

2. start 是否在 end 之前：

// ❌ start 晚于 end
{ start: "2024-01-10", end: "2024-01-01" }

3. 容器是否有明确高度：

// ✅ 设置容器高度
<div style={{ height: "500px" }}>
  <EnhancedGanttChart tasks={tasks} />
</div>

Q: 如何让甘特图自适应容器宽度？

A: 设置容器宽度即可：

<div style={{ width: "100%" }}>
  <EnhancedGanttChart tasks={tasks} />
</div>

Q: 日期显示格式不对？

A: 通过 locale 属性自定义：

const locale = {
  dateFormat: 'YYYY-MM-DD',  // 自定义日期格式
  // 或
  dateFormat: 'DD/MM/YYYY',  // 欧洲格式
  // 或
  dateFormat: 'MM/DD/YYYY',   // 美国格式
}

<EnhancedGanttChart tasks={tasks} locale={locale} />

---

性能问题

Q: 任务数量多时明显卡顿？

A: 启用虚拟滚动：

<EnhancedGanttChart
  tasks={tasks}
  virtualScrolling={true}
  visibleTaskCount={50}  // 根据屏幕大小调整
  bufferSize={10}
/>

Q: 拖拽时卡顿/不跟手？

A: 几个优化建议：

1. 关闭不必要的动画：

<EnhancedGanttChart tasks={tasks} enableAnimations={false} />

2. 减少依赖线数量（如果不需要关键路径）：

<EnhancedGanttChart tasks={tasks} enableCriticalPath={false} />

3. 使用 requestAnimationFrame 批量更新：

const handleTaskDrag = (task, e, newStart, newEnd) => {
  requestAnimationFrame(() => {
    // 更新逻辑
  })
}

Q: 初始加载慢？

A: 尝试以下优化：

1. 使用懒加载组件
2. 减少初始任务数量，先加载可见范围的数据
3. 启用代码分割

---

功能问题

Q: 如何添加里程碑？

A: 设置任务的 type 为 milestone：

const tasks = [
  { id: "1", name: "开发", start: "2024-01-01", end: "2024-01-10" },
  { id: "m1", name: "Alpha 发布", start: "2024-01-15", end: "2024-01-15", type: "milestone" },
  { id: "2", name: "测试", start: "2024-01-16", end: "2024-01-25" },
]

Q: 如何让任务支持拖拽但禁止调整大小？

A: 分别控制：

<EnhancedGanttChart
  tasks={tasks}
  enableDragging={true}    // 允许拖拽移动
  enableResizing={false}   // 禁止调整大小
/>

Q: 如何实现任务分组/层级？

A: 使用 parentId 属性：

const tasks = [
  { id: "p1", name: "后端模块", start: "2024-01-01", end: "2024-01-20", type: "project" },
  { id: "t1", name: "数据库设计", start: "2024-01-01", end: "2024-01-05", parentId: "p1" },
  { id: "t2", name: "API 开发", start: "2024-01-06", end: "2024-01-15", parentId: "p1" },
  { id: "t3", name: "单元测试", start: "2024-01-16", end: "2024-01-20", parentId: "p1" },
]

Q: 导出图片有空白边距？

A: 调整导出选项：

const options = {
  padding: 0,        // 移除外边距
  backgroundColor: '#ffffff',
  scale: 2           // 提高清晰度
}

await ganttRef.current?.exportAsPNG(options)

Q: 导出 Excel 中文乱码？

A: 确保使用正确的编码：

import { exportAsExcel } from '@agions/gantt-flow'

await exportAsExcel(tasks, {
  filename: '甘特图',
  encoding: 'utf-8'
})

---

主题问题

Q: 如何自定义任务条颜色？

A: 有两种方式：

方式一：单个任务设置

const tasks = [
  { id: "1", name: "后端", start: "2024-01-01", end: "2024-01-10", color: "#10b981" },
  { id: "2", name: "前端", start: "2024-01-05", end: "2024-01-15", color: "#3b82f6" },
]

方式二：全局设置

:root {
  --gantt-task-bg: #10b981;
}

Q: 如何实现主题跟随系统？

A:

<EnhancedGanttChart options={{ theme: 'auto' }} />

或者手动检测：

const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches
<EnhancedGanttChart options={{ theme: isDark ? 'dark' : 'light' }} />

---

框架相关

Q: React 和 Vue 版本可以同时使用吗？

A: 可以，但建议按需引入：

// React 项目
import { EnhancedGanttChart } from '@agions/gantt-flow/react'

// Vue 项目
import { GanttChart } from '@agions/gantt-flow/vue'

Q: Vue 版本支持 Composition API 吗？

A: 是的，完全支持：

<script setup lang="ts">
import { ref, computed } from 'vue'
import { GanttChart } from '@agions/gantt-flow/vue'

const tasks = ref([...])
const viewMode = ref('week')
</script>

<template>
  <GanttChart :tasks="tasks" v-model:view-mode="viewMode" />
</template>

---

TypeScript 问题

Q: 类型报错？

A: 确保安装了 TypeScript 5.0+：

npm install typescript@latest --save-dev

并检查 tsconfig.json：

{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Q: 某些类型的属性报错？

A: 使用类型断言：

const task = {
  id: "1",
  name: "任务",
  start: "2024-01-01",
  end: "2024-01-10"
} as Task

---

其他问题

Q: 如何获取甘特图的统计数据？

A: 通过 getStats() 方法：

const stats = ganttRef.current?.getStats()
// 返回: { totalTasks, completedTasks, overdueTasks, totalProgress }

Q: 如何禁用某些操作的快捷键？

A: 通过 shortcuts 配置：

<EnhancedGanttChart
  tasks={tasks}
  shortcuts={{
    deleteTask: false,   // 禁用 Delete 键删除任务
    editTask: false     // 禁用 Enter 键编辑任务
  }}
/>

Q: 在 Next.js 中使用有问题？

A: 确保在客户端组件中使用：

// app/gantt/page.tsx
'use client'

import dynamic from 'next/dynamic'

const GanttChart = dynamic(
  () => import('@/components/GanttChart'),
  { ssr: false }
)

---

获取帮助

如果以上 FAQ 无法解决你的问题：

1. GitHub Issues: 提交 Issue
2. GitHub Discussions: 讨论区
3. Stack Overflow: 使用 tag gantt-flow 提问

提问技巧

提交问题时请提供：

• GanttFlow 版本号
• 复现步骤
• 最小可复现代码
• 浏览器/环境信息