# vueGantt

**Repository Path**: cpsoft13/vueGantt

## Basic Information

- **Project Name**: vueGantt
- **Description**: 基于Vue的甘特图组件
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-03-10
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue Gantt

功能强大的 Vue 3 甘特图组件库。

## 应用界面预览

### 主界面

![甘特图主界面](images/gantt-main.svg)

显示完整的任务列表和时间轴视图，支持：
- 任务列表的详细/简洁模式切换
- 时间轴缩放（50%-200%）
- 同步滚动
- 父子任务支持
- 任务名称列宽度可调整（拖动右边框）

### 任务编辑

![任务编辑弹窗](images/gantt-edit.svg)

任务点击或双击后显示编辑弹窗，支持：
- 基本信息编辑（名称、日期、进度等）
- 里程碑设置（开始/结束里程碑）
- 依赖关系管理
- 负责人分配

### 任务栏视图

![任务栏和里程碑](images/gantt-tasks.svg)

任务栏显示详细信息：
- 任务进度条形图
- 基线对比显示
- 里程碑标记（开始/结束）
- 任务依赖连线

### 任务栏Tooltip

![任务栏Tooltip](images/gantt-tooltip.svg)

悬停任务栏显示详细信息：
- 任务名称和时间范围
- 进度和状态
- 前置任务信息
- 里程碑信息（如果有）

## 安装

```bash
npm install vue-gantt
```

## 快速开始

```vue
<template>
  <Gantt
    ref="ganttRef"
    :project-id="1"
    :tasks="tasks"
    :users="users"
    :current-user="currentUser"
    @task-click="handleTaskClick"
    @task-dblclick="handleTaskDblClick"
  />
  <button @click="setBaseline">设置项目基线</button>
</template>

<script setup>
import { ref } from 'vue'
import { Gantt } from 'vue-gantt'

const ganttRef = ref(null)

const tasks = ref([
  {
    id: 1,
    projectId: 1,
    type: 'normal',
    name: '任务示例',
    parentId: null,
    level: 0,
    sortOrder: 1,
    startDate: '2026-03-01',
    endDate: '2026-03-10',
    actualStartDate: '',
    actualEndDate: '',
    baselineStart: '',
    baselineEnd: '',
    progress: 50,
    status: 'ongoing',
    assigneeId: 1,
    predecessorIds: [],
    successorIds: [],
    milestoneType: null,
    milestoneName: null,
    remark: '',
    isExpanded: true
  }
])

const users = ref([
  { id: 1, name: '张三' },
  { id: 2, name: '李四' }
])

const currentUser = ref({ id: 1, name: '张三' })

const handleTaskClick = (task) => {
  console.log('Clicked:', task)
}

const handleTaskDblClick = (task) => {
  console.log('Double-clicked:', task)
}

// 设置项目基线
const setBaseline = () => {
  ganttRef.value?.setProjectBaseline()
}
</script>
```

## 特性

- 任务列表支持完整模式和简洁模式切换
- 时间轴支持缩放 (50%-200%)
- 同步滚动
- 父子任务支持
- 里程碑显示
- 基线对比
- 依赖关系连线
- 拖拽排序
- 任务编辑弹窗
- **任务名称列宽度可调整（拖动右边框）**
- **列分隔线显示**
- **项目基线设置**
- **深色/浅色主题切换（可配置显示）**
- **高效的依赖关系管理（DependencyGraph数据结构）**

## Props

| 属性 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| projectId | number | 是 | - | 项目ID |
| tasks | Task[] | 是 | [] | 任务列表 |
| users | User[] | 否 | [] | 用户列表 |
| currentUser | User | 否 | null | 当前用户 |
| readonly | boolean | 否 | false | 只读模式 |
| showThemeToggle | boolean | 否 | false | 是否显示主题切换按钮 |

## Events

| 事件名 | 参数 | 说明 |
|--------|------|------|
| task-click | task: Task | 点击任务 |
| task-dblclick | task: Task | 双击任务 |
| task-update | task: Task | 任务更新 |
| task-create | task: Partial<Task> | 任务创建 |
| task-delete | taskId: number | 任务删除 |
| task-order-change | orders: TaskOrder[] | 排序变化 |
| baseline-change | tasks: Task[] | 基线设置变化（需通知后端保存） |
| filter-change | filters: Filter | 筛选变化 |

## Expose

| 方法名 | 说明 |
|--------|------|
| scrollToToday | 滚动到今天 |
| zoomIn | 放大 |
| zoomOut | 缩小 |
| resetZoom | 重置缩放 |
| refresh | 刷新数据 |
| **setProjectBaseline** | **设置项目基线（将当前计划时间保存为基线）** |

## 数据类型

### Task

```typescript
interface Task {
  id: number
  projectId: number
  type: 'normal' | 'parent' | string
  name: string
  parentId: number | null
  level: number
  sortOrder: number
  startDate: string
  endDate: string
  actualStartDate: string
  actualEndDate: string
  baselineStart: string      // 基线开始日期
  baselineEnd: string        // 基线结束日期
  progress: number
  status: 'pending' | 'ongoing' | 'completed' | 'overdue'
  assigneeId: number
  predecessorIds: number[]
  successorIds: number[]
  milestoneType: 'start' | 'end' | null  // 里程碑类型
  milestoneName: string | null           // 里程碑名字
  remark: string
  isExpanded: boolean
  children?: Task[]
}
```

### User

```typescript
interface User {
  id: number
  name: string
  avatar?: string
}
```

## 使用说明

### 调整任务名称列宽度

将鼠标悬停在"任务名称"列标题的**右边框**上，光标变为拖动图标时，按住左键拖动即可调整列宽。

### 设置项目基线

点击顶部工具栏的"📏 设置基线"按钮，会弹出确认对话框。确认后，当前所有任务的开始日期和结束日期会被保存为基线。

基线保存后，时间轴会自动显示基线对比条（灰色条形），方便跟踪计划与实际进度的差异。

```vue
<template>
  <Gantt ref="ganttRef" :tasks="tasks" />
</template>

<script setup>
import { ref } from 'vue'
import { Gantt } from 'vue-gantt'

const ganttRef = ref(null)

// 点击按钮后会弹出确认对话框
const saveBaseline = () => {
  ganttRef.value?.setProjectBaseline()
}
</script>
```

### 主题切换

组件支持深色/浅色主题切换。主题切换按钮默认隐藏，需要通过 `showThemeToggle` prop 配置显示：

```vue
<template>
  <Gantt
    ref="ganttRef"
    :tasks="tasks"
    :showThemeToggle="true"
  />
</template>

<script setup>
import { ref } from 'vue'
import { Gantt } from 'vue-gantt'

const ganttRef = ref(null)
const tasks = ref([])
</script>
```

## 依赖关系管理

### 架构设计

本项目使用 **DependencyGraph** 数据结构来管理任务之间的依赖关系，提供高效的查询性能和完整的依赖分析功能。

### 核心优势

| 特性 | 传统方式 | DependencyGraph |
|------|----------|-----------------|
| 查找前置任务 | O(n) 数组遍历 | O(1) 直接访问 |
| 查找后继任务 | O(n) 数组遍历 | O(1) 直接访问 |
| 更新依赖关系 | 手动维护数组 | 自动同步 |
| 循环检测 | 重建图结构 | 直接查询 |
| 数据一致性 | 可能不一致 | 保证一致 |

### 数据结构

```typescript
class DependencyGraph {
  // 任务ID -> 前置任务ID集合
  private predecessors: Map<number, Set<number>>
  // 任务ID -> 后继任务ID集合
  private successors: Map<number, Set<number>>
}
```

### 主要功能

1. **高效查询**
   - `getPredecessors(taskId)` - 获取所有前置任务
   - `getSuccessors(taskId)` - 获取所有后继任务

2. **依赖管理**
   - `addDependency(predId, succId)` - 添加依赖关系
   - `removeDependency(predId, succId)` - 删除依赖关系
   - `setPredecessors(taskId, newIds)` - 替换所有前置任务

3. **循环检测**
   - `hasCycle(taskId)` - 检查是否存在循环依赖
   - `wouldCreateCycle(predId, succId)` - 预检查添加依赖是否会造成循环

4. **传递查询**
   - `getAllAncestors(taskId)` - 获取所有间接前置任务
   - `getAllDescendants(taskId)` - 获取所有间接后继任务

5. **拓扑排序**
   - `topologicalSort()` - 获取任务的拓扑排序

### 折叠状态处理

当父任务折叠时，依赖线会自动调整：

- **子任务被折叠**：依赖线绘制到父任务
- **子任务展开**：依赖线精确绘制到具体子任务
- **多层嵌套**：递归查找最近可见祖先

### 使用示例

依赖关系通过任务的 `predecessorIds` 字段定义：

```typescript
const tasks = [
  {
    id: 1,
    name: '需求分析',
    predecessorIds: [],  // 无前置任务
    successorIds: [2, 3]  // 后继任务（自动计算）
  },
  {
    id: 2,
    name: 'UI设计',
    predecessorIds: [1],  // 依赖任务1
    successorIds: [4]
  },
  {
    id: 3,
    name: '后端开发',
    predecessorIds: [1],  // 依赖任务1
    successorIds: [4]
  },
  {
    id: 4,
    name: '联调测试',
    predecessorIds: [2, 3],  // 依赖任务2和3
    successorIds: []
  }
]
```

**注意**：`successorIds` 会由 DependencyGraph 自动维护，无需手动设置。

### 最佳实践

1. **避免循环依赖**：在添加依赖前检查 `wouldCreateCycle()`
2. **批量更新**：使用 `setPredecessors()` 而不是多次调用 `addDependency()`
3. **删除任务**：调用 `removeTask()` 清理所有相关依赖
4. **序列化**：通过 Task 的 `predecessorIds` 字段保存，DependencyGraph 会自动重建