jordium-gantt-vue3/README-EN.md

jordium-gantt-vue3

🌐 Languages: 📖 English Documentation | 📖 中文文档

Modern Vue 3 Gantt chart component library providing complete solutions for project management and task scheduling

🖼️ Demo Show

🎨 Theme Support

Light Theme

Dark Theme

🚀 Features

• 📊 Complete Functionality: Task management, milestone tracking, dependency relationships, progress visualization
• 🎨 Theme Switching: Built-in light/dark themes with customizable theme variables
• 🖱️ Rich Interactions: Drag adjustment, resizing, double-click editing, context menus
• 🌍 Internationalization: Built-in Chinese/English support with custom language pack capability
• 📱 Responsive: Desktop and mobile compatible with smooth touch experience
• ⚡ High Performance: Virtual scrolling, lazy loading, optimized rendering
• 🔧 Extensible: Rich API interfaces supporting custom components and events
• 💎 Type Safe: Complete TypeScript support for better development experience

📦 Installation

# npm
npm install jordium-gantt-vue3

# yarn  
yarn add jordium-gantt-vue3

# pnpm
pnpm add jordium-gantt-vue3

📄 License

MIT License © 2025 JordiUM

---

💡 Badge Downloads：

• npm version badge：https://badge.fury.io/
• MIT license badge：https://img.shields.io/badge/license-MIT-blue.svg
• Vue version badge：https://img.shields.io/badge/vue-3.x-green.svg
• TypeScript badge：https://img.shields.io/badge/typescript-5.x-blue.svg

📁 Project Structure

jordium-gantt-vue3/
├── src/                      # Source code directory
│   ├── components/           # Core components
│   │   ├── GanttChart.vue   # Main entry component
│   │   ├── TaskList.vue     # Task list
│   │   ├── Timeline.vue     # Timeline
│   │   ├── TaskBar.vue      # Task bar
│   │   ├── MilestonePoint.vue # Milestone
│   │   └── ...              # Other components
│   ├── models/              # Data models
│   │   ├── classes/         # Class definitions
│   │   └── configs/         # Configuration interfaces
│   ├── composables/         # Composable functions
│   ├── styles/              # Style files
│   └── index.ts             # Export entry
├── demo/                    # Development demo
├── dist/                    # Build output
├── docs/                    # Documentation
└── package.json

🔧 API Reference

GanttChart Properties

Property	Type	Default	Description
tasks	Task[]	[]	Task data array
milestones	Task[]	[]	Milestone data array
editComponent	any	-	Custom edit component
useDefaultDrawer	boolean	true	Use default edit drawer
showToolbar	boolean	true	Show toolbar
toolbarConfig	ToolbarConfig	{}	Toolbar configuration
localeMessages	Partial<Messages['zh-CN']>	-	Custom locale messages
onTaskDoubleClick	(task: Task) => void	-	Task double-click event callback
onTaskDelete	(task: Task) => void	-	Task delete event callback
onTaskUpdate	(task: Task) => void	-	Task update event callback
onTaskAdd	(task: Task) => void	-	Task add event callback
onMilestoneSave	(milestone: Task) => void	-	Milestone save event callback
onMilestoneDelete	(milestoneId: number) => void	-	Milestone delete event callback
onMilestoneIconChange	(milestoneId: number, icon: string) => void	-	Milestone icon change event callback
onAddTask	() => void	-	Add task toolbar event callback
onAddMilestone	() => void	-	Add milestone toolbar event callback
onTodayLocate	() => void	-	Locate today toolbar event callback
onExportCsv	() => boolean | void	-	Export CSV toolbar event callback
onExportPdf	() => void	-	Export PDF toolbar event callback
onLanguageChange	(lang: 'zh-CN' | 'en-US') => void	-	Language change toolbar event callback
onThemeChange	(isDark: boolean) => void	-	Theme change toolbar event callback
onFullscreenChange	(isFullscreen: boolean) => void	-	Fullscreen change toolbar event callback

GanttChart Events

Event	Parameters	Description
taskbar-drag-end	task: Task	Task bar drag end
taskbar-resize-end	task: Task	Task bar resize end
milestone-drag-end	milestone: Task	Milestone drag end

Data Types

Core Types (src/models/classes)

Task Type

interface Task {
  id: number                    // Unique task identifier
  name: string                  // Task name
  predecessor?: string          // Predecessor task ID
  assignee?: string            // Assignee
  startDate?: string           // Start date (YYYY-MM-DD format)
  endDate?: string             // End date (YYYY-MM-DD format)
  progress?: number            // Completion progress (0-100)
  estimatedHours?: number      // Estimated hours
  actualHours?: number         // Actual hours
  parentId?: number            // Parent task ID
  children?: Task[]            // Child tasks array (supports nested structure)
  collapsed?: boolean          // Whether child tasks are collapsed
  isParent?: boolean           // Whether it's a parent task
  type?: string               // Task type (task/story/bug/milestone)
  description?: string         // Task description
  icon?: string               // Task icon
  level?: number              // Task level
}

Milestone Type

// Milestone is actually a special usage of Task type
// Task object with type: 'milestone' property
interface Milestone extends Task {
  type: 'milestone'            // Must be 'milestone'
  startDate: string           // Milestone date (required)
  endDate?: string            // End date (optional, usually same as startDate)
}

Language Type

type Language = 'zh' | 'en'   // Supported language types
type Locale = 'zh-CN' | 'en-US' // Complete language locale identifiers

Configuration Types (src/models/configs)

TimelineConfig

interface TimelineConfig {
  startDate: Date              // Timeline start date
  endDate: Date                // Timeline end date
  zoomLevel: number            // Zoom level
}

ToolbarConfig

interface ToolbarConfig {
  showAddTask?: boolean        // Show add task button
  showAddMilestone?: boolean   // Show add milestone button
  showTodayLocate?: boolean    // Show locate today button
  showExportCsv?: boolean      // Show export CSV button
  showExportPdf?: boolean      // Show export PDF button
  showLanguage?: boolean       // Show language switch button
  showTheme?: boolean          // Show theme switch button
  showFullscreen?: boolean     // Show fullscreen toggle button
}

Composable Functions (src/composables)

useI18n Internationalization Tool

// Provides multi-language support
const { 
  locale,           // Current language
  setLocale,        // Switch language
  t,               // Translation function
  formatYearMonth  // Year-month formatting
} = useI18n()

// Supported languages
type Locale = 'zh-CN' | 'en-US'

useMessage Message Tool

// Provides global message notifications
const { showMessage } = useMessage()

// Message types
type MessageType = 'success' | 'error' | 'warning' | 'info'

// Usage example
showMessage('Operation successful', 'success')

💻 Basic Usage

Simple Example

<script setup lang="ts">
import { ref } from 'vue'
import { GanttChart } from 'jordium-gantt-vue3'
import 'jordium-gantt-vue3/dist/style.css'

const tasks = ref([
  {
    id: 1,
    name: 'Project Kickoff',
    startDate: '2025-01-01',
    endDate: '2025-01-15',
    progress: 80,
    assignee: 'John Doe'
  },
  {
    id: 2,
    name: 'Requirements Analysis',
    startDate: '2025-01-16',
    endDate: '2025-01-30',
    progress: 60,
    assignee: 'Jane Smith',
    predecessor: '1'
  }
])

const milestones = ref([
  {
    id: 1,
    name: 'Project Milestone',
    startDate: '2025-01-31',
    type: 'milestone'
  }
])
</script>

<template>
  <div style="height: 600px;">
    <GanttChart 
      :tasks="tasks" 
      :milestones="milestones"
    />
  </div>
</template>

Custom Event Handling

<script setup lang="ts">
import { GanttChart } from 'jordium-gantt-vue3'

// Custom double-click handler
const handleTaskDoubleClick = (task) => {
  console.log('Task double-clicked:', task)
  // Open custom edit interface
  router.push(`/task/${task.id}/edit`)
}

// Custom delete handler
const handleTaskDelete = async (task) => {
  const confirmed = await showConfirm(`Are you sure to delete task "${task.name}"?`)
  if (confirmed) {
    await api.deleteTask(task.id)
    // Refresh task list
    refreshTasks()
  }
}

// Listen to drag events
const handleTaskDragEnd = (task) => {
  console.log('Task drag ended:', task)
  // Save task time changes
  api.updateTask(task)
}
</script>

<template>
  <GanttChart
    :tasks="tasks"
    :on-task-double-click="handleTaskDoubleClick"
    :on-task-delete="handleTaskDelete"
    :use-default-drawer="false"
    @taskbar-drag-end="handleTaskDragEnd"
  />
</template>

Theme and Internationalization

<script setup lang="ts">
import { ref } from 'vue'
import { GanttChart } from 'jordium-gantt-vue3'

// Toolbar configuration
const toolbarConfig = {
  showLanguage: true,
  showTheme: true,
  showAddTask: true,
  showAddMilestone: true,
  showTodayLocate: true,
  showExportCsv: true,
  showExportPdf: true,
  showFullscreen: true
}

// Custom locale messages
const customLocaleMessages = {
  taskName: 'Custom Task Name',
  addTask: 'Custom Add Task'
}

// Handle toolbar events
const handleLanguageChange = (lang) => {
  console.log('Language changed to:', lang)
}

const handleThemeChange = (isDark) => {
  console.log('Theme changed to:', isDark ? 'dark' : 'light')
}
</script>

<template>
  <GanttChart
    :tasks="tasks"
    :milestones="milestones"
    :toolbar-config="toolbarConfig"
    :locale-messages="customLocaleMessages"
    :on-language-change="handleLanguageChange"
    :on-theme-change="handleThemeChange"
  />
</template>

🤝 Contributing & Collaboration

Contributing

We welcome community contributions! If you want to participate in project development:

1. Fork this repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Report Issues

If you find bugs or have feature suggestions:

• 📬 Submit Github Issue
• 📬 Submit Gitee Issue
• 📧 Send email to：ning.li@jordium.com / nelson820125@gmail.com / lining820125@163.com

Business Collaboration

We provide professional technical support and custom development services:

• 🏢 Enterprise Customization: Custom Gantt chart features based on business needs
• 💼 Technical Consulting: Project management system architecture design consultation

Contact Information：

• 📧 Business Email：ning.li@jordium.com / nelson820125@gmail.com

Development Environment

# Clone project
git clone https://github.com/nelson820125/jordium-gantt-vue3.git

# Install dependencies
npm install

# Start development server
npm run dev

# Build library
npm run build:lib

# Run tests
npm run test

---

🔗 Related Links

• GitHub Repository
• Changelog

💡 Tip: If this project helps you, please give us a ⭐ Star!