+
+
```
-## 🤝 Contributing & Collaboration
+#### Example 3: Hide Toolbar, Custom Control Buttons with Event Binding
-### Contributing
+```vue
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-We welcome community contributions! If you want to participate in project development:
+
```
---
-**🔗 Related Links**
-- [GitHub Repository](https://github.com/nelson820125/jordium-gantt-vue3)
-- [Changelog](./CHANGELOG.md)
+### Task Management
-> 💡 **Tip**: If this project helps you, please give us a ⭐ Star!
+Tasks are the core elements of the Gantt chart. The component provides complete CRUD operation support for tasks, including adding, editing, deleting tasks, and rich interactive events.
+
+#### Task Data Structure
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `id` | `number` | ✅ | - | Unique task identifier |
+| `name` | `string` | ✅ | - | Task name |
+| `startDate` | `string` | - | - | Start date, format: 'YYYY-MM-DD' or 'YYYY-MM-DD HH:mm' |
+| `endDate` | `string` | - | - | End date, format: 'YYYY-MM-DD' or 'YYYY-MM-DD HH:mm' |
+| `progress` | `number` | - | `0` | Task progress, range 0-100 |
+| `predecessor` | `number[]` | - | - | Array of predecessor task IDs, standard format: `[1, 2, 3]` **Compatible formats**: Also supports string `'1,2,3'` or string array `['1', '2', '3']`, component will auto-parse |
+| `assignee` | `string` | - | - | Task assignee |
+| `avatar` | `string` | - | - | Avatar URL of task assignee |
+| `estimatedHours` | `number` | - | - | Estimated hours |
+| `actualHours` | `number` | - | - | Actual hours |
+| `parentId` | `number` | - | - | Parent task ID, used for task grouping |
+| `children` | `Task[]` | - | - | Array of child tasks |
+| `collapsed` | `boolean` | - | `false` | Whether child tasks are collapsed |
+| `isParent` | `boolean` | - | - | Whether this is a parent task |
+| `type` | `string` | - | - | Task type, 'milestone' for milestone, 'milestone-group' for milestone group |
+| `description` | `string` | - | - | Task description |
+| `icon` | `string` | - | `'diamond'` | Task icon (for milestones), options: 'diamond', 'flag', 'star', 'rocket', etc. |
+| `level` | `number` | - | `0` | Task level (auto-calculated) |
+| `isTimerRunning` | `boolean` | - | `false` | Whether timer is running |
+| `timerStartTime` | `number` | - | - | Timer start time (timestamp) |
+| `timerEndTime` | `number` | - | - | Timer end time (timestamp) |
+| `timerStartDesc` | `string` | - | - | Description filled when timer starts |
+| `timerElapsedTime` | `number` | - | `0` | Elapsed time (milliseconds) |
+| `isEditable` | `boolean` | - | `true` | Whether individual task is editable (draggable, resizable), overrides global `allowDragAndResize` |
+| `[key: string]` | `unknown` | - | - | Supports custom property extensions, can add any additional fields |
+
+> **Custom Property Extensions**: The Task interface supports adding arbitrary custom fields, such as: `priority`, `tags`, `status`, `department`, and other business-related fields.
+>
+> **Predecessor Field Notes**:
+> - **Standard format** (recommended): `predecessor: [1, 2, 3]` - number array
+> **Compatible format 1**: `predecessor: '1,2,3'` - comma-separated string
+> - **Compatible format 2**: `predecessor: ['1', '2', '3']` - string array
+> - Component will automatically parse all formats into number array
+> - No predecessors: use empty array `[]`, empty string `''`, or don't set this field
+
+#### Task-Related Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tasks` | `Task[]` | `[]` | Array of task data |
+| `useDefaultDrawer` | `boolean` | `true` | Whether to use built-in task edit drawer (TaskDrawer) |
+| `taskBarConfig` | `TaskBarConfig` | `{}` | Task bar style configuration, see [TaskBarConfig Configuration](#taskbarconfig-configuration) |
+| `taskListConfig` | `TaskListConfig` | `undefined` | Task list configuration, see [TaskListConfig Configuration](#tasklistconfig-configuration) |
+| `autoSortByStartDate` | `boolean` | `false` | Whether to automatically sort tasks by start date |
+
+**Configuration Notes**:
+- **Default mode**: `useDefaultDrawer=true` (default), double-click task to auto-open built-in TaskDrawer
+- **Custom editor**: `useDefaultDrawer=false` disables built-in drawer, listen to `@task-double-click` event to open custom editor
+- **Read-only mode**: `useDefaultDrawer=false` and don't listen to `@task-double-click` event, user double-click task has no response
+
+#### Task Events
+
+> **💡 Event-Driven Architecture**: Component adopts pure event-driven design. All user operations (add, edit, delete, drag, etc.) will trigger corresponding events for easy external listening and handling.
+
+| Event Name | Parameters | When Triggered | Description |
+|------------|------------|----------------|-------------|
+| `add-task` | - | When clicking toolbar "Add Task" button | Can be used for custom add task logic. If `useDefaultDrawer=true`, component will auto-open built-in TaskDrawer |
+| `task-click` | `(task: Task, event: MouseEvent) => void` | When clicking task bar | Triggered on single-click task |
+| `task-double-click` | `(task: Task) => void` | When double-clicking task bar | Double-click task **always triggers**. When `useDefaultDrawer=true`, component will additionally open built-in editor; when `false`, won't open. Event triggering is independent of property value |
+| `task-added` | `{ task: Task }` | After task added | Triggered after adding task via built-in TaskDrawer. **Note**: Component has auto-updated `tasks` data, external only needs to listen to this event for additional processing (like calling API to save) |
+| `task-updated` | `{ task: Task }` | After task updated | Triggered after updating task via built-in TaskDrawer or drag. **Note**: Component has auto-updated `tasks` data, external only needs to listen to this event for additional processing |
+| `task-deleted` | `{ task: Task }` | After task deleted | Triggered after deleting task via built-in TaskDrawer. **Note**: Component has auto-updated `tasks` data, external only needs to listen to this event for additional processing |
+| `taskbar-drag-end` | `(task: Task) => void` | When task bar drag ends | Task position changed, startDate and endDate updated. **Note**: Component has auto-updated `tasks` data |
+| `taskbar-resize-end` | `(task: Task) => void` | When task bar resize ends | Task duration changed, endDate updated. **Note**: Component has auto-updated `tasks` data |
+| `predecessor-added` | `{ targetTask: Task, newTask: Task }` | After adding predecessor via context menu | `targetTask` is the task to which predecessor is added, `newTask` is the newly created predecessor task |
+| `successor-added` | `{ targetTask: Task, newTask: Task }` | After adding successor via context menu | `targetTask` is the original task, `newTask` is the newly created successor task (its predecessor already contains targetTask.id) |
+| `timer-started` | `(task: Task) => void` | When task timer starts | Start recording task hours |
+| `timer-stopped` | `(task: Task) => void` | When task timer stops | Stop recording task hours |
+
+**Data Synchronization Notes**:
+- ✅ **Component auto-updates internally**: For all task CRUD operations, component will auto-update `props.tasks` data
+- ✅ **Events are for notification only**: External event listeners are mainly for: showing messages, calling backend APIs, updating other related data, etc.
+- ❌ **Avoid duplicate operations**: Don't modify `tasks` data again in event handlers, otherwise it will cause duplicate updates
+
+#### Example 1: Basic Task Operations
+
+```vue
+
+
+
+
+
+
+
+```
+
+#### Example 2: Task Dependencies (Predecessors/Successors)
+
+Tasks can configure predecessors via the `predecessor` field, and the component will automatically draw dependency lines:
+
+```vue
+
+
+
+
+
+```
+
+**Dependency Relationship Notes**:
+- **`predecessor` field supports multiple formats**:
+ - Standard format (recommended): `[1, 2, 3]` - number array
+ - Compatible format 1: `'1,2,3'` - comma-separated string
+ - Compatible format 2: `['1', '2', '3']` - string array
+ - Component will automatically parse all formats
+- Predecessor task: Task that must be completed first (e.g., design must be done before development)
+- Successor task: Task that depends on current task (current task is a predecessor for other tasks)
+- Component will automatically draw dependency lines from predecessor tasks to dependent tasks
+- Can add/delete predecessor and successor tasks via built-in context menu
+- When deleting tasks via built-in menu, component will automatically clean up related dependency references
+- No predecessors: use empty array `[]`, empty string `''`, or don't set `predecessor` field
+
+#### Example 3: Hide Toolbar, Use Custom Buttons to Trigger Events
+
+Suitable for scenarios requiring complete custom control bar:
+
+```vue
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+> **💡 Flexibility Design**:
+> - Show toolbar + default editor: Simplest out-of-the-box approach
+> - Hide toolbar + custom buttons + default editor: Custom control bar style while keeping default edit functionality
+> - Hide toolbar + custom buttons + custom editor: Fully customize all interaction logic
+
+### Milestone Management
+
+### Milestone Management
+
+Milestones are used to mark important time points in a project, such as project kickoff, phase completion, product release, etc. The component provides flexible milestone editing configuration, using the built-in MilestoneDialog by default, and also supports fully custom editing behavior.
+
+> **Note**: Milestones and tasks are independent data collections with no direct association. Milestones are managed independently through the `milestones` prop.
+
+#### Milestone Data Structure
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `id` | `number` | ✅ | - | Unique milestone identifier |
+| `name` | `string` | ✅ | - | Milestone name |
+| `startDate` | `string` | ✅ | - | Milestone date, format: 'YYYY-MM-DD' or 'YYYY-MM-DD HH:mm' |
+| `endDate` | `string` | - | - | End date (usually not needed for milestones, auto-set to same as startDate) |
+| `assignee` | `string` | - | - | Assignee |
+| `type` | `string` | ✅ | `'milestone'` | Type identifier, must be set to 'milestone' |
+| `icon` | `string` | - | `'diamond'` | Milestone icon, options: 'diamond', 'flag', 'star', 'rocket', etc. |
+| `description` | `string` | - | - | Milestone description |
+
+> **Note**: The `milestones` prop type is `Task[]`, ensure each milestone object's `type` field is set to `'milestone'`.
+
+#### Milestone-Related Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `milestones` | `Task[]` | `[]` | Array of milestone data (type is Task[], ensure type='milestone') |
+| `useDefaultMilestoneDialog` | `boolean` | `true` | Whether to use built-in milestone edit dialog (MilestoneDialog) |
+
+**Configuration Notes**:
+- **Default mode**: `useDefaultMilestoneDialog=true` (default), double-click milestone to auto-open built-in MilestoneDialog
+- **Disable editor**: `useDefaultMilestoneDialog=false`, double-click milestone has no response (component doesn't open any editor)
+- **Custom editor**: Can listen to `onMilestoneDoubleClick` callback or related events to implement custom editing logic
+
+> **💡 Differences Between Milestones and Tasks**:
+> - Milestone data is managed independently via `milestones` prop, separate from `tasks`
+> - Milestone object's `type` field must be set to `'milestone'`
+> - Milestones don't support child tasks, dependency relationships, and other complex structures
+> - Milestones are mainly used to mark key time points
+
+#### Milestone Callbacks (Backward Compatible)
+
+> **⚠️ Deprecated**: Please use the new event-driven API (see "Milestone Events" section below)
+
+
+#### Milestone Events
+
+> **💡 Event-Driven Architecture**: Milestone management adopts event-driven design. Using event API is recommended over callback functions.
+
+| Event Name | Parameters | When Triggered | Description |
+|------------|------------|----------------|-------------|
+| `add-milestone` | - | When clicking toolbar "Add Milestone" button | Can be used for custom add milestone logic. If `useDefaultMilestoneDialog=true`, component will auto-open built-in MilestoneDialog |
+| `milestone-saved` | `(milestone: Task) => void` | After milestone saved (add or edit) | Triggered after saving milestone via built-in MilestoneDialog. **Note**: Component has auto-updated `milestones` data, external only needs to listen to this event for additional processing (like calling API to save) |
+| `milestone-deleted` | `{ milestoneId: number }` | After milestone deleted | Triggered after deleting milestone via built-in MilestoneDialog. **Note**: Component has auto-updated `milestones` data, external only needs to listen to this event for additional processing |
+| `milestone-icon-changed` | `{ milestoneId: number, icon: string }` | After milestone icon changed | Triggered after modifying icon via built-in MilestoneDialog |
+| `milestone-drag-end` | `(milestone: Task) => void` | When milestone drag ends | Milestone date updated. **Note**: Component has auto-updated `milestones` data |
+
+**Data Synchronization Notes**:
+- ✅ **Component auto-updates internally**: For all milestone CRUD operations, component will auto-update `props.milestones` data
+- ✅ **Events are for notification only**: External event listeners are mainly for: showing messages, calling backend APIs, updating other related data, etc.
+- ❌ **Avoid duplicate operations**: Don't modify `milestones` data again in event handlers, otherwise it will cause duplicate updates
+
+#### Example 1: Using Event-Driven API (Recommended)
+
+Using the new event API, component auto-manages data, more concise:
+
+```vue
+
+
+
+
+
+
+
+```
+
+#### Example 2: Using Custom Milestone Edit Dialog
+
+If you need to fully customize the milestone editing interface, you can disable the built-in dialog and use your own component:
+
+```vue
+
+
+
+
+
+
+
+
+
+
+```
+
+**Custom Dialog Component Example** (`CustomMilestoneDialog.vue` - Using Element Plus)：
+
+> **Note**: The following examplesUsing Element Plus UI framework. You can also use other UI frameworks (such as Ant Design Vue, Naive UI, etc.) or native HTML implementation.
+
+```vue
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+> **💡 Custom Dialog Notes**:
+> - Set `use-default-milestone-dialog="false"` to disable built-in dialog
+> - Listen to `@add-milestone` event to open custom dialog
+> - Need to manually manage `milestones` array CRUD operations
+> - Can still listen to other events (like `@milestone-drag-end`) to handle drag operations
+> - Suitable for scenarios requiring complex form validation, special UI design, or additional fields
+
+---
+
+## ⚙️ Configuration & Customization
+
+This section details the configuration options and extension capabilities of the GanttChart component, including Component Configuration, Theme & Internationalization, and Custom Extensions.
+
+### Component Configuration
+
+#### ToolbarConfig (Toolbar Configuration)
+
+Customize the toolbar functional buttons and time scale options.
+
+**Type Definition:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `showAddTask` | `boolean` | `true` | Show "Add Task" button |
+| `showAddMilestone` | `boolean` | `true` | Show "Add Milestone" button |
+| `showTodayLocate` | `boolean` | `true` | Show "Locate to Today" button |
+| `showExportCsv` | `boolean` | `true` | Show "Export CSV" button |
+| `showExportPdf` | `boolean` | `true` | Show "Export PDF" button |
+| `showLanguage` | `boolean` | `true` | Show "Language Switch" button (Chinese/English) |
+| `showTheme` | `boolean` | `true` | Show "Theme Switch" button (Light/Dark) |
+| `showFullscreen` | `boolean` | `true` | Show "Fullscreen" button |
+| `showTimeScale` | `boolean` | `true` | Show time scale button group (controls entire group visibility) |
+| `timeScaleDimensions` | `TimelineScale[]` | `['hour', 'day', 'week', 'month', 'quarter', 'year']` | Set time scale dimensions to display, options: `'hour'`, `'day'`, `'week'`, `'month'`, `'quarter'`, `'year'` |
+| `defaultTimeScale` | `TimelineScale` | `'week'` | Default selected time scale |
+| `showExpandCollapse` | `boolean` | `true` | Show "Expand All/Collapse All" button (for parent-child task tree structure) |
+
+**TimelineScale Type Description:**
+
+```typescript
+type TimelineScale = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'
+
+// Can also use constant form
+import { TimelineScale } from 'jordium-gantt-vue3'
+
+TimelineScale.HOUR // 'hour' - Hour view
+TimelineScale.DAY // 'day' - Day view
+TimelineScale.WEEK // 'week' - Week view
+TimelineScale.MONTH // 'month' - Month view
+TimelineScale.QUARTER // 'quarter' - Quarter view
+TimelineScale.YEAR // 'year' - Year view
+```
+
+**Example 1: Complete Configuration (Show All Features)**
+
+```vue
+
+
+
+
+
+```
+
+**Example 2: Simplified Configuration (Show Common Features Only)**
+
+```vue
+
+```
+
+**Example 3: Using TimelineScale Constants**
+
+```vue
+
+```
+
+**Example 4: Minimal Configuration (Suitable for Embedded Use)**
+
+```vue
+
+```
+
+> **💡 Configuration Recommendations**：
+> - **Default configuration**：When not passed, all buttons are shown by default
+> - **Show as needed**: Hide unnecessary feature buttons based on business requirements
+> - **Time scale**：`timeScaleDimensions` controls which time dimensions to display, recommend selecting 2-4 common dimensions
+> - **Responsive layout**：toolbar will automatically adapt to container width, excessive buttons will collapse into more menu
+
+#### TaskListConfig（Task List Configuration）
+
+Customize task list display columns, width limits, etc. Task list is located on the left side of the Gantt chart, showing detailed task information.
+
+**Type Definition：**
+
+| Field | Type | Default | Description |
+|--------|------|--------|------|
+| `columns` | `TaskListColumnConfig[]` | Default 8 columns | Task list column configuration array, defines which columns to display and their properties |
+| `showAllColumns` | `boolean` | `true` | Whether to show all columns. When `true`, ignores `visible` setting in `columns` |
+| `defaultWidth` | `number \| string` | `320` | Default expanded width. Supports pixel number (like `320`) or percentage string (like `'30%'`) |
+| `minWidth` | `number \| string` | `280` | Minimum width. Supports pixel number (like `280`) or percentage string (like `'20%'`). Cannot be less than 280px |
+| `maxWidth` | `number \| string` | `1160` | Maximum width. Supports pixel number (like `1160`) or percentage string (like `'80%'`) |
+
+**TaskListColumnConfig Type Definition：**
+
+| Field | Type | Required | Description |
+|--------|------|------|------|
+| `key` | `string` | ✅ | Unique column identifier, used to access fields in Task object and for internationalization |
+| `label` | `string` | - | Column display label (header text) |
+| `cssClass` | `string` | - | Custom CSS class name |
+| `width` | `number` | - | Column width (unit: pixels) |
+| `visible` | `boolean` | - | Whether to show this column, default `true`. This setting is invalid when `showAllColumns=true` |
+
+**Example1：Basic Configuration (Adjust Width)**
+
+```vue
+
+
+
+
+
+```
+
+**Example2：Using Percentage Width**
+
+```vue
+
+
+
+
+
+```
+
+**Example3：Custom Display Columns (Standard Configuration)**
+
+Based on business requirements, you can customize columns to display, column widths, and display order. Recommend defining column configuration array first, then assign to `columns` prop.
+
+```vue
+
+
+
+
+
+```
+
+**Example4：Simplified Column Configuration**
+
+Only show core information columns, suitable for scenarios with limited space or requiring concise display.
+
+```vue
+
+```
+
+**Example5：Custom Business Columns**
+
+Add business-related custom columns, ensure Task object contains corresponding fields.
+
+```vue
+
+```
+
+**Example6：Dynamic Column Configuration**
+
+Combine `ref` and `computed` to achieve dynamic show/hide and width adjustment of columns.
+
+```vue
+
+
+
+
+
+```
+
+> **💡 Configuration Notes**：
+> - **Default behavior**：When not passed, show all 8 default columns with width of 320px
+> - **Width units**：Supports pixel (`number`) and percentage (`string`, like `'30%'`) methods
+> - **Percentage calculation**：Based on total width of Gantt chart container, responsive adjustment
+> - **Column order**: `columns` array order determines column display order
+> - **Column configuration standards**：Recommend defining `TaskListColumnConfig[]` type column array first, then assign to `columns` prop
+> - **Custom column support**：Task interface supports arbitrary custom fields through `[key: string]: unknown` index signature, component will dynamically read column values through `task[column.key]`, no need to modify Task interface to add custom columns
+> - **Dynamic configuration**：Combine `ref` and `computed` to achieve dynamic show/hide and width adjustment of columns
+> - **Minimum width limit**: `minWidth` cannot be less than 280px, this is the minimum value to ensure basic usability
+
+#### TaskBarConfig (Task Bar Configuration)
+
+Controls task bar display content and interaction behavior。
+
+**Configuration Fields：**
+
+| Field | Type | Default | Description |
+|--------|------|--------|------|
+| `showAvatar` | `boolean` | `true` | Whether to show avatar |
+| `showTitle` | `boolean` | `true` | Whether to show title text |
+| `showProgress` | `boolean` | `true` | Whether to show progress text |
+| `dragThreshold` | `number` | `5` | Drag trigger threshold (pixels) |
+| `resizeHandleWidth` | `number` | `5` | Resize handle width (pixels), max 15px |
+| `enableDragDelay` | `boolean` | `false` | Whether to enable drag delay (prevent accidental trigger) |
+| `dragDelayTime` | `number` | `150` | Drag delay time (milliseconds) |
+
+> **💡 Edit Permission Control**：
+> - **Global control**: Use `` to disable drag/resize for all tasks
+> - **Individual task control**: Set task object `isEditable: false` property to control individual task
+
+**Example1：Complete Configuration**
+
+```vue
+
+
+
+
+
+```
+
+**Example2：Global Read-Only Mode**
+
+Disable edit operations for all tasks.
+
+```vue
+
+
+
+```
+
+**Example3：Individual Task Read-Only**
+
+Only certain tasks are non-editable, other tasks are normal.
+
+```vue
+
+```
+
+**Example4：Simplified Display**
+
+Only show task bar, hide avatar, title and progress text.
+
+```vue
+
+```
+
+**Example5：Anti-Accidental Touch Configuration**
+
+In mobile or touch screen scenarios, increase drag threshold and delay time.
+
+```vue
+
+```
+#### Timeline Container Auto-Fill Configuration
+
+The component has built-in intelligent timeline range calculation logic, ensuring that regardless of task data volume or task duration, the timeline always fills the container width, providing the best visual experience.
+
+**Core Design Principles:**
+
+1. **Base Buffer Mechanism**: Add fixed buffers based on the actual time range of tasks, varying by view type
+ - Hour view：±1 day task range
+ - Day view: ±30 days before/after task range
+ - Week view: ±8 weeks (approx. 2 months) before/after task range
+ - Month view: ±1 year before/after task range
+ - Quarter view: ±1 year before/after task range
+ - Year view: ±1 year before/after task range
+
+2. **Container Width Adaptation**: After base buffering, if calculated timeline width is less than container width, automatically extend the range
+ - Calculate time units (days/weeks/months/quarters/years) needed for container
+ - **Symmetrically extend** on both sides of base range to ensure timeline fills container
+
+3. **Empty Data Handling**: When no task data exists, calculate reasonable time range based on container width and time scale
+ - Center on current date
+ - Dynamically calculate time span to display based on container width
+ - Ensure minimum display range (e.g., at least 60 days for day view, at least 20 weeks for week view)
+
+4. **Independent Calculation on View Switch**: Each time scale switch triggers independent recalculation of optimal time range for that view
+ - Avoid unreasonable ranges caused by different views sharing cache
+ - Each view gets optimal display effect
+
+**Calculation Pattern Reference Table:**
+
+| View | Unit Width | Base Buffer | Empty Data Min Range | Container Auto-Fill? |
+|------|-----------|--------------|----------------------|----------------|
+| Hour View | 30px/hour | ±1 day | 3 days | ✅ |
+| Day View | 30px/day | ±30 days | 60 days | ✅ |
+| Week View | 60px/week | ±2 months | 20 weeks | ✅ |
+| Month View | 60px/month | ±1 year | 3 years | ✅ |
+| Quarter View | 60px/quarter (240px/year) | ±1 year | 5 years | ✅ |
+| Year View | 360px/year | ±1 year | 5 years | ✅ |
+
+**Practical Application Scenarios:**
+
+- **Short-term Tasks** (e.g., 1-week project):
+ - Won't result in narrow timeline, automatically extends to fill container
+ - Day view: 1 week (7 days × 30px = 210px) → Extends to ≥1200px (approx. 40 days)
+ - Week view: 1 week (60px) → Extends to ≥1200px (approx. 20 weeks)
+
+- **Long-term Projects** (e.g., 2-year project):
+ - After adding fixed buffer, automatically adapts to container
+ - Month view: 24 months + buffer → Extends to container width if needed
+ - Quarter view: 8 quarters + buffer → Extends to container width if needed
+
+- **Empty Board** (no task data):
+ - Day view: Centered on today, displays at least 60 days
+ - Week view: Centered on today, displays at least 20 weeks
+ - Month view: Displays at least 3 years
+ - Quarter/Year view: Displays at least 5 years
+
+> **💡 Automation Advantages**:
+> - No need to manually set `startDate` and `endDate`, component automatically calculates optimal range
+> - Responsive to container width changes, timeline automatically recalculates
+> - Different views independently optimized, auto-adjusts to best display effect when switching views
+> - Avoids issues with timeline being too narrow or having excessive whitespace
+> - Suitable for displaying at different resolutions
+
+### Theme & Internationalization
+
+#### Theme Switching
+
+Component has built-in light and dark themes, can switch via toolbar button, also can listen to switch events:
+
+```vue
+
+
+
+
+
+```
+
+#### Custom Theme Variables
+
+Customize theme by overriding CSS variables:
+
+```css
+/* Customize light theme */
+:root {
+ /* Primary colors */
+ --gantt-primary-color: #409eff;
+ --gantt-success-color: #67c23a;
+ --gantt-warning-color: #e6a23c;
+ --gantt-danger-color: #f56c6c;
+
+ /* Background colors */
+ --gantt-bg-primary: #ffffff;
+ --gantt-bg-secondary: #f5f7fa;
+ --gantt-bg-hover: #ecf5ff;
+
+ /* Text colors */
+ --gantt-text-primary: #303133;
+ --gantt-text-secondary: #606266;
+ --gantt-text-placeholder: #c0c4cc;
+
+ /* Border colors */
+ --gantt-border-color: #dcdfe6;
+ --gantt-border-color-light: #e4e7ed;
+
+ /* Task bar colors */
+ --gantt-task-bg: #409eff;
+ --gantt-task-border: #66b1ff;
+ --gantt-task-text: #ffffff;
+}
+
+/* Customize dark theme */
+.dark {
+ --gantt-bg-primary: #1a1a1a;
+ --gantt-bg-secondary: #2c2c2c;
+ --gantt-bg-hover: #3a3a3a;
+
+ --gantt-text-primary: #e5e5e5;
+ --gantt-text-secondary: #b0b0b0;
+
+ --gantt-border-color: #3a3a3a;
+ --gantt-border-color-light: #4a4a4a;
+
+ --gantt-task-bg: #409eff;
+ --gantt-task-border: #66b1ff;
+ --gantt-task-text: #ffffff;
+}
+```
+
+#### Language Switching
+
+Component has built-in Chinese (zh-CN) and English (en-US), can switch via toolbar button:
+
+```vue
+
+
+
+
+
+```
+
+#### Custom Translations
+
+Override or extend default translations via `localeMessages` prop:
+
+```vue
+
+
+
+
+
+```
+
+> **💡 Tip**：
+> - `localeMessages` adopts **deep merge** strategy, only need to pass fields that need to be overridden
+> - supports nested objects, like `taskList.name`, `toolbar.addTask`, etc.
+> - For complete translation keys, please refer to built-in `messages['zh-CN']` object in component
+
+### Custom Extensions
+
+#### Slots (Slots)
+
+Component provides slots support, allowing custom task content rendering。
+
+##### `custom-task-content` Slots
+
+Used to customize task display content in task list (TaskRow) and timeline (TaskBar).
+
+**Slot Parameters：**
+
+| Parameter | Type | Source | Description |
+|--------|------|------|------|
+| `type` | `'task-row'` \| `'task-bar'` | Common | Slot call position identifier |
+| `task` | `Task` | Common | Current task object |
+
+**TaskRow specific parameters (when `type === 'task-row'`):**
+
+| Parameter | Type | Description |
+|--------|------|------|
+| `isRowContent` | `boolean` | Identified as row content |
+| `level` | `number` | Task level |
+| `indent` | `string` | Indent style |
+| `isHovered` | `boolean` | Whether hovering |
+| `hoveredTaskId` | `number \| null` | Current hovering task ID |
+| `isParent` | `boolean` | Whether parent task |
+| `hasChildren` | `boolean` | Whether has child tasks |
+| `collapsed` | `boolean` | Whether collapsed |
+| `formattedTimer` | `string` | Formatted timer text |
+| `timerRunning` | `boolean` | Whether timer is running |
+| `timerElapsed` | `number` | Elapsed time |
+| `isOvertime` | `number \| boolean \| undefined` | Whether overtime |
+| `overdueDays` | `number` | Overdue days |
+| `overtimeText` | `string` | Overtime text |
+| `overdueText` | `string` | Overdue text |
+| `daysText` | `string` | Days text |
+| `progressClass` | `string` | Progress CSS class name |
+
+**TaskBar specific parameters (when `type === 'task-bar'`):**
+
+| Parameter | Type | Description |
+|--------|------|------|
+| `status` | `object` | TaskStatus object, contains `type`, `color`, `bgColor`, `borderColor` |
+| `statusType` | `string` | StatusType：`'completed'`, `'delayed'`, `'in-progress'`, `'not-started'`, `'parent'` |
+| `isParent` | `boolean` | Whether parent task |
+| `progress` | `number` | TaskProgress（0-100） |
+| `currentTimeScale` | `TimelineScale` | Current time scale |
+| `rowHeight` | `number` | Row height (pixels) |
+| `dayWidth` | `number` | Width per day (pixels) |
+
+**Usage Example：**
+
+```vue
+
+
+
+
+
+
+
+
+
+
+```
+
+**Custom Content Component Example：**
+
+```vue
+
+
+
+
+
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+ 
+
+
jordium-gantt-vue3
+# 
-- 📊 **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
+#### Dark Theme
+
+
+
+---
## 📦 Installation
+Install using your preferred package manager:
+
```bash
# npm
npm install jordium-gantt-vue3
-# yarn
+# yarn
yarn add jordium-gantt-vue3
# pnpm
pnpm add jordium-gantt-vue3
```
-## 📄 License
-
-[MIT License](./LICENSE) © 2025 JordiUM
-
---
-## 📁 Project Structure
+## 🚀 Quick Start
-```
-jordium-gantt-vue3/
-├── src/ # Source code directory
-│ ├── components/ # Core Vue components
-│ │ ├── GanttChart.vue # Main entry component
-│ │ ├── TaskList.vue # Task list component
-│ │ ├── Timeline.vue # Timeline component
-│ │ ├── TaskBar.vue # Task bar component
-│ │ ├── TaskDrawer.vue # Task edit drawer
-│ │ ├── TaskContextMenu.vue # Task context menu
-│ │ ├── GanttToolbar.vue # Toolbar component
-│ │ ├── MilestonePoint.vue # Milestone point
-│ │ ├── MilestoneDialog.vue # Milestone dialog
-│ │ ├── DatePicker.vue # Date picker
-│ │ └── ... # Other components
-│ ├── models/ # Data models and configurations
-│ │ ├── classes/ # Class definitions
-│ │ │ ├── Task.ts # Task model
-│ │ │ ├── Milestone.ts # Milestone model
-│ │ │ └── Language.ts # Language configuration
-│ │ ├── configs/ # Configuration interfaces
-│ │ │ ├── TimelineConfig.ts # Timeline configuration
-│ │ │ └── ToolbarConfig.ts # Toolbar configuration
-│ │ └── types/ # Type definitions
-│ │ └── TimelineScale.ts # Timeline scale types
-│ ├── composables/ # Vue composable functions
-│ │ ├── useI18n.ts # Internationalization utilities
-│ │ └── useMessage.ts # Message utilities
-│ ├── styles/ # Style files
-│ │ ├── app.css # Main styles
-│ │ └── theme-variables.css # Theme variables
-│ ├── utils/ # Utility functions
-│ │ └── predecessorUtils.ts # Predecessor utilities
-│ └── index.ts # Export entry
-├── demo/ # Development demo & interactive showcase
-│ ├── App.vue # Demo application main component
-│ ├── data.json # Demo data (includes clinical trial examples)
-│ ├── main.ts # Demo application entry
-│ └── ... # Other demo files
-├── packageDemo/ # npm package integration demo
-├── dist/ # Build output directory
-├── docs/ # Documentation
-├── design/ # Design resources and screenshots
-│ └── screenshots/ # Theme screenshots
-├── public/ # Public static resources
-│ └── assets/ # Static asset files
-├── README.md # Chinese documentation
-├── README-EN.md # English documentation
-├── package.json # Project configuration
-├── vite.config.ts # Vite development configuration
-├── vite.config.lib.ts # Vite library build configuration
-├── tsconfig.json # TypeScript configuration
-└── ... # Other configuration files and metadata
-```
+### Import Component
-### Directory Description
-
-- **`src/components/`**: Core Vue components containing all Gantt chart functionality
-- **`src/models/`**: Data models, type definitions and configuration interfaces
-- **`src/composables/`**: Vue 3 composable functions providing reusable logic
-- **`src/styles/`**: Style files including theme system and CSS variables
-- **`src/utils/`**: Utility functions for business logic and data transformation
-- **`demo/`**: Local development and feature demonstration with complete interactive pages and clinical trial sample data
-- **`packageDemo/`**: Simulates npm package integration in external projects
-- **`dist/`**: Build output directory for npm publishing or static sites
-- **`docs/`**: Project documentation including deployment guides and API references
-
-## 🔧 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 |
-| `taskListConfig` | `TaskListConfig` | `{}` | Task list configuration (including default width, min/max width limits, etc.) |
-| `localeMessages` | `Partial