From 5a9a55cd1fd3069b0fda08c5ed8d0ade72f395d4 Mon Sep 17 00:00:00 2001
From: "LINING-PC\\lining" <lining820125@163.com>
Date: Sat, 28 Jun 2025 23:30:10 +0800
Subject: [PATCH] beta-1.0.1 - vulnerabilities upgrades

---
 API_USAGE.md                  | 1010 ++++++++++++++++++++++++++++++++-
 demo/VersionHistoryDrawer.vue |    3 -
 src/components/DatePicker.vue |    5 +-
 3 files changed, 991 insertions(+), 27 deletions(-)

diff --git a/API_USAGE.md b/API_USAGE.md
index 4a0064d..d61741a 100644
--- a/API_USAGE.md
+++ b/API_USAGE.md
@@ -1,26 +1,996 @@
-# API_USAGE
+# Gantt Chart API 使用指南
 
-## 组件导出
-```js
-import { GanttChart, TaskList, TaskRow, MilestonePoint, GanttToolbar, GanttConfirmDialog } from 'jordium-gantt-vue3'
+## 📖 概述
+
+Jordium Gantt Vue3 组件提供了灵活的API接口，允许开发者自定义TaskBar双击事件的处理逻辑，可以完全替换默认的编辑行为。组件采用Vue3 + TypeScript构建，样式延续Element Plus设计风格但不依赖Element Plus组件库。
+
+## 🚀 API 接口
+
+### GanttChart Props
+
+| 属性名 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| `tasks` | `Task[]` | `[]` | 任务数据数组，支持嵌套结构（树形数据） |
+| `onTaskDoubleClick` | `(task: Task) => void` | `undefined` | 自定义双击事件处理器，当TaskBar被双击时触发 |
+| `editComponent` | `any` | `undefined` | 自定义编辑组件（预留接口，暂未实现） |
+| `useDefaultDrawer` | `boolean` | `true` | 是否使用默认的TaskDrawer抽屉组件进行编辑 |
+| `onTaskDelete` | `(task: Task) => void` | `undefined` | 自定义删除事件处理器，当删除按钮被点击时触发 |
+| `showToolbar` | `boolean` | `true` | 是否显示工具栏 |
+| `toolbarConfig` | `ToolbarConfig` | `{}` | 工具栏配置选项 |
+| `onAddTask` | `() => void` | `undefined` | 新增任务按钮点击事件处理器 |
+| `onExportCsv` | `() => void \| boolean` | `undefined` | 导出CSV按钮点击事件处理器，返回false使用默认实现 |
+| `onExportPdf` | `() => void` | `undefined` | 导出PDF按钮点击事件处理器 |
+| `onLanguageChange` | `(lang: 'zh' \| 'en') => void` | `undefined` | 语言切换事件处理器 |
+| `onThemeChange` | `(isDark: boolean) => void` | `undefined` | 主题切换事件处理器 |
+| `onFullscreenChange` | `(isFullscreen: boolean) => void` | `undefined` | 全屏切换事件处理器 |
+
+### ToolbarConfig 接口定义
+
+```typescript
+interface ToolbarConfig {
+  showAddTask?: boolean        // 是否显示新增任务按钮，默认true
+  showExportCsv?: boolean      // 是否显示导出CSV按钮，默认true
+  showExportPdf?: boolean      // 是否显示导出PDF按钮，默认true
+  showLanguage?: boolean       // 是否显示语言切换按钮，默认true
+  showTheme?: boolean          // 是否显示主题切换按钮，默认true
+  showFullscreen?: boolean     // 是否显示全屏切换按钮，默认true
+}
 ```
 
-## 主要 Props 说明
-- `tasks`: 任务数据数组
-- `milestones`: 里程碑数据数组
-- `onDelete`: 删除回调，已统一弹窗交互
-- `theme`: 主题切换（如 'light'/'dark'）
-- 其它详见各组件 props 类型定义
+### API 工作机制
 
-## 事件
-- `@delete`：删除任务/里程碑
-- `@update`：任务/里程碑更新
-- `@confirm`/`@cancel`：弹窗交互
+1. **双击优先级**: 当提供 `onTaskDoubleClick` 时，将优先调用自定义处理器，默认的TaskDrawer不会打开
+2. **双击一致性**: TaskList中任务行的双击与Timeline中TaskBar的双击具有完全相同的效果和优先级
+3. **删除优先级**: 当提供 `onTaskDelete` 时，将优先调用自定义删除处理器，否则使用默认删除行为
+4. **默认行为**: 当未提供 `onTaskDoubleClick` 且 `useDefaultDrawer` 为 `true` 时，双击TaskBar或TaskRow会打开内置的TaskDrawer
+5. **完全自定义**: 设置 `useDefaultDrawer: false` 可以完全禁用默认抽屉，只使用自定义处理器
+6. **数据更新机制**:
+   - TaskDrawer更新任务 → Timeline本地更新 → 发送task-updated事件 → TaskList更新数据源
+   - TaskList数据更新 → 发送tasks-changed事件 → Timeline重新渲染TaskBar
+   - TaskBar位置变化 → 自动重新报告位置 → 依赖关系线自动重新计算
+7. **CSV导出机制**:
+   - 当提供 `onExportCsv` 时，优先调用自定义处理器
+   - 如果自定义处理器返回 `false`，则使用内置的默认导出功能
+   - 默认导出支持UTF-8编码、多语言头部、安全字符转义等特性
+   - 导出内容包含所有任务字段，递归处理子任务
+8. **工具栏功能**:
+   - 新增任务按钮：独立的主要操作按钮，具有醒目的主色调样式
+   - 导出按钮组：CSV和PDF导出按钮采用button group样式，左右相连，统一的视觉效果
+   - 设置按钮：语言、主题、全屏等图标按钮，位于右侧，支持响应式布局
+   - 国际化支持：内置中英文切换，所有按钮文本和提示自动适配
 
-## 样式与主题
-- 全局按钮、弹窗、表格等样式统一于 `src/styles/app.css`
-- 主题变量见 `src/styles/theme-variables.css`
+### Task 接口定义
 
-## 扩展
-- 支持自定义工具栏、弹窗内容、国际化
-- 详细用法见 README.md
+```typescript
+interface Task {
+  id: number                    // 任务唯一标识
+  name: string                  // 任务名称
+  predecessor?: string          // 前置任务ID
+  assignee?: string            // 负责人
+  startDate?: string           // 开始日期 (YYYY-MM-DD格式)
+  endDate?: string             // 结束日期 (YYYY-MM-DD格式)
+  progress?: number            // 完成进度 (0-100)
+  estimatedHours?: number      // 预估工时
+  actualHours?: number         // 实际工时
+  children?: Task[]            // 子任务数组（支持嵌套结构）
+  collapsed?: boolean          // 是否折叠子任务
+  isParent?: boolean           // 是否为父级任务
+  type?: string               // 任务类型 (task/story/bug/milestone)
+  description?: string         // 任务描述
+}
+```
+
+## 💡 使用示例
+
+### 1. 默认模式（使用内置TaskDrawer）
+
+```vue
+<template>
+  <!-- 最简单的使用方式，双击TaskBar会打开默认的编辑抽屉 -->
+  <GanttChart :tasks="tasks" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import GanttChart from './components/GanttChart.vue'
+
+// 定义任务数据
+const tasks = ref([
+  {
+    id: 1,
+    name: '项目启动',
+    assignee: '张三',
+    startDate: '2025-06-15',
+    endDate: '2025-06-25',
+    progress: 100,
+    type: 'story',
+    children: [
+      {
+        id: 2,
+        name: '需求分析',
+        assignee: '李四',
+        startDate: '2025-06-16',
+        endDate: '2025-06-20',
+        progress: 100,
+        type: 'task'
+      }
+    ]
+  }
+])
+</script>
+```
+
+### 2. 自定义双击处理器
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import GanttChart from './components/GanttChart.vue'
+
+// 定义Task接口（与组件内部保持一致）
+interface Task {
+  id: number
+  name: string
+  startDate: string
+  endDate: string
+  progress?: number
+  isParent?: boolean
+  predecessor?: number
+  type?: string
+}
+
+// 自定义双击事件处理器
+const handleTaskDoubleClick = (task: Task) => {
+  console.log('双击了任务:', task)
+  // 注意：此处理器会同时响应TaskBar和TaskList中任务行的双击事件
+
+  // 自定义逻辑示例:
+  // 1. 打开自定义模态框
+  openCustomModal(task)
+
+  // 2. 跳转到详情页面
+  // router.push(`/task/${task.id}`)
+
+  // 3. 调用外部API
+  // await updateTaskAPI(task)
+
+  // 4. 显示自定义消息
+  // showCustomMessage(task)
+}
+
+const openCustomModal = (task: Task) => {
+  // 实现自定义模态框逻辑
+  alert(`自定义处理: ${task.name}`)
+}
+</script>
+
+<template>
+  <!-- 使用自定义处理器，禁用默认抽屉 -->
+  <GanttChart
+    :on-task-double-click="handleTaskDoubleClick"
+    :use-default-drawer="false"
+  />
+</template>
+```
+
+### 3. TaskList与TaskBar双击一致性
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import GanttChart from './components/GanttChart.vue'
+
+const handleTaskDoubleClick = (task: Task) => {
+  console.log('任务双击事件:', task)
+  // 此处理器会同时响应：
+  // 1. Timeline中TaskBar的双击
+  // 2. TaskList中任务行的双击
+
+  // 无论用户双击任务条还是任务行，都会执行相同的逻辑
+  openTaskEditor(task)
+}
+
+const openTaskEditor = (task: Task) => {
+  // 打开自定义任务编辑器
+  console.log(`正在编辑任务: ${task.name}`)
+}
+</script>
+
+<template>  <!-- TaskList和Timeline的双击行为保持一致 -->
+  <GanttChart
+    :tasks="tasks"
+    :on-task-double-click="handleTaskDoubleClick"
+    :use-default-drawer="false"
+  />
+</template>
+```
+
+### 4. CSV导出功能使用
+
+CSV导出功能支持自定义处理器和默认实现，具有完整的多语言和UTF-8编码支持。详细文档请参考 [CSV_EXPORT.md](./CSV_EXPORT.md)
+
+#### 基本使用
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const tasks = ref([/* 你的任务数据 */])
+
+// 启用CSV导出
+const toolbarConfig = {
+  showExportCsv: true,
+  showLanguage: true, // 启用语言切换，影响CSV头部语言
+}
+
+// 可选：自定义CSV导出处理器
+const handleCsvExport = () => {
+  console.log('CSV导出')
+  // 返回false使用默认实现
+  return false
+}
+</script>
+
+<template>
+  <GanttChart
+    :tasks="tasks"
+    :toolbar-config="toolbarConfig"
+    :on-export-csv="handleCsvExport"
+  />
+</template>
+```
+
+### 5. 工具栏配置与使用
+
+工具栏采用了全新的设计，新增任务按钮独立显示，导出CSV和PDF按钮采用button group样式相连，右侧为设置类按钮。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import GanttChart from './components/GanttChart.vue'
+
+// 工具栏配置
+const toolbarConfig = ref({
+  showAddTask: true,      // 显示新增任务按钮（主色调独立按钮）
+  showExportCsv: true,    // 显示导出CSV按钮（button group左侧）
+  showExportPdf: true,    // 显示导出PDF按钮（button group右侧）
+  showLanguage: true,     // 显示语言切换按钮
+  showTheme: true,        // 显示主题切换按钮
+  showFullscreen: true    // 显示全屏切换按钮
+})
+
+// 工具栏事件处理器
+const handleAddTask = () => {
+  console.log('新增任务按钮被点击')
+  // 实现新增任务逻辑
+  // 例如：打开新增任务对话框
+  openAddTaskDialog()
+}
+
+const handleExportCsv = () => {
+  console.log('导出CSV按钮被点击')
+  // 实现CSV导出逻辑
+  exportToCsv()
+}
+
+const handleExportPdf = () => {
+  console.log('导出PDF按钮被点击')
+  // 实现PDF导出逻辑
+  exportToPdf()
+}
+
+const handleLanguageChange = (lang: 'zh' | 'en') => {
+  console.log('语言切换为:', lang)
+  // 实现语言切换逻辑
+}
+
+const handleThemeChange = (isDark: boolean) => {
+  console.log('主题切换为:', isDark ? '暗色' : '明亮')
+  // 实现主题切换逻辑
+}
+
+const handleFullscreenChange = (isFullscreen: boolean) => {
+  console.log('全屏状态:', isFullscreen ? '已进入' : '已退出')
+  // 实现全屏状态处理逻辑
+}
+
+// 业务逻辑函数示例
+const openAddTaskDialog = () => {
+  // 打开新增任务对话框的具体实现
+}
+
+const exportToCsv = () => {
+  // 导出CSV的具体实现
+  // 可以调用后端API或者前端处理
+}
+
+const exportToPdf = () => {
+  // 导出PDF的具体实现
+  // 可以调用后端API或者前端处理
+}
+</script>
+
+<template>
+  <GanttChart
+    :tasks="tasks"
+    :show-toolbar="true"
+    :toolbar-config="toolbarConfig"
+    :on-add-task="handleAddTask"
+    :on-export-csv="handleExportCsv"
+    :on-export-pdf="handleExportPdf"
+    :on-language-change="handleLanguageChange"
+    :on-theme-change="handleThemeChange"
+    :on-fullscreen-change="handleFullscreenChange"
+  />
+</template>
+```
+
+#### 工具栏样式特点
+
+- **Button Group设计**: 导出CSV和PDF按钮采用连接式设计，视觉上更加统一
+- **主操作突出**: 新增任务按钮使用主色调，突出重要操作
+- **图标化右侧**: 设置类按钮采用纯图标设计，节省空间
+- **响应式布局**: 在小屏幕设备上自动调整按钮尺寸和间距
+- **国际化支持**: 所有按钮文本和提示自动适配当前语言
+
+#### 选择性显示工具栏项
+
+```vue
+<script setup lang="ts">
+// 仅显示新增任务和导出功能，隐藏其他按钮
+const minimalToolbarConfig = ref({
+  showAddTask: true,
+  showExportCsv: true,
+  showExportPdf: true,
+  showLanguage: false,    // 隐藏语言切换
+  showTheme: false,       // 隐藏主题切换
+  showFullscreen: false   // 隐藏全屏切换
+})
+</script>
+
+<template>
+  <!-- 最小化工具栏配置 -->
+  <GanttChart
+    :toolbar-config="minimalToolbarConfig"
+    :on-add-task="handleAddTask"
+    :on-export-csv="handleExportCsv"
+    :on-export-pdf="handleExportPdf"
+  />
+</template>
+```
+
+#### 完全隐藏工具栏
+
+```vue
+<template>
+  <!-- 隐藏工具栏，使用纯甘特图 -->
+  <GanttChart
+    :show-toolbar="false"
+    :tasks="tasks"
+  />
+</template>
+```
+
+> **说明**: TaskList中任务行的双击与Timeline中TaskBar的双击具有完全相同的API行为和优先级机制，确保用户体验的一致性。
+
+### 4. 条件性使用不同处理器
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+import GanttChart from './components/GanttChart.vue'
+
+const useCustomHandler = ref(false)
+
+const handleCustomTaskDoubleClick = (task: Task) => {
+  // 自定义处理逻辑
+  console.log('使用自定义处理器:', task)
+}
+
+// 根据条件决定使用哪种处理器
+const doubleClickHandler = computed(() => {
+  return useCustomHandler.value ? handleCustomTaskDoubleClick : undefined
+})
+</script>
+
+<template>
+  <div>
+    <label>
+      <input type="checkbox" v-model="useCustomHandler" />
+      使用自定义处理器
+    </label>
+
+    <GanttChart
+      :on-task-double-click="doubleClickHandler"
+      :use-default-drawer="!useCustomHandler"
+    />
+  </div>
+</template>
+```
+
+### 4. 自定义删除处理器
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import GanttChart from './components/GanttChart.vue'
+
+// 自定义删除事件处理器
+const handleCustomTaskDelete = async (task: Task) => {
+  console.log('自定义删除处理器被调用:', task)
+
+  // 自定义删除逻辑示例:
+  try {
+    // 1. 调用后端API删除
+    await fetch(`/api/tasks/${task.id}`, { method: 'DELETE' })
+
+    // 2. 更新本地状态
+    // store.dispatch('deleteTask', task.id)
+
+    // 3. 显示自定义成功消息
+    showNotification(`任务 "${task.name}" 已成功删除`, 'success')
+
+    // 4. 可以触发其他业务逻辑
+    // trackDeleteEvent(task)
+
+  } catch (error) {
+    console.error('删除失败:', error)
+    showNotification('删除失败，请重试', 'error')
+  }
+}
+
+const showNotification = (message: string, type: string) => {
+  // 实现自定义通知逻辑
+  console.log(`${type}: ${message}`)
+}
+</script>
+
+<template>
+  <GanttChart
+    :on-task-delete="handleCustomTaskDelete"
+  />
+</template>
+```
+
+### 5. 完整的自定义处理器组合
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import GanttChart from './components/GanttChart.vue'
+
+// 自定义双击处理器
+const handleTaskDoubleClick = (task: Task) => {
+  // 打开自定义编辑界面
+  router.push(`/tasks/${task.id}/edit`)
+}
+
+// 自定义删除处理器
+const handleTaskDelete = async (task: Task) => {
+  // 使用自定义确认对话框
+  const confirmed = await showCustomConfirm(
+    '删除确认',
+    `确定要删除任务 "${task.name}" 吗？`,
+    'warning'
+  )
+
+  if (confirmed) {
+    await api.deleteTask(task.id)
+    showMessage('删除成功', 'success')
+  }
+}
+</script>
+
+<template>
+  <GanttChart
+    :on-task-double-click="handleTaskDoubleClick"
+    :on-task-delete="handleTaskDelete"
+    :use-default-drawer="false"
+  />
+</template>
+```
+
+## 🏗️ 组件架构
+
+### 组件层次结构
+```
+GanttChart (入口组件，API配置)
+├── TaskList (左侧任务列表)
+├── Timeline (右侧时间轴区域)
+    ├── TaskBar (任务条，支持双击事件)
+    ├── Milestone (里程碑)
+    └── TaskDrawer (默认编辑抽屉)
+```
+
+### API 数据流
+1. `GanttChart` 接收API配置props
+2. 透传给 `Timeline` 组件
+3. `Timeline` 将API配置传递给 `TaskBar`
+4. `TaskBar` 双击时调用API处理器或触发默认行为
+
+### 内置功能
+- ✅ 拖拽调整任务时间
+- ✅ 调整任务条长度
+- ✅ 任务进度显示
+- ✅ 前置任务依赖关系
+- ✅ 父子任务层级结构
+- ✅ 时间轴缩放和导航
+- ✅ 自定义双击事件API
+
+## 🔧 技术特性
+
+- **Framework**: Vue 3 + TypeScript + Vite
+- **样式**: 延续Element Plus设计风格，无外部依赖
+- **响应式**: 完全使用Vue 3 Composition API
+- **类型安全**: 完整的TypeScript接口定义
+- **可扩展**: 灵活的API设计，支持自定义扩展
+
+## 🛠️ 高级用法
+
+### 完整示例：集成自定义编辑功能
+
+```vue
+<template>
+  <div class="gantt-container">
+    <!-- Gantt图表 -->
+    <GanttChart
+      :on-task-double-click="handleTaskDoubleClick"
+      :use-default-drawer="!useCustomEditor"
+    />
+
+    <!-- 自定义编辑模态框 -->
+    <div v-if="showCustomModal" class="custom-modal-overlay" @click="closeModal">
+      <div class="custom-modal" @click.stop>
+        <div class="modal-header">
+          <h3>编辑任务: {{ currentTask?.name }}</h3>
+          <button @click="closeModal" class="close-btn">×</button>
+        </div>
+        <div class="modal-body">
+          <form @submit.prevent="saveTask">
+            <div class="form-group">
+              <label>任务名称:</label>
+              <input v-model="editingTask.name" type="text" required />
+            </div>
+            <div class="form-group">
+              <label>开始日期:</label>
+              <input v-model="editingTask.startDate" type="date" required />
+            </div>
+            <div class="form-group">
+              <label>结束日期:</label>
+              <input v-model="editingTask.endDate" type="date" required />
+            </div>
+            <div class="form-group">
+              <label>完成进度:</label>
+              <input v-model.number="editingTask.progress" type="number" min="0" max="100" />
+            </div>
+          </form>
+        </div>
+        <div class="modal-footer">
+          <button @click="closeModal" class="btn-cancel">取消</button>
+          <button @click="saveTask" class="btn-save">保存</button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive } from 'vue'
+import GanttChart from './components/GanttChart.vue'
+
+interface Task {
+  id: number
+  name: string
+  startDate: string
+  endDate: string
+  progress?: number
+  isParent?: boolean
+  predecessor?: number
+  type?: string
+}
+
+// 状态管理
+const useCustomEditor = ref(true)
+const showCustomModal = ref(false)
+const currentTask = ref<Task | null>(null)
+const editingTask = reactive<Partial<Task>>({})
+
+// 自定义双击处理器
+const handleTaskDoubleClick = (task: Task) => {
+  currentTask.value = task
+
+  // 复制任务数据到编辑状态
+  Object.assign(editingTask, {
+    id: task.id,
+    name: task.name,
+    startDate: task.startDate,
+    endDate: task.endDate,
+    progress: task.progress || 0
+  })
+
+  showCustomModal.value = true
+}
+
+// 关闭模态框
+const closeModal = () => {
+  showCustomModal.value = false
+  currentTask.value = null
+  Object.keys(editingTask).forEach(key => {
+    delete editingTask[key as keyof typeof editingTask]
+  })
+}
+
+// 保存任务
+const saveTask = () => {
+  if (!currentTask.value) return
+
+  // 这里可以调用API保存数据
+  console.log('保存任务:', editingTask)
+
+  // 触发任务更新事件
+  window.dispatchEvent(new CustomEvent('task-updated', {
+    detail: { ...currentTask.value, ...editingTask }
+  }))
+
+  closeModal()
+}
+</script>
+
+<style scoped>
+.gantt-container {
+  width: 100%;
+  height: 100%;
+  position: relative;
+}
+
+.custom-modal-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(0, 0, 0, 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+}
+
+.custom-modal {
+  background: white;
+  border-radius: 8px;
+  width: 500px;
+  max-width: 90vw;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+}
+
+.modal-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 20px;
+  border-bottom: 1px solid #eee;
+}
+
+.modal-header h3 {
+  margin: 0;
+  color: #333;
+}
+
+.close-btn {
+  background: none;
+  border: none;
+  font-size: 24px;
+  cursor: pointer;
+  color: #999;
+}
+
+.modal-body {
+  padding: 20px;
+}
+
+.form-group {
+  margin-bottom: 16px;
+}
+
+.form-group label {
+  display: block;
+  margin-bottom: 4px;
+  color: #333;
+  font-weight: 500;
+}
+
+.form-group input {
+  width: 100%;
+  padding: 8px 12px;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 14px;
+}
+
+.modal-footer {
+  display: flex;
+  justify-content: flex-end;
+  gap: 12px;
+  padding: 20px;
+  border-top: 1px solid #eee;
+}
+
+.btn-cancel, .btn-save {
+  padding: 8px 16px;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 14px;
+}
+
+.btn-cancel {
+  background: #f5f5f5;
+  color: #666;
+}
+
+.btn-save {
+  background: #409eff;
+  color: white;
+}
+</style>
+```
+
+## ⚡ 性能优化建议
+
+1. **事件处理器缓存**: 使用 `computed` 或 `useMemo` 缓存事件处理器，避免不必要的重新渲染
+
+2. **异步处理**: 对于复杂的双击处理逻辑，建议使用异步函数
+
+```vue
+<script setup lang="ts">
+const handleTaskDoubleClick = async (task: Task) => {
+  try {
+    // 显示加载状态
+    loading.value = true
+
+    // 异步处理
+    await processTask(task)
+  } catch (error) {
+    console.error('处理任务失败:', error)
+  } finally {
+    loading.value = false
+  }
+}
+</script>
+```
+
+3. **防抖处理**: 对于可能触发频繁操作的场景，考虑添加防抖
+
+```vue
+<script setup lang="ts">
+import { debounce } from 'lodash-es'
+
+const debouncedHandler = debounce((task: Task) => {
+  // 实际处理逻辑
+  console.log('处理任务:', task)
+}, 300)
+</script>
+```
+
+## 🔧 故障排除
+
+### 常见问题
+
+1. **Q: 双击事件不触发？**
+   - A: 检查是否正确传递了 `onTaskDoubleClick` 属性，并确保 `useDefaultDrawer` 设置正确
+
+2. **Q: 同时使用自定义处理器和默认Drawer？**
+   - A: 当 `onTaskDoubleClick` 存在时，会优先调用自定义处理器，默认Drawer不会打开
+
+3. **Q: 如何在自定义处理器中获取更多任务信息？**
+   - A: 可以通过全局状态管理或者父组件传递更多上下文信息
+
+4. **Q: 自定义处理器中的异步操作报错？**
+   - A: 确保在异步操作中添加try-catch错误处理，避免未捕获的异常
+
+### 调试技巧
+
+```vue
+<script setup lang="ts">
+// 启用调试模式
+const debugMode = ref(true)
+
+const handleTaskDoubleClick = (task: Task) => {
+  if (debugMode.value) {
+    console.log('双击事件触发:', {
+      task,
+      timestamp: new Date().toISOString(),
+      component: 'TaskBar'
+    })
+  }
+
+  // 你的处理逻辑...
+}
+</script>
+```
+
+## ⚡ 性能优化
+
+### 1. 事件处理器缓存
+```vue
+<script setup lang="ts">
+import { computed } from 'vue'
+
+// 使用computed缓存处理器，避免不必要的重新渲染
+const taskDoubleClickHandler = computed(() => {
+  return (task: Task) => {
+    // 处理逻辑
+  }
+})
+</script>
+
+<template>
+  <GanttChart :on-task-double-click="taskDoubleClickHandler" />
+</template>
+```
+
+### 2. 异步处理优化
+```vue
+<script setup lang="ts">
+const loading = ref(false)
+
+const handleTaskDoubleClick = async (task: Task) => {
+  try {
+    // 显示加载状态
+    loading.value = true
+
+    // 异步处理
+    await processTaskAsync(task)
+  } catch (error) {
+    console.error('处理任务失败:', error)
+    // 显示错误提示
+  } finally {
+    loading.value = false
+  }
+}
+</script>
+```
+
+### 3. 防抖处理
+```vue
+<script setup lang="ts">
+import { debounce } from 'lodash-es'
+
+const debouncedHandler = debounce((task: Task) => {
+  // 实际处理逻辑
+  console.log('处理任务:', task)
+}, 300)
+</script>
+```
+
+## 🎯 最佳实践
+
+### 1. 代码组织
+- **保持处理器简洁**: 双击处理器应该保持轻量，复杂逻辑建议抽取到单独的函数中
+- **类型安全**: 充分利用TypeScript的类型检查，确保Task接口一致性
+- **职责分离**: 将业务逻辑与UI逻辑分离
+
+### 2. 用户体验
+- **即时反馈**: 为用户操作提供即时的视觉反馈
+- **错误处理**: 始终为异步操作添加错误处理和用户友好的错误提示
+- **加载状态**: 为长时间运行的操作提供适当的加载提示
+- **可访问性**: 确保自定义交互也支持键盘导航和屏幕阅读器
+
+### 3. 性能考虑
+- **避免内存泄漏**: 及时清理事件监听器和定时器
+- **合理使用响应式**: 不要过度使用reactive，对于简单数据使用ref
+- **组件懒加载**: 对于复杂的自定义组件考虑懒加载
+
+### 4. 兼容性设计
+```vue
+<script setup lang="ts">
+// 提供降级方案
+const handleTaskDoubleClick = (task: Task) => {
+  try {
+    // 主要逻辑
+    processTask(task)
+  } catch (error) {
+    // 降级处理
+    console.warn('使用降级方案')
+    fallbackHandler(task)
+  }
+}
+</script>
+```
+
+## 🚀 扩展开发
+
+### 自定义事件系统
+```vue
+<script setup lang="ts">
+// 定义自定义事件
+const emit = defineEmits<{
+  'task-clicked': [task: Task]
+  'task-updated': [task: Task]
+  'task-deleted': [taskId: number]
+}>()
+
+const handleTaskDoubleClick = (task: Task) => {
+  // 处理双击逻辑
+
+  // 发出自定义事件
+  emit('task-clicked', task)
+}
+</script>
+```
+
+### 插件化架构
+```typescript
+// 定义插件接口
+interface GanttPlugin {
+  name: string
+  onTaskDoubleClick?: (task: Task) => void
+  onTaskCreate?: (task: Task) => void
+  onTaskUpdate?: (task: Task) => void
+}
+
+// 使用插件
+const ganttPlugins: GanttPlugin[] = [
+  {
+    name: 'analytics',
+    onTaskDoubleClick: (task) => {
+      // 分析统计逻辑
+    }
+  }
+]
+```
+
+## 📝 更新日志
+
+- **v0.2.0-beta**: 工具栏集成与Button Group优化
+  - ✅ 新增GanttToolbar工具栏组件，支持完整的功能配置
+  - ✅ 导出CSV和PDF按钮采用Button Group样式，视觉统一
+  - ✅ 新增任务按钮独立显示，采用主色调突出重要操作
+  - ✅ 右侧设置按钮采用图标化设计，支持语言、主题、全屏切换
+  - ✅ 工具栏支持国际化，内置中英文切换
+  - ✅ 响应式设计，在小屏幕设备上自动调整布局
+  - ✅ 支持选择性显示工具栏项，完全可配置
+
+- **v1.0.0**: 初始API发布
+  - ✅ 支持自定义双击处理器 (`onTaskDoubleClick`)
+  - ✅ 支持禁用默认编辑抽屉 (`useDefaultDrawer`)
+  - ✅ 完整的TypeScript类型支持
+  - ✅ Element Plus风格设计，无外部依赖
+
+- **规划中**:
+  - 🔄 自定义编辑组件支持 (`editComponent`)
+  - 🔄 更多事件API（创建、删除、拖拽等）
+  - 🔄 主题定制API
+  - 🔄 插件系统
+
+## 🤝 贡献指南
+
+欢迎提交Issue和Pull Request来改进这个组件！
+
+### 开发环境设置
+```bash
+# 克隆项目
+git clone <repository-url>
+
+# 安装依赖
+npm install
+
+# 启动开发服务器
+npm run dev
+
+# 构建项目
+npm run build
+```
+
+### 代码规范
+- 使用TypeScript进行类型安全开发
+- 遵循Vue 3 Composition API最佳实践
+- 保持代码简洁和可读性
+- 添加适当的注释和文档
+
+---
+
+🎉 **通过这些API，您可以完全自定义TaskBar的交互行为，打造符合您项目需求的甘特图体验！**
+
+> 如有问题或建议，欢迎提交Issue或联系开发团队。
diff --git a/demo/VersionHistoryDrawer.vue b/demo/VersionHistoryDrawer.vue
index 891b745..35fcd88 100644
--- a/demo/VersionHistoryDrawer.vue
+++ b/demo/VersionHistoryDrawer.vue
@@ -233,9 +233,6 @@ onMounted(async () => {
   top: 18px;
   width: 0;
   height: 0;
-  /*border-top: 6px solid transparent;
-  border-bottom: 6px solid transparent;
-  border-right: 16px solid #fff;*/
   filter: drop-shadow(-2px 0 2px var(--gantt-timeline-line, #a0cfff));
   z-index: 1;
 }
diff --git a/src/components/DatePicker.vue b/src/components/DatePicker.vue
index 2175f7f..8074a9b 100644
--- a/src/components/DatePicker.vue
+++ b/src/components/DatePicker.vue
@@ -97,7 +97,7 @@ watch(
       singleValue.value = (newValue as string) || ''
     }
   },
-  { immediate: true },
+  { immediate: true }
 )
 
 // 处理单日期输入变化（预留，当前版本不使用）
@@ -569,9 +569,6 @@ const showClearButton = computed(() => {
 
 // 计算面板位置
 const panelStyle = computed(() => {
-  // 依赖 positionUpdateKey 来强制重新计算
-  positionUpdateKey.value // eslint-disable-line no-unused-expressions
-
   if (!inputRef.value || !showPicker.value) return {}
 
   const rect = inputRef.value.getBoundingClientRect()