@lee576/vue3-gantt 1.0.1 → 1.0.3

package/README.en-US.md

@@ -12,6 +12,14 @@ A feature-rich, highly customizable Vue 3 Gantt chart component that supports ta
 
 ## Interface Preview
 
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/34562bf8-0709-44aa-a05d-6e970ea8b57f" alt="Vue3 Gantt Chart - Light Theme" />
+  <p><em>Light Theme - Complete Task Management Interface</em></p>
+  
+  <img src="https://github.com/user-attachments/assets/d6a60ba1-9f5b-479a-b402-68014ec7c935" alt="Vue3 Gantt Chart - Dark Theme" />
+  <p><em>Dark Theme - Eye-friendly Mode</em></p>
+</div>
+
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │                        Vue3 Gantt Professional Component                    │
@@ -27,27 +35,63 @@ A feature-rich, highly customizable Vue 3 Gantt chart component that supports ta
 └─────────────────┴───────────────────────────────────────────────────────────┘
 ```
 
-**Key Features:**
-- 🎯 Left task list + Right Gantt chart timeline
-- 📊 Visual progress bars showing task completion
-- 🔗 Task dependency relationship lines
-- 🎨 Multi-theme support (Light/Dark/Colorful, etc.)
-- 🖱️ Drag to adjust task time and progress
-- 🌍 Multi-language support (Chinese/English/Japanese/Korean/French/German/Spanish/Russian)
-
-## Features
-
-- **Multiple View Modes** - Month, Day, Week, and Hour time granularity views
-- **Task Dependencies** - Support for FS, SS, FF, SF dependency types
-- **Milestone Support** - Diamond markers for key project milestones with dependency support
-- **Theme System** - 5 built-in themes with custom theme support
-- **Internationalization** - Built-in 8 languages, easily extensible
-- **Progress Management** - Visual progress bars with drag-to-adjust
-- **Interactive Operations** - Task dragging, resizing, parent-child linkage
-- **Responsive Design** - Adjustable split panel ratio
-- **High Performance** - Virtual scrolling optimization for large datasets
-
-## Installation
+**Key Highlights:**
+- 🎯 **Dual-Column Layout** - Left task list + Right Gantt timeline, clear information at a glance
+- 📊 **Visual Progress** - Real-time progress bars with drag-to-adjust completion
+- 🔗 **Smart Dependencies** - Four dependency types (FS/SS/FF/SF) with auto-drawn links
+- 🎨 **Multi-Theme** - 5 built-in themes, dark mode and custom theme support
+- 🖱️ **Rich Interactions** - Drag move, resize, parent-child task linkage
+- 🌍 **Internationalization** - Built-in 8 languages, easily extensible
+- ⚡ **High Performance** - Virtual scrolling, handles massive task data effortlessly
+- 💎 **Milestones** - Diamond markers for key nodes with dependency support
+
+## ✨ Core Features
+
+### 📅 Multiple View Modes
+Four time granularities for different scenarios:
+- **Month View** - Long-term project planning, displayed by day
+- **Week View** - Medium-term project tracking, displayed by week
+- **Day View** - Short-term task management, precise to day
+- **Hour View** - Fine task scheduling, displayed by hour
+
+### 🔗 Task Dependency Management
+- **Finish-to-Start (FS)** - Successor task starts after predecessor finishes
+- **Start-to-Start (SS)** - Both tasks start simultaneously
+- **Finish-to-Finish (FF)** - Both tasks finish simultaneously
+- **Start-to-Finish (SF)** - Predecessor finishes after successor starts
+
+### 💎 Milestone Features
+- Diamond icon markers for project key nodes
+- Support as dependency source and target
+- Auto-detect (start time = end time) or manual marking
+
+### 🎨 Theme System
+- 5 beautiful built-in themes (Metro/Dark/Modern/Classic/Colorful)
+- Dark mode support, eye-friendly
+- Complete CSS variable support, easy customization
+- Theme settings auto-saved to browser
+
+### 🌍 Internationalization
+- Built-in 8 languages (CN/EN/JP/KR/FR/DE/ES/RU)
+- Instant switching, no page refresh needed
+- All UI elements fully translated
+- Timeline headers auto-localized
+- Easy to extend new languages
+
+### 🖱️ Interactive Operations
+- **Drag Move** - Modify task start and end dates
+- **Resize** - Drag edges to adjust task duration
+- **Progress Adjust** - Drag triangle slider to adjust completion
+- **Parent-Child Linkage** - Child tasks follow when parent moves
+- **Split Panel** - Adjustable left-right area ratio
+
+### ⚡ Performance Optimization
+- Virtual scroll rendering, supports massive task data
+- Throttled updates, avoids frequent redraws
+- Cached computations, improves response speed
+- On-demand link rendering, optimized drawing performance
+
+## 🚀 Installation
 
 ### Option 1: Install via npm (Recommended)
 
@@ -67,6 +111,7 @@ pnpm add @lee576/vue3-gantt
 ```bash
 # Clone repository
 git clone https://github.com/lee576/vue3-gantt.git
+cd vue3-gantt
 
 # Install dependencies
 npm install
@@ -75,64 +120,118 @@ npm install
 npm run dev
 ```
 
-## Dependencies
+## 📚 Quick Start
 
-- @vueuse/core ^13.0.0
-- dayjs ^1.11.13
-- interactjs ^1.10.27
-- svg.js ^2.7.1
-- vue ^3.5.13
-- zod ^3.24.2
+### 1️⃣ Import Component
 
-## Basic Usage
+```typescript
+import { createApp } from 'vue';
+import Gantt from '@lee576/vue3-gantt';
+import '@lee576/vue3-gantt/style.css';
 
-### 1. Import Component and Styles
+const app = createApp(App);
+app.use(Gantt); // Global registration
+```
 
-```typescript
-import { ref, onMounted } from 'vue';
-import dayjs from 'dayjs';
-// Import Gantt component and types
+Or import in component:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
 import Gantt, { 
   type DataConfig, 
   type StyleConfig, 
-  type EventConfig 
+  type EventConfig,
+  LinkType 
 } from '@lee576/vue3-gantt';
-// Import styles
 import '@lee576/vue3-gantt/style.css';
-import { LinkType } from '@lee576/vue3-gantt';
+</script>
+```
+
+### 2️⃣ Configure Container Height (Important!)
+
+> ⚠️ **Important**: The component **must have an explicit container height** to display properly.
 
-### 2. Configure Component
+**Recommended methods (choose one):**
 
 ```vue
+<!-- Method 1: Use viewport height (Easiest) -->
+<template>
+  <div style="height: 100vh;">
+    <gantt :dataConfig="dataConfig" :styleConfig="styleConfig" />
+  </div>
+</template>
+
+<!-- Method 2: Use fixed height -->
+<template>
+  <div style="height: 800px;">
+    <gantt :dataConfig="dataConfig" :styleConfig="styleConfig" />
+  </div>
+</template>
+
+<!-- Method 3: Flex layout -->
 <template>
-  <gantt 
-    :styleConfig="styleConfig" 
-    :dataConfig="dataConfig" 
-    :eventConfig="eventConfig"
-  />
+  <div style="display: flex; flex-direction: column; height: 100vh;">
+    <div>Header</div>
+    <div style="flex: 1;"> <!-- Auto-fill remaining space -->
+      <gantt :dataConfig="dataConfig" :styleConfig="styleConfig" />
+    </div>
+  </div>
 </template>
 ```
 
-```typescript
-// Style configuration
+<details>
+<summary>💡 Why set height?</summary>
+
+The component uses `height: 100%` internally. According to CSS specifications, percentage height requires the parent element to have an explicit height to calculate. Without a height on the parent container, the component will collapse.
+
+**Solutions:**
+- Use `100vh` (viewport height)
+- Use fixed pixel value (e.g., `800px`)
+- Use Flex layout's `flex: 1`
+- Configure `html, body { height: 100%; }` then use `100%`
+
+</details>
+
+### 3️⃣ Basic Configuration
+
+```vue
+<template>
+  <div style="height: 100vh;">
+    <gantt 
+      :dataConfig="dataConfig" 
+      :styleConfig="styleConfig" 
+      :eventConfig="eventConfig"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import dayjs from 'dayjs';
+import Gantt, { 
+  type DataConfig, 
+  type StyleConfig, 
+  type EventConfig,
+  LinkType 
+} from '@lee576/vue3-gantt';
+import '@lee576/vue3-gantt/style.css';
+
+// 🎨 Style Configuration
 const styleConfig = ref<StyleConfig>({
   headersHeight: 100,  // Header height
   rowHeight: 60,       // Row height
   setBarColor: (row) => {
-    // Custom task bar color
-    const colorMap = {
-      'urgent': 'red',
-      'important': 'blue',
-      'normal': 'gray'
-    };
-    return colorMap[row.level] ?? 'black';
+    // Custom task bar colors
+    const colorMap = { 'urgent': '#ef4444', 'important': '#3b82f6', 'normal': '#6b7280' };
+    return colorMap[row.level] ?? '#000';
   }
 });
 
-// Data configuration
+// 📊 Data Configuration
 const dataConfig = ref<DataConfig>({
-  queryStartDate: '',
-  queryEndDate: '',
+  queryStartDate: dayjs().startOf('month').format('YYYY-MM-DD'),
+  queryEndDate: dayjs().endOf('month').format('YYYY-MM-DD'),
   dataSource: [],
   dependencies: [],
   mapFields: {
@@ -147,42 +246,39 @@ const dataConfig = ref<DataConfig>({
   },
   taskHeaders: [
     { title: 'No.', width: 80, property: 'no', show: true },
-    { title: 'Task Name', width: 190, property: 'task', show: true },
+    { title: 'Task Name', width: 200, property: 'task', show: true },
     { title: 'Priority', width: 90, property: 'priority', show: true },
     { title: 'Start Date', width: 150, property: 'startdate', show: true },
     { title: 'End Date', width: 150, property: 'enddate', show: true },
-    { title: 'Duration', width: 90, property: 'takestime', show: true }
   ]
 });
 
-// Event configuration
+// ⚡ Event Configuration
 const eventConfig = ref<EventConfig>({
-  addRootTask: (row) => console.log('Add root task', row),
-  addSubTask: (task) => console.log('Add subtask', task),
-  removeTask: (task) => console.log('Remove task', task),
-  editTask: (task) => console.log('Edit task', task),
   queryTask: async (startDate, endDate, mode) => {
     // Query task data
-    dataConfig.value.dataSource = await fetchTasks(startDate, endDate);
+    const tasks = await fetchTasks(startDate, endDate);
+    dataConfig.value.dataSource = tasks;
   },
   barDate: (id, startDate, endDate) => {
-    console.log('Task date changed', id, startDate, endDate);
-  },
-  allowChangeTaskDate: (allow) => {
-    console.log('Allow date change', allow);
+    console.log('Task date changed', { id, startDate, endDate });
   },
   updateProgress: (detail) => {
     console.log('Progress updated', detail);
   }
 });
 
+// Initialize and load data
 onMounted(() => {
-  const startDate = dayjs().startOf('month').format('YYYY-MM-DD');
-  const endDate = dayjs().endOf('month').format('YYYY-MM-DD');
-  eventConfig.value.queryTask(startDate, endDate, 'Month');
+  const start = dayjs().startOf('month').format('YYYY-MM-DD');
+  const end = dayjs().endOf('month').format('YYYY-MM-DD');
+  eventConfig.value.queryTask?.(start, end, 'month');
 });
+</script>
 ```
 
+## 📖 Configuration Guide
+
 ## Configuration Details
 
 ### StyleConfig

package/README.md

@@ -21,47 +21,78 @@
 
 ## 界面预览
 
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                        Vue3 Gantt 专业组件                                  │
-├─────────────────┬───────────────────────────────────────────────────────────┤
-│ 任务名称        │ 12/01  12/02  12/03  12/04  12/05  12/06  12/07  12/08   │
-├─────────────────┼───────────────────────────────────────────────────────────┤
-│ 主任务1 - 项目规划│ ████████████████████████████████████████████ 85%        │
-│   子任务1.1 - 需求│   ████████████ 100%                                     │
-│ 主任务2 - 开发阶段│       ████████████████████████████ 60%                  │
-│ 主任务3 - 测试阶段│             ████████████████ 45%                        │
-│ 主任务4 - 部署上线│                   ████████ 30%                          │
-│ 主任务5 - 维护优化│                       ████ 0%                           │
-└─────────────────┴───────────────────────────────────────────────────────────┘
-```
-
-**主要特点：**
-- 🎯 左侧任务列表 + 右侧甘特图时间轴
-- 📊 可视化进度条显示任务完成度
-- 🔗 任务间依赖关系连线
-- 🎨 多主题支持（浅色/深色/彩色等）
-- 🖱️ 拖拽调整任务时间和进度
-- 🌍 多语言支持（中文/English/日本語/한국어/Français/Deutsch/Español/Русский）
-
-## 特性
+<div align="center">
+  <img src="https://github.com/user-attachments/assets/34562bf8-0709-44aa-a05d-6e970ea8b57f" alt="Vue3 Gantt Chart - Light Theme" />
+  <p><em>浅色主题 - 完整的任务管理界面</em></p>
+  
+  <img src="https://github.com/user-attachments/assets/d6a60ba1-9f5b-479a-b402-68014ec7c935" alt="Vue3 Gantt Chart - Dark Theme" />
+  <p><em>深色主题 - 护眼模式</em></p>
+</div>
 
-- **多视图模式** - 支持月、日、周、时四种时间粒度视图
-- **任务依赖关系** - 支持 FS、SS、FF、SF 四种依赖类型
-- **里程碑功能** - 菱形图标标记项目关键节点，支持作为依赖源和目标
-- **主题系统** - 内置 5 种主题，支持自定义主题
-- **国际化支持** - 内置 8 种语言，可扩展更多语言
-- **进度管理** - 可视化进度条，支持拖拽调整进度
-- **交互操作** - 支持任务拖拽、调整大小、父子任务联动
-- **响应式设计** - 可调整分割面板比例
-- **高性能** - 虚拟滚动优化，支持大量任务数据
+```
 
-## 安装
+**核心亮点：**
+- 🎯 **双栏布局** - 左侧任务列表 + 右侧甘特图时间轴，信息一目了然
+- 📊 **可视化进度** - 实时进度条显示，支持拖拽调整完成度
+- 🔗 **智能依赖** - 四种依赖类型（FS/SS/FF/SF），自动绘制连线
+- 🎨 **多主题切换** - 5种内置主题，支持深色模式和自定义主题
+- 🖱️ **交互丰富** - 拖拽移动、调整大小、父子任务联动
+- 🌍 **国际化** - 内置8种语言，轻松扩展更多语言
+- ⚡ **高性能** - 虚拟滚动优化，轻松处理大量任务数据
+- 💎 **里程碑** - 菱形标记关键节点，支持依赖关系
+
+## ✨ 核心特性
+
+### 📅 多视图模式
+支持四种时间粒度，满足不同场景需求：
+- **月视图** - 长期项目规划，按天显示
+- **周视图** - 中期项目跟踪，按周显示  
+- **日视图** - 短期任务管理，精确到天
+- **时视图** - 精细任务调度，按小时显示
+
+### 🔗 任务依赖管理
+- **完成-开始 (FS)** - 前置任务完成后，后续任务才能开始
+- **开始-开始 (SS)** - 两个任务同时开始
+- **完成-完成 (FF)** - 两个任务同时完成
+- **开始-完成 (SF)** - 后续任务开始后，前置任务才能完成
+
+### 💎 里程碑功能
+- 菱形图标标记项目关键节点
+- 支持作为依赖关系的源和目标
+- 自动识别（开始时间=结束时间）或手动标记
+
+### 🎨 主题系统
+- 内置 5 种精美主题（Metro/Dark/Modern/Classic/Colorful）
+- 支持深色模式，护眼舒适
+- 完整的 CSS 变量支持，轻松自定义主题
+- 主题设置自动保存到浏览器
+
+### 🌍 国际化支持
+- 内置 8 种语言（中/英/日/韩/法/德/西/俄）
+- 即时切换，无需刷新页面
+- 所有界面元素完整翻译
+- 时间轴表头自动本地化
+- 易于扩展新语言
+
+### 🖱️ 交互操作
+- **拖拽移动** - 修改任务开始和结束日期
+- **调整大小** - 拖拽边缘调整任务时长
+- **进度调整** - 拖拽三角滑块调整完成度
+- **父子联动** - 父任务移动时子任务自动跟随
+- **分割面板** - 可调整左右区域比例
+
+### ⚡ 性能优化
+- 虚拟滚动渲染，支持海量任务数据
+- 节流更新机制，避免频繁重绘
+- 计算结果缓存，提升响应速度
+- 按需渲染连线，优化绘制性能
+
+## 🚀 安装使用
 
 ### 方式一：通过 npm 安装（推荐）
 
 ```bash
-# 使用 npm 安装
+# 使用 npm
 npm install @lee576/vue3-gantt
 
 # 或使用 yarn
@@ -74,8 +105,9 @@ pnpm add @lee576/vue3-gantt
 ### 方式二：从源码构建
 
 ```bash
-# 克隆项目
+# 克隆仓库
 git clone https://github.com/lee576/vue3-gantt.git
+cd vue3-gantt
 
 # 安装依赖
 npm install
@@ -84,64 +116,118 @@ npm install
 npm run dev
 ```
 
-## 依赖项
+## 📚 快速开始
 
-- @vueuse/core ^13.0.0
-- dayjs ^1.11.13
-- interactjs ^1.10.27
-- svg.js ^2.7.1
-- vue ^3.5.13
-- zod ^3.24.2
+### 1️⃣ 引入组件
 
-## 基本使用
+```typescript
+import { createApp } from 'vue';
+import Gantt from '@lee576/vue3-gantt';
+import '@lee576/vue3-gantt/style.css';
 
-### 1. 引入组件和样式
+const app = createApp(App);
+app.use(Gantt); // 全局注册
+```
 
-```typescript
-import { ref, onMounted } from 'vue';
-import dayjs from 'dayjs';
-// 引入甘特图组件和类型
+或在组件中单独引入：
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
 import Gantt, { 
   type DataConfig, 
   type StyleConfig, 
-  type EventConfig 
+  type EventConfig,
+  LinkType 
 } from '@lee576/vue3-gantt';
-// 引入样式文件
 import '@lee576/vue3-gantt/style.css';
-import { LinkType } from '@lee576/vue3-gantt';
+</script>
+```
+
+### 2️⃣ 配置容器高度（重要！）
 
-### 2. 配置组件
+> ⚠️ **注意**：组件**必须有明确的容器高度**才能正常显示。
+
+**推荐方法（任选其一）：**
 
 ```vue
+<!-- 方法1：使用视口高度（最简单） -->
+<template>
+  <div style="height: 100vh;">
+    <gantt :dataConfig="dataConfig" :styleConfig="styleConfig" />
+  </div>
+</template>
+
+<!-- 方法2：使用固定高度 -->
 <template>
-  <gantt 
-    :styleConfig="styleConfig" 
-    :dataConfig="dataConfig" 
-    :eventConfig="eventConfig"
-  />
+  <div style="height: 800px;">
+    <gantt :dataConfig="dataConfig" :styleConfig="styleConfig" />
+  </div>
+</template>
+
+<!-- 方法3：Flex 布局 -->
+<template>
+  <div style="display: flex; flex-direction: column; height: 100vh;">
+    <div>Header</div>
+    <div style="flex: 1;"> <!-- 自动填充剩余空间 -->
+      <gantt :dataConfig="dataConfig" :styleConfig="styleConfig" />
+    </div>
+  </div>
 </template>
 ```
 
-```typescript
-// 样式配置
+<details>
+<summary>💡 为什么需要设置高度？</summary>
+
+组件内部使用了 `height: 100%`，根据 CSS 规范，百分比高度需要父元素有明确的高度才能计算。如果父容器没有设置高度，组件会高度坑塌。
+
+**解决方案**：
+- 使用 `100vh`（视口高度）
+- 使用固定像素值（如 `800px`）
+- 使用 Flex 布局的 `flex: 1`
+- 配置 `html, body { height: 100%; }` 后使用 `100%`
+
+</details>
+
+### 3️⃣ 基本配置
+
+```vue
+<template>
+  <div style="height: 100vh;">
+    <gantt 
+      :dataConfig="dataConfig" 
+      :styleConfig="styleConfig" 
+      :eventConfig="eventConfig"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import dayjs from 'dayjs';
+import Gantt, { 
+  type DataConfig, 
+  type StyleConfig, 
+  type EventConfig,
+  LinkType 
+} from '@lee576/vue3-gantt';
+import '@lee576/vue3-gantt/style.css';
+
+// 🎨 样式配置
 const styleConfig = ref<StyleConfig>({
   headersHeight: 100,  // 表头高度
   rowHeight: 60,       // 行高
   setBarColor: (row) => {
     // 自定义任务条颜色
-    const colorMap = {
-      '紧急': 'red',
-      '重要': 'blue',
-      '一般': 'gray'
-    };
-    return colorMap[row.level] ?? 'black';
+    const colorMap = { '紧急': '#ef4444', '重要': '#3b82f6', '一般': '#6b7280' };
+    return colorMap[row.level] ?? '#000';
   }
 });
 
-// 数据配置
+// 📊 数据配置
 const dataConfig = ref<DataConfig>({
-  queryStartDate: '',
-  queryEndDate: '',
+  queryStartDate: dayjs().startOf('month').format('YYYY-MM-DD'),
+  queryEndDate: dayjs().endOf('month').format('YYYY-MM-DD'),
   dataSource: [],
   dependencies: [],
   mapFields: {
@@ -156,40 +242,35 @@ const dataConfig = ref<DataConfig>({
   },
   taskHeaders: [
     { title: '序号', width: 80, property: 'no', show: true },
-    { title: '任务名称', width: 190, property: 'task', show: true },
+    { title: '任务名称', width: 200, property: 'task', show: true },
     { title: '优先级', width: 90, property: 'priority', show: true },
     { title: '开始时间', width: 150, property: 'startdate', show: true },
     { title: '结束时间', width: 150, property: 'enddate', show: true },
-    { title: '耗时', width: 90, property: 'takestime', show: true }
   ]
 });
 
-// 事件配置
+// ⚡ 事件配置
 const eventConfig = ref<EventConfig>({
-  addRootTask: (row) => console.log('添加根任务', row),
-  addSubTask: (task) => console.log('添加子任务', task),
-  removeTask: (task) => console.log('删除任务', task),
-  editTask: (task) => console.log('编辑任务', task),
   queryTask: async (startDate, endDate, mode) => {
     // 查询任务数据
-    dataConfig.value.dataSource = await fetchTasks(startDate, endDate);
+    const tasks = await fetchTasks(startDate, endDate);
+    dataConfig.value.dataSource = tasks;
   },
   barDate: (id, startDate, endDate) => {
-    console.log('任务日期变更', id, startDate, endDate);
-  },
-  allowChangeTaskDate: (allow) => {
-    console.log('允许修改日期', allow);
+    console.log('任务日期变更', { id, startDate, endDate });
   },
   updateProgress: (detail) => {
     console.log('进度更新', detail);
   }
 });
 
+// 初始化加载数据
 onMounted(() => {
-  const startDate = dayjs().startOf('month').format('YYYY-MM-DD');
-  const endDate = dayjs().endOf('month').format('YYYY-MM-DD');
-  eventConfig.value.queryTask(startDate, endDate, '月');
+  const start = dayjs().startOf('month').format('YYYY-MM-DD');
+  const end = dayjs().endOf('month').format('YYYY-MM-DD');
+  eventConfig.value.queryTask?.(start, end, '月');
 });
+</script>
 ```
 
 ## 配置详解