jordium-gantt-vue3 1.6.1 → 1.7.0

package/README.md

@@ -29,6 +29,12 @@
 
 <p align="center">现代化的 Vue 3 甘特图组件库，为项目管理和任务调度提供完整解决方案</p>
 
+<p align="center">
+  <a href="https://gitee.com/activity/2025opensource?ident=IOUNZP" target="_blank">
+    <img src="https://img.shields.io/badge/🥇_Gitee_2025年度开源项目评选-👉_感谢您的参与投票-gold?style=for-the-badge&labelColor=C71D23&logoColor=white" alt="Gitee 2025年度开源项目评选" height="40">
+  </a>
+</p>
+
 <p align="center">
   <a href="https://nelson820125.github.io/jordium-gantt-vue3/">
     <strong>📱 在线演示</strong>
@@ -189,6 +195,8 @@ npm run dev
 | `autoSortByStartDate`       | `boolean`                                                                                 | `false` | 是否根据开始时间自动排序任务                                   |
 | `allowDragAndResize`        | `boolean`                                                                                 | `true`  | 是否允许拖拽和调整任务/里程碑大小                              |
 | `enableTaskRowMove`         | `boolean`                                                                                 | `false` | 是否允许拖拽和摆放TaskRow                                      |
+| `enableTaskListContextMenu` | `boolean`                                                                                 | `true`  | 是否启用 TaskList（TaskRow）右键菜单功能。为 `true` 时：未声明 `task-list-context-menu` 插槽则使用内置菜单，声明了插槽则使用自定义菜单；为 `false` 时右键菜单完全禁用                     |
+| `enableTaskBarContextMenu`  | `boolean`                                                                                 | `true`  | 是否启用 TaskBar 右键菜单功能。为 `true` 时：未声明 `task-bar-context-menu` 插槽则使用内置菜单，声明了插槽则使用自定义菜单；为 `false` 时右键菜单完全禁用                               |
 | `assigneeOptions`           | `Array<{ key?: string \| number; value: string \| number; label: string }>`               | `[]`    | 任务编辑抽屉中负责人下拉菜单的选项列表          | 
 
 #### TaskListColumn 属性
@@ -224,6 +232,110 @@ npm run dev
 > - 列的显示顺序由 `TaskListColumn` 组件的声明顺序决定
 > - 关于列内容自定义和插槽的详细使用方法，请参考 [插槽 (Slots)](#插槽-slots) 章节
 
+#### TaskListContextMenu 属性
+
+`TaskListContextMenu` 组件用于声明式定义 TaskList（TaskRow）的右键菜单。当 `enableTaskListContextMenu` 为 `true` 时生效。
+
+| 属性名     | 类型                   | 默认值      | 说明                                                                                                                   |
+| ---------- | ---------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `taskType` | `string \| string[]`   | `undefined` | 指定哪些任务类型显示此右键菜单。不设置时遵循现有逻辑（所有任务都显示），设置后仅对指定类型任务显示。支持单个类型（如 `'task'`）或多个类型（如 `['task', 'milestone']`） |
+
+**使用示例**：
+
+```vue
+<GanttChart 
+  :tasks="tasks" 
+  :enable-task-list-context-menu="true"
+>
+  <!-- 默认行为：所有任务都显示此右键菜单 -->
+  <TaskListContextMenu>
+    <template #default="scope">
+      <div class="custom-menu">
+        <div class="menu-item" @click="editTask(scope.row)">编辑</div>
+        <div class="menu-item" @click="deleteTask(scope.row)">删除</div>
+      </div>
+    </template>
+  </TaskListContextMenu>
+  
+  <!-- 仅对 type='task' 的任务显示此菜单 -->
+  <TaskListContextMenu task-type="task">
+    <template #default="scope">
+      <div class="custom-menu">
+        <div class="menu-item">任务专属菜单</div>
+      </div>
+    </template>
+  </TaskListContextMenu>
+  
+  <!-- 对多种类型显示菜单 -->
+  <TaskListContextMenu :task-type="['task', 'milestone']">
+    <template #default="scope">
+      <div class="custom-menu">
+        <div class="menu-item">任务和里程碑菜单</div>
+      </div>
+    </template>
+  </TaskListContextMenu>
+</GanttChart>
+```
+
+> **💡 提示**：
+> - `TaskListContextMenu` 组件本身不渲染任何内容，仅用于声明菜单配置
+> - 必须在 `GanttChart` 组件内部使用，且设置 `enable-task-list-context-menu="true"`
+> - 菜单定位和显示状态由内部自动管理，用户只需关心菜单内容的 HTML 结构
+> - 菜单会在点击外部或滚动时自动关闭
+> - 关于插槽的详细使用方法，请参考 [插槽 (Slots)](#插槽-slots) 章节
+
+#### TaskBarContextMenu 属性
+
+`TaskBarContextMenu` 组件用于声明式定义 TaskBar（时间线任务条）的右键菜单。当 `enableTaskBarContextMenu` 为 `true` 时生效。
+
+| 属性名     | 类型                   | 默认值      | 说明                                                                                                                   |
+| ---------- | ---------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `taskType` | `string \| string[]`   | `undefined` | 指定哪些任务类型显示此右键菜单。不设置时遵循现有逻辑（所有任务都显示），设置后仅对指定类型任务显示。支持单个类型（如 `'task'`）或多个类型（如 `['task', 'milestone']`） |
+
+**使用示例**：
+
+```vue
+<GanttChart 
+  :tasks="tasks" 
+  :enable-task-bar-context-menu="true"
+>
+  <!-- 默认行为：所有任务都显示此右键菜单 -->
+  <TaskBarContextMenu>
+    <template #default="scope">
+      <div class="custom-menu">
+        <div class="menu-item" @click="extendTask(scope.row)">延长任务</div>
+        <div class="menu-item" @click="moveTask(scope.row)">移动任务</div>
+      </div>
+    </template>
+  </TaskBarContextMenu>
+  
+  <!-- 仅对 type='task' 的任务显示此菜单 -->
+  <TaskBarContextMenu task-type="task">
+    <template #default="scope">
+      <div class="custom-menu">
+        <div class="menu-item">任务条专属菜单</div>
+      </div>
+    </template>
+  </TaskBarContextMenu>
+  
+  <!-- 对多种类型显示菜单 -->
+  <TaskBarContextMenu :task-type="['task', 'story']">
+    <template #default="scope">
+      <div class="custom-menu">
+        <div class="menu-item">任务和故事菜单</div>
+      </div>
+    </template>
+  </TaskBarContextMenu>
+</GanttChart>
+```
+
+> **💡 提示**：
+> - `TaskBarContextMenu` 组件本身不渲染任何内容，仅用于声明菜单配置
+> - 必须在 `GanttChart` 组件内部使用，且设置 `enable-task-bar-context-menu="true"`
+> - 菜单定位和显示状态由内部自动管理，用户只需关心菜单内容的 HTML 结构
+> - 菜单会在点击外部或滚动时自动关闭
+> - 关于插槽的详细使用方法，请参考 [插槽 (Slots)](#插槽-slots) 章节
+
 #### 配置对象属性
 
 完整的配置对象说明请参考 [⚙️ 配置与扩展](#⚙️-配置与扩展) 章节。
@@ -2011,7 +2123,7 @@ const handleLanguageChange = (lang: 'zh-CN' | 'en-US') => {
 
 #### 自定义翻译
 
-通过 `localeMessages` 属性覆盖或扩展默认翻译：
+通过 `localeMessages` 属性传入自定义多语言文本，组件内部会自动合并到默认翻译中：
 
 ```vue
 <template>
@@ -2022,7 +2134,7 @@ const handleLanguageChange = (lang: 'zh-CN' | 'en-US') => {
 const customMessages = {
   "zh-CN": {
     // 任务列表相关
-    name: '任务名称（自定义）',
+    taskName: '任务名称（自定义）',
     startDate: '开始日期',
     endDate: '结束日期',
     duration: '工期',
@@ -2030,55 +2142,183 @@ const customMessages = {
     predecessor: '前置任务',
     assignee: '负责人',
     estimatedHours: '预估工时',
-    actualHours: '实际工时'
-
-    // 工具栏相关
-    addTask: '新建任务',
-    addMilestone: '新建里程碑',
-    today: '今天',
-    exportCsv: '导出 CSV',
-    exportPdf: '导出 PDF',
-    fullscreen: '全屏',
-    exitFullscreen: '退出全屏',
-    language: '语言',
-    theme: '主题',
-    expandAll: '全部展开',
-    collapseAll: '全部折叠'
-
-    // 内置任务编辑器相关
-    title: '任务详情',
-    titleEdit: '编辑任务',
-    titleNew: '新建任务',
-    name: '任务名称',
-    startDate: '开始日期',
-    endDate: '结束日期',
-    assignee: '负责人',
-    predecessor: '前置任务',
-    description: '描述',
-    estimatedHours: '预估工时',
     actualHours: '实际工时',
-    progress: '进度',
-    save: '保存',
-    cancel: '取消',
-    delete: '删除'
-
-    // 其他文本
-    days: '天',
-    hours: '小时',
-    overtime: '超时',
-    overdue: '逾期',
-    // ... 更多自定义翻译
+
+    // 自定义字段（支持嵌套结构）
+    department: '部门',
+    status: '状态',
+    gantt: {
+      planEndDate: '计划结束时间',
+      planStartDate: '计划开始时间'
+    }
   },
-  "en-US": {......}
+  "en-US": {
+    department: 'Department',
+    status: 'Status',
+    gantt: {
+      planEndDate: 'Plan End Date',
+      planStartDate: 'Plan Start Date'
+    }
+  }
 }
 </script>
 ```
 
 > **💡 提示**：
 >
-> - `localeMessages` 采用**深度合并**策略，只需传递需要覆盖的字段即可
-> - 支持嵌套对象，如 `taskList.name`、`toolbar.addTask` 等
-> - 完整的翻译键请参考组件内置的 `messages['zh-CN']` 对象
+> - `localeMessages` 采用**深度合并**策略，只需传递需要覆盖或新增的字段即可
+> - 支持嵌套对象结构，如 `gantt.planEndDate`
+> - 完整的内置翻译键请参考组件源码中的 `useI18n.ts`
+
+##### 在自定义插槽中使用翻译
+
+组件导出了 `useI18n` composable，可在自定义插槽中访问翻译文本，支持两种访问方式：
+
+**方式一：引用式访问（`t.field`）**
+
+通过响应式对象直接访问翻译文本，语法简洁，适合模板中使用：
+
+```vue
+<script setup>
+import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
+
+const { t } = useI18n()
+
+const customMessages = {
+  'zh-CN': {
+    department: '部门'
+  }
+}
+</script>
+
+<template>
+  <GanttChart :tasks="tasks" :locale-messages="customMessages" />
+  
+  <!-- 引用式：直接通过 t 对象访问 -->
+  <TaskListColumn prop="startDate" label="开始时间" width="250">
+    <template #header>
+      <strong style="color: #1890ff;">{{ t.department }}</strong>
+    </template>
+  </TaskListColumn>
+</template>
+```
+
+**方式二：函数式访问（`getTranslation()`）**
+
+支持嵌套键和默认值，适合访问深层结构或动态键：
+
+```vue
+<script setup>
+import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
+
+const { getTranslation } = useI18n()
+
+const customMessages = {
+  'zh-CN': {
+    gantt: {
+      planEndDate: '计划结束时间'
+    }
+  }
+}
+</script>
+
+<template>
+  <GanttChart :tasks="tasks" :locale-messages="customMessages" />
+  
+  <!-- 函数式：支持嵌套键和默认值 -->
+  <TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate')" width="250" />
+</template>
+```
+
+**完整示例（结合语言切换）：**
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { GanttChart, TaskListColumn, useI18n } from 'jordium-gantt-vue3'
+
+// 自定义多语言配置
+const customMessages = {
+  'zh-CN': {
+    department: '部门',
+    gantt: {
+      planEndDate: '计划结束时间'
+    }
+  },
+  'en-US': {
+    department: 'Department',
+    gantt: {
+      planEndDate: 'Plan End Date'
+    }
+  }
+}
+
+// 使用 useI18n 访问翻译
+const { t, getTranslation, locale, setLocale } = useI18n()
+const tasks = ref([...])
+
+// 语言切换
+const switchLanguage = () => {
+  setLocale(locale.value === 'zh-CN' ? 'en-US' : 'zh-CN')
+}
+</script>
+
+<template>
+  <button @click="switchLanguage">切换语言</button>
+  
+  <GanttChart :tasks="tasks" :locale-messages="customMessages" />
+  
+  <!-- 引用式：直接通过 t 对象访问 -->
+  <TaskListColumn prop="startDate" label="开始时间" width="250">
+    <template #header>
+      <strong style="color: #1890ff;">{{ t.department }}</strong>
+    </template>
+  </TaskListColumn>
+  
+  <!-- 函数式：支持嵌套键和默认值 -->
+  <TaskListColumn prop="endDate" :label="getTranslation('gantt.planEndDate')" width="250" />
+</template>
+```
+
+**`useI18n` API 说明：**
+
+| 导出项 | 类型 | 说明 |
+|--------|------|------|
+| `t` | `Ref<object>` | 响应式翻译对象，通过 `t.key` 或 `t.nested.key` 访问翻译文本 |
+| `getTranslation(key, defaultValue?)` | `Function` | 函数式访问翻译文本<br>• `key`: 翻译键，支持嵌套路径（如 `'gantt.planEndDate'`）<br>• `defaultValue`: 可选，找不到翻译时返回的默认值<br>• 返回：翻译文本、默认值或 key 本身 |
+| `formatTranslation(key, params)` | `Function` | 格式化带参数的翻译文本<br>• `key`: 翻译键<br>• `params`: 参数对象，如 `{ name: '任务1' }`<br>• 返回：替换占位符后的文本（如 `'任务{name}'` → `'任务任务1'`） |
+| `locale` | `Ref<string>` | 当前语言（`'zh-CN'` 或 `'en-US'`） |
+| `setLocale(locale)` | `Function` | 切换语言，会自动更新所有使用 `useI18n` 的组件 |
+| `formatYearMonth(year, month)` | `Function` | 格式化年月显示<br>• 中文：`formatYearMonth(2024, 3)` → `'2024年03月'`<br>• 英文：`formatYearMonth(2024, 3)` → `'2024/03'` |
+| `formatMonth(month)` | `Function` | 格式化月份显示<br>• 中文：`formatMonth(3)` → `'3月'`<br>• 英文：`formatMonth(3)` → `'03'` |
+
+**使用示例：**
+
+```vue
+<script setup>
+import { useI18n } from 'jordium-gantt-vue3'
+
+const { t, getTranslation, formatTranslation, formatYearMonth, formatMonth } = useI18n()
+
+// 1. 基础访问
+const text1 = t.taskName  // '任务名称'
+const text2 = getTranslation('gantt.planEndDate', '计划结束')  // '计划结束时间' 或默认值
+
+// 2. 带参数的翻译
+const message = formatTranslation('taskNotFound', { id: '123' })  // '未找到要更新的任务，ID：123'
+
+// 3. 日期格式化
+const yearMonth = formatYearMonth(2024, 3)  // '2024年03月' (zh-CN) 或 '2024/03' (en-US)
+const month = formatMonth(3)  // '3月' (zh-CN) 或 '03' (en-US)
+</script>
+```
+
+> **💡 使用提示**：
+>
+> - **引用式** (`t.key`)：语法简洁，适合模板中直接使用
+> - **函数式** (`getTranslation('nested.key', 'default')`)：支持嵌套键和默认值，适合访问深层结构
+> - 通过 `localeMessages` 属性传入自定义翻译，再通过 `useI18n` 访问并翻译
+> - 语言切换通过 `setLocale()` 实现，所有组件会自动响应更新
 
 ### 自定义扩展
 
@@ -2248,6 +2488,208 @@ const props = defineProps<Props>()
 > - TaskRow 和 TaskBar 的可用空间不同，需要适配布局
 > - 避免在插槽内容中使用过于复杂的组件，可能影响性能
 
+##### TaskListContextMenu 插槽
+
+用于自定义 TaskRow（任务列表行）的右键菜单内容。
+
+**菜单显示逻辑：**
+- 当 `enableTaskListContextMenu=true` 且**未声明** TaskListContextMenu 组件时 → 使用**系统内置**的右键菜单
+- 当 `enableTaskListContextMenu=true` 且**声明了** TaskListContextMenu 组件时 → 使用**自定义**的右键菜单
+- 当 `enableTaskListContextMenu=false` 时 → 右键菜单**完全禁用**（无论是否声明组件）
+
+**插槽列表：**
+
+| 插槽名    | 参数                              | 说明                                                                                           |
+| --------- | --------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `default` | `scope: { row: Task, $index: number }`   | 自定义TaskRow的右键菜单。通过 `scope.row` 访问当前任务对象，通过 `scope.$index` 访问任务索引。 |
+
+**使用示例：**
+
+```vue
+<template>
+  <GanttChart 
+    :tasks="tasks"
+    :enable-task-list-context-menu="true"
+  >
+    <TaskListContextMenu>
+      <template #default="scope">
+        <div class="custom-menu">
+          <div class="custom-item" @click="handleEdit('extend', scope.row)">
+            ✏️ 编辑任务
+          </div>
+          <div class="custom-item" @click="handleDelete('move', scope.row)">
+            🗑️ 删除任务
+          </div>
+          <div class="custom-divider"></div>
+          <div class="custom-item" @click="handleDuplicate('copy', scope.row)">
+            📄 复制任务
+          </div>
+        </div>
+      </template>
+    </TaskListContextMenu>
+  </GanttChart>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { GanttChart, TaskListContextMenu } from 'jordium-gantt-vue3'
+import 'jordium-gantt-vue3/dist/assets/jordium-gantt-vue3.css'
+import type { Task } from 'jordium-gantt-vue3'
+
+const tasks = ref<Task[]>([])
+
+const handleEdit = (task: Task) => {
+  console.log('编辑任务:', task)
+}
+
+const handleDelete = (task: Task) => {
+  console.log('删除任务:', task)
+}
+
+const handleDuplicate = (task: Task) => {
+  console.log('复制任务:', task)
+}
+</script>
+
+<style scoped>
+.custom-context-menu {
+  position: fixed;
+  background: white;
+  border: 1px solid #e0e0e0;
+  border-radius: 4px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+  z-index: 9999;
+  min-width: 120px;
+}
+
+.menu-item {
+  padding: 8px 16px;
+  cursor: pointer;
+  transition: background-color 0.2s;
+}
+
+.menu-item:hover {
+  background-color: #f5f5f5;
+}
+
+.menu-divider {
+  height: 1px;
+  background-color: #e0e0e0;
+  margin: 4px 0;
+}
+</style>
+```
+
+##### TaskBarContextMenu 插槽
+
+用于自定义 TaskBar（时间轴任务条）的右键菜单内容。
+
+**菜单显示逻辑：**
+- 当 `enableTaskBarContextMenu=true` 且**未声明** TaskBarContextMenu 组件时 → 使用**系统内置**的右键菜单
+- 当 `enableTaskBarContextMenu=true` 且**声明了** TaskBarContextMenu 组件时 → 使用**自定义**的右键菜单
+- 当 `enableTaskBarContextMenu=false` 时 → 右键菜单**完全禁用**（无论是否声明组件）
+
+**插槽列表：**
+
+| 插槽名    | 参数                              | 说明                                                                                           |
+| --------- | --------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `default` | `scope: { row: Task, $index: number }`   | 自定义TaskBar的右键菜单。通过 `scope.row` 访问当前任务对象，通过 `scope.$index` 访问任务索引。 |
+
+**使用示例：**
+
+```vue
+<template>
+  <GanttChart 
+    :tasks="tasks"
+    :enable-task-bar-context-menu="true"
+  >
+    <TaskBarContextMenu>
+      <template #default="scope">
+        <div class="custom-context-menu">
+          <div class="menu-item" @click="handleViewDetails(scope.row)">
+            👁️ 查看详情
+          </div>
+          <div class="menu-item" @click="handleAdjustTime(scope.row)">
+            ⏰ 调整时间
+          </div>
+          <div class="menu-divider"></div>
+          <div class="menu-item" @click="handleSetDependency(scope.row)">
+            🔗 设置依赖
+          </div>
+        </div>
+      </template>
+    </TaskBarContextMenu>
+  </GanttChart>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { GanttChart, TaskBarContextMenu } from 'jordium-gantt-vue3'
+import 'jordium-gantt-vue3/dist/assets/jordium-gantt-vue3.css'
+import type { Task } from 'jordium-gantt-vue3'
+
+const tasks = ref<Task[]>([])
+
+const handleViewDetails = (task: Task) => {
+  console.log('查看详情:', task)
+}
+
+const handleAdjustTime = (task: Task) => {
+  console.log('调整时间:', task)
+}
+
+const handleSetDependency = (task: Task) => {
+  console.log('设置依赖:', task)
+}
+</script>
+
+<style scoped>
+.custom-context-menu {
+  position: fixed;
+  background: white;
+  border: 1px solid #e0e0e0;
+  border-radius: 4px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+  z-index: 9999;
+  min-width: 120px;
+}
+
+.menu-item {
+  padding: 8px 16px;
+  cursor: pointer;
+  transition: background-color 0.2s;
+}
+
+.menu-item:hover {
+  background-color: #f5f5f5;
+}
+
+.menu-divider {
+  height: 1px;
+  background-color: #e0e0e0;
+  margin: 4px 0;
+}
+</style>
+```
+
+> **💡 使用场景**：
+>
+> - 自定义右键菜单样式和布局
+> - 添加业务特定的操作项
+> - 根据任务状态动态显示菜单项
+> - 添加权限控制逻辑
+> - 集成第三方 UI 组件库的菜单组件
+
+> **⚠️ 注意事项**：
+>
+> - 当 `enableTaskListContextMenu=false` 或 `enableTaskBarContextMenu=false` 时，即使声明了组件也不会显示菜单
+> - 右键菜单会在滚动或点击菜单外部时自动关闭
+> - 推荐使用 `<Teleport to="body">` 将菜单渲染到 body 下，避免定位和层级问题
+> - 记得在菜单项点击后调用 `onClose()` 关闭菜单
+> - TaskRow 和 TaskBar 的右键菜单是独立的，可以分别自定义
+> - 默认情况下，系统会提供内置的右键菜单，包含常用操作
+> - 声明式组件不会渲染任何内容，仅用于传递配置
+
 ##### TaskListColumn 插槽
 
 `TaskListColumn` 组件提供了两个插槽，用于自定义任务列表的列头和单元格内容。必须在声明式模式（`taskListColumnRenderMode="declarative"`）下使用。
@@ -2560,25 +3002,90 @@ const taskListConfig = ref<TaskListConfig>({
 
 ```
 jordium-gantt-vue3/
-├── src/                      # 源代码
-│   ├── components/           # Vue 组件
-│   │   ├── GanttChart.vue    # 甘特图主组件
-│   │   ├── TaskList.vue      # 任务列表
-│   │   ├── Timeline.vue      # 时间轴
-│   │   └── ...
-│   ├── models/               # 数据模型
-│   │   ├── classes/          # 类定义
-│   │   ├── configs/          # 配置接口
-│   │   └── types/            # 类型定义
-│   ├── composables/          # 组合式函数
-│   ├── styles/               # 样式文件
-│   └── utils/                # 工具函数
-├── demo/                     # 示例代码
-├── docs/                     # 文档
-├── public/                   # 公共资源
-└── package.json              # 项目配置
+├── src/                           # 源代码
+│   ├── components/                # Vue 组件
+│   │   ├── GanttChart.vue         # 甘特图主组件
+│   │   ├── GanttToolbar.vue       # 工具栏组件
+│   │   ├── Timeline.vue           # 时间轴组件
+│   │   ├── TaskBar.vue            # 任务条组件
+│   │   ├── TaskRow.vue            # 任务行组件
+│   │   ├── TaskDrawer.vue         # 任务编辑抽屉
+│   │   ├── MilestonePoint.vue     # 里程碑点组件
+│   │   ├── MilestoneDialog.vue    # 里程碑编辑对话框
+│   │   ├── TaskContextMenu.vue    # 右键菜单组件
+│   │   ├── TaskList/              # 任务列表模块（模块化重构）
+│   │   │   ├── TaskList.vue       # 任务列表主组件
+│   │   │   ├── TaskListColumn.vue # 声明式列组件
+│   │   │   ├── index.ts           # 模块导出
+│   │   │   └── composables/       # 任务列表相关组合式函数
+│   │   │       ├── useTaskListLayout.ts          # 虚拟滚动和布局计算
+│   │   │       ├── useTaskListColumns.ts         # 列配置管理
+│   │   │       ├── useTaskListResize.ts          # 容器尺寸管理
+│   │   │       ├── useTaskListEventHandlers.ts   # 事件处理逻辑
+│   │   │       └── useTaskParentCalculation.ts   # 父任务数据计算
+│   │   └── index.ts               # 组件统一导出
+│   ├── models/                    # 数据模型
+│   │   ├── classes/               # 类定义
+│   │   │   ├── Task.ts            # 任务类
+│   │   │   ├── Milestone.ts       # 里程碑类
+│   │   │   └── Language.ts        # 语言配置类
+│   │   ├── configs/               # 配置接口
+│   │   │   ├── TaskListConfig.ts  # 任务列表配置
+│   │   │   ├── TaskBarConfig.ts   # 任务条配置
+│   │   │   ├── TimelineConfig.ts  # 时间轴配置
+│   │   │   └── ToolbarConfig.ts   # 工具栏配置
+│   │   └── types/                 # 类型定义
+│   │       ├── TimelineDataTypes.ts # 时间轴数据类型
+│   │       ├── TimelineScale.ts   # 时间刻度类型
+│   │       └── TimelineCompat.ts  # 兼容性类型
+│   ├── composables/               # 全局组合式函数
+│   │   ├── useI18n.ts             # 国际化
+│   │   ├── useMessage.ts          # 消息提示
+│   │   ├── useTaskRowDrag.ts      # 任务行拖拽
+│   │   └── useTaskListColumns.ts  # 列配置（已迁移至 TaskList/composables）
+│   ├── styles/                    # 样式文件
+│   │   ├── app.css                # 主样式
+│   │   ├── list.css               # 列表样式
+│   │   ├── theme-variables.css    # 主题变量
+│   │   └── index.ts               # 样式导出
+│   ├── utils/                     # 工具函数
+│   │   ├── canvasUtils.ts         # Canvas 工具
+│   │   ├── perfMonitor.ts         # 性能监控
+│   │   ├── predecessorUtils.ts    # 前置任务工具
+│   │   └── taskTreeUtils.ts       # 任务树工具
+│   └── index.ts                   # 主入口文件
+├── demo/                          # 在线演示代码
+│   ├── App.vue                    # 演示应用
+│   ├── data.json                  # 示例数据
+│   ├── locales/                   # 多语言文件
+│   └── ...
+├── docs/                          # 文档
+│   └── TaskList-重构测试清单.md   # 重构文档
+├── npm-demo/                      # NPM 包使用示例
+├── npm-webpack-demo/              # Webpack 集成示例
+├── public/                        # 公共资源
+│   └── assets/                    # 静态资源
+└── package.json                   # 项目配置
 ```
 
+### 模块化设计亮点
+
+#### TaskList 模块化重构
+
+TaskList 组件经过深度重构，采用模块化设计，提升了代码可维护性：
+
+**重构成果：**
+- 主组件从 686 行精简至 361 行（-47%）
+- 逻辑按职责分离到 5 个专门的 composables
+- 每个模块职责单一，便于测试和维护
+
+**Composables 职责划分：**
+- `useTaskListLayout` - 虚拟滚动和布局计算
+- `useTaskListColumns` - 列配置管理和样式计算
+- `useTaskListResize` - 容器尺寸监听和 ResizeObserver 管理
+- `useTaskListEventHandlers` - 全局事件处理和滚动同步
+- `useTaskParentCalculation` - 父任务数据计算和任务树遍历
+
 ---
 
 ## 🔗 相关链接