v1.0.1 - 升级文档说明 & 增加npm包集成示例
This commit is contained in:
LINING-PC\lining
398
README-EN.md
Normal file
398
README-EN.md
Normal file
@@ -0,0 +1,398 @@
|
||||
# jordium-gantt-vue3
|
||||
|
||||
[](https://badge.fury.io/js/jordium-gantt-vue3)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://vuejs.org/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
|
||||
> Modern Vue 3 Gantt chart component library providing complete solutions for project management and task scheduling
|
||||
|
||||
## 🚀 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
|
||||
|
||||
```bash
|
||||
# npm
|
||||
npm install jordium-gantt-vue3
|
||||
|
||||
# yarn
|
||||
yarn add jordium-gantt-vue3
|
||||
|
||||
# pnpm
|
||||
pnpm add jordium-gantt-vue3
|
||||
```
|
||||
|
||||
## 📄 License
|
||||
|
||||
[MIT License](./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**
|
||||
```typescript
|
||||
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**
|
||||
```typescript
|
||||
// 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**
|
||||
```typescript
|
||||
type Language = 'zh' | 'en' // Supported language types
|
||||
type Locale = 'zh-CN' | 'en-US' // Complete language locale identifiers
|
||||
```
|
||||
|
||||
#### Configuration Types (src/models/configs)
|
||||
|
||||
**TimelineConfig**
|
||||
```typescript
|
||||
interface TimelineConfig {
|
||||
startDate: Date // Timeline start date
|
||||
endDate: Date // Timeline end date
|
||||
zoomLevel: number // Zoom level
|
||||
}
|
||||
```
|
||||
|
||||
**ToolbarConfig**
|
||||
```typescript
|
||||
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**
|
||||
```typescript
|
||||
// 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**
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
```vue
|
||||
<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
|
||||
|
||||
```vue
|
||||
<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
|
||||
|
||||
```vue
|
||||
<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](https://github.com/nelson820125/jordium-gantt-vue3/issues)
|
||||
- 📬 [Submit Gitee Issue](https://gitee.com/jordium/jordium-gantt-vue3/issues)
|
||||
- 📧 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
|
||||
|
||||
```bash
|
||||
# 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](https://github.com/nelson820125/jordium-gantt-vue3)
|
||||
- [Changelog](./CHANGELOG.md)
|
||||
|
||||
> 💡 **Tip**: If this project helps you, please give us a ⭐ Star!
|
||||
Reference in New Issue
Block a user