jordium-gantt-vue3 1.1.0 → 1.3.0

package/README.md

@@ -56,36 +56,75 @@ pnpm add jordium-gantt-vue3
 
 ---
 
-> 💡 **徽章下载**：
-> - npm 版本徽章：https://img.shields.io/npm/v/jordium-gantt-vue3.svg
-> - MIT 许可证徽章：https://img.shields.io/badge/license-MIT-blue.svg
-> - Vue 版本徽章：https://img.shields.io/badge/vue-3.x-green.svg
-> - TypeScript 徽章：https://img.shields.io/badge/typescript-5.x-blue.svg
-
 ## 📁 项目结构
 
 ```
 jordium-gantt-vue3/
-├── src/                      # 源码目录
-│   ├── components/           # 核心组件
-│   │   ├── GanttChart.vue   # 主入口组件
-│   │   ├── TaskList.vue     # 任务列表
-│   │   ├── Timeline.vue     # 时间轴
-│   │   ├── TaskBar.vue      # 任务条
-│   │   ├── MilestonePoint.vue # 里程碑
-│   │   └── ...              # 其他组件
-│   ├── models/              # 数据模型
-│   │   ├── classes/         # 类定义
-│   │   └── configs/         # 配置接口
-│   ├── composables/         # 组合式函数
-│   ├── styles/              # 样式文件
-│   └── index.ts             # 导出入口
-├── demo/                    # 开发演示
-├── dist/                    # 构建产物
-├── docs/                    # 文档
-└── package.json
+├── src/                      # 组件源码与核心逻辑
+│   ├── components/           # 主要 Vue 组件
+│   │   ├── GanttChart.vue    # 主入口组件
+│   │   ├── TaskList.vue      # 任务列表
+│   │   ├── Timeline.vue      # 时间轴组件
+│   │   ├── TaskBar.vue       # 任务条
+│   │   ├── TaskDrawer.vue    # 任务编辑抽屉
+│   │   ├── TaskContextMenu.vue # 任务右键菜单
+│   │   ├── GanttToolbar.vue  # 工具栏
+│   │   ├── MilestonePoint.vue # 里程碑点
+│   │   ├── MilestoneDialog.vue # 里程碑对话框
+│   │   ├── DatePicker.vue    # 日期选择器
+│   │   └── ...               # 其他组件
+│   ├── models/               # 数据模型与配置
+│   │   ├── classes/          # 类定义
+│   │   │   ├── Task.ts       # 任务模型
+│   │   │   ├── Milestone.ts  # 里程碑模型
+│   │   │   └── Language.ts   # 语言配置
+│   │   ├── configs/          # 配置接口
+│   │   │   ├── TimelineConfig.ts # 时间轴配置
+│   │   │   └── ToolbarConfig.ts  # 工具栏配置
+│   │   └── types/            # 类型定义
+│   │       └── TimelineScale.ts  # 时间刻度类型
+│   ├── composables/          # 组合式函数
+│   │   ├── useI18n.ts        # 国际化工具
+│   │   └── useMessage.ts     # 消息提示工具
+│   ├── styles/               # 样式文件
+│   │   ├── app.css           # 主样式
+│   │   └── theme-variables.css # 主题变量
+│   ├── utils/                # 工具函数
+│   │   └── predecessorUtils.ts # 前置依赖工具
+│   └── index.ts              # 入口导出
+├── demo/                     # 组件开发与交互演示（本地开发/预览用）
+│   ├── App.vue               # 演示应用主组件
+│   ├── data.json             # 演示数据（包含药物临床试验案例）
+│   ├── main.ts               # 演示应用入口
+│   └── ...                   # 其他演示文件
+├── packageDemo/              # npm 包集成演示（模拟外部项目集成效果）
+├── dist/                     # 构建产物（发布/静态站点/打包输出）
+├── docs/                     # 相关文档（如部署、API 说明等）
+├── design/                   # 设计资源与截图
+│   └── screenshots/          # 主题截图
+├── public/                   # 公共静态资源
+│   └── assets/               # 静态资源文件
+├── README.md                 # 中文说明文档
+├── README-EN.md              # 英文说明文档
+├── package.json              # 项目配置
+├── vite.config.ts            # Vite开发配置
+├── vite.config.lib.ts        # Vite库构建配置
+├── tsconfig.json             # TypeScript配置
+└── ...                       # 其他配置、脚本与元数据
 ```
 
+### 目录说明
+
+- **`src/components/`**：核心Vue组件，包含甘特图的所有功能组件
+- **`src/models/`**：数据模型、类型定义和配置接口
+- **`src/composables/`**：Vue 3组合式函数，提供可复用的逻辑
+- **`src/styles/`**：样式文件，包含主题系统和CSS变量
+- **`src/utils/`**：工具函数，处理业务逻辑和数据转换
+- **`demo/`**：本地开发和功能演示，包含完整的交互页面和药物临床试验样例数据
+- **`packageDemo/`**：模拟npm包在外部项目中的集成与使用场景
+- **`dist/`**：构建输出目录，包含发布到npm或静态站点的产物
+- **`docs/`**：项目文档，包括部署说明、API参考等
+
 ## 🔧 API 参考
 
 ### GanttChart 属性
@@ -99,8 +138,22 @@ jordium-gantt-vue3/
 | `showToolbar` | `boolean` | `true` | 是否显示工具栏 |
 | `toolbarConfig` | `ToolbarConfig` | `{}` | 工具栏配置 |
 | `localeMessages` | `Partial<Messages['zh-CN']>` | - | 自定义多语言配置 |
+| `workingHours` | `WorkingHours` | - | 工作时间配置 |
 | `onTaskDoubleClick` | `(task: Task) => void` | - | 任务双击事件回调 |
-| `onTaskDelete` | `(task: Task) => void` | - | 任务删除事件回调 |
+| `onTaskDelete` | `(task: Task, deleteChildren?: boolean) => void` | - | 任务删除事件回调 |
+| `onTaskUpdate` | `(task: Task) => void` | - | 任务更新事件回调 |
+| `onTaskAdd` | `(task: Task) => void` | - | 任务添加事件回调 |
+| `onMilestoneSave` | `(milestone: Task) => void` | - | 里程碑保存事件回调 |
+| `onMilestoneDelete` | `(milestoneId: number) => void` | - | 里程碑删除事件回调 |
+| `onMilestoneIconChange` | `(milestoneId: number, icon: string) => void` | - | 里程碑图标变更事件回调 |
+| `onAddTask` | `() => void` | - | 新增任务工具栏事件回调 |
+| `onAddMilestone` | `() => void` | - | 新增里程碑工具栏事件回调 |
+| `onTodayLocate` | `() => void` | - | 定位今天工具栏事件回调 |
+| `onExportCsv` | `() => boolean \| void` | - | 导出CSV工具栏事件回调 |
+| `onExportPdf` | `() => void` | - | 导出PDF工具栏事件回调 |
+| `onLanguageChange` | `(lang: 'zh-CN' \| 'en-US') => void` | - | 语言切换工具栏事件回调 |
+| `onThemeChange` | `(isDark: boolean) => void` | - | 主题切换工具栏事件回调 |
+| `onFullscreenChange` | `(isFullscreen: boolean) => void` | - | 全屏切换工具栏事件回调 |
 | `onTaskUpdate` | `(task: Task) => void` | - | 任务更新事件回调 |
 | `onTaskAdd` | `(task: Task) => void` | - | 任务添加事件回调 |
 | `onMilestoneSave` | `(milestone: Task) => void` | - | 里程碑保存事件回调 |
@@ -117,11 +170,72 @@ jordium-gantt-vue3/
 
 ### GanttChart 事件
 
-| 事件名 | 参数 | 说明 |
-|--------|------|------|
+| 事件名                | 参数                        | 说明                         |
+|----------------------|----------------------------|------------------------------|
 | `taskbar-drag-end` | `task: Task` | 任务条拖拽结束 |
 | `taskbar-resize-end` | `task: Task` | 任务条大小调整结束 |
 | `milestone-drag-end` | `milestone: Task` | 里程碑拖拽结束 |
+| `predecessor-added`  | `{ targetTask, newTask }`   | 添加前置任务后触发。<br>参数说明：<br>• `targetTask`：被添加前置任务的目标任务（Task对象）<br>• `newTask`：新添加的前置任务（Task对象） |
+| `successor-added`    | `{ targetTask, newTask }`   | 添加后置任务后触发。<br>参数说明：<br>• `targetTask`：被添加后置任务的目标任务（Task对象）<br>• `newTask`：新添加的后置任务（Task对象） |
+| `task-deleted`       | `{ task }`                  | 删除任务后触发               |
+| `task-added`         | `{ task }`                  | 新建任务后触发               |
+| `task-updated`       | `{ task }`                  | 更新任务后触发               |
+
+#### 计时事件用法示例
+
+```vue
+<GanttChart
+  ...
+  @timer-started="onTimerStarted"
+  @timer-stopped="onTimerStopped"
+/>
+
+<script setup>
+function onTimerStarted(task) {
+  // 这里可以自定义提示、日志或业务逻辑
+  alert(`任务【${task.name}】开始计时：${new Date(task.timerStartTime).toLocaleString()}`)
+}
+function onTimerStopped(task) {
+  alert(`任务【${task.name}】停止计时`)
+}
+</script>
+```
+
+#### 任务事件用法示例
+
+```vue
+<GanttChart
+  ...
+  @predecessor-added="onPredecessorAdded"
+  @successor-added="onSuccessorAdded"
+  @task-deleted="onTaskDeleted"
+  @task-added="onTaskAdded"
+  @task-updated="onTaskUpdated"
+/>
+
+<script setup>
+function onPredecessorAdded(e) {
+  // e: { targetTask: Task, newTask: Task }
+  alert(`任务【${e.targetTask.name}】添加前置任务【${e.newTask.name}】`)
+}
+function onSuccessorAdded(e) {
+  // e: { targetTask: Task, newTask: Task }
+  alert(`任务【${e.targetTask.name}】添加后置任务【${e.newTask.name}】`)
+}
+function onTaskDeleted(e) {
+  // e: { task: Task }
+  alert(`任务【${e.task.name}】已删除`)
+}
+function onTaskAdded(e) {
+  // e: { task: Task }
+  alert(`任务【${e.task.name}】已创建`)
+}
+function onTaskUpdated(e) {
+  // e: { task: Task }
+  alert(`任务【${e.task.name}】已更新`)
+}
+</script>
+```
 
 ### 数据类型
 
@@ -129,24 +243,30 @@ jordium-gantt-vue3/
 
 **Task 任务类型**
 ```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         // 实际工时
-  parentId?: number            // 上级任务ID
-  children?: Task[]            // 子任务数组（支持嵌套结构）
-  collapsed?: boolean          // 是否折叠子任务
-  isParent?: boolean           // 是否为父级任务
-  type?: string               // 任务类型 (task/story/bug/milestone)
-  description?: string         // 任务描述
-  icon?: string               // 任务图标
-  level?: number              // 任务层级
+export interface Task {
+  id: number                  // 任务唯一ID
+  name: string               // 任务名称
+  predecessor?: number[]     // 前置任务ID数组
+  assignee?: string          // 负责人
+  startDate?: string         // 开始日期（ISO字符串）
+  endDate?: string           // 结束日期（ISO字符串）
+  progress?: number          // 进度百分比 0-100
+  estimatedHours?: number    // 预估工时（支持小数，最多2位）
+  actualHours?: number       // 实际工时（支持小数，最多2位）
+  parentId?: number          // 上级任务ID
+  children?: Task[] // 子任务数组
+  collapsed?: boolean // 是否折叠
+  isParent?: boolean // 是否为父任务
+  type?: string // 任务类型（如 task、story、milestone 等）
+  description?: string // 任务描述
+  icon?: string // 图标
+  level?: number // 层级
+  // 计时相关字段
+  isTimerRunning?: boolean // 计时是否进行中
+  timerStartTime?: number // 计时开始时间（时间戳）
+  timerEndTime?: number // 计时结束时间（时间戳）
+  timerStartDesc?: string // 计时开始时的描述
+  timerElapsedTime?: number // 已累计计时时长（秒）
 }
 ```
 
@@ -193,6 +313,86 @@ interface ToolbarConfig {
 }
 ```
 
+**WorkingHours 工作时间配置**
+```typescript
+interface WorkingHours {
+  morning?: { start: number; end: number }    // 上午工作时间，如 { start: 8, end: 11 }
+  afternoon?: { start: number; end: number }  // 下午工作时间，如 { start: 13, end: 17 }
+}
+```
+
+**TimelineScale 时间刻度类型**
+```typescript
+// 时间轴显示刻度类型
+type TimelineScale = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'
+
+// 时间刻度常量
+export const TimelineScale = {
+  HOUR: 'hour',        // 小时视图 - 每列显示一小时
+  DAY: 'day',          // 日视图 - 每列显示一天
+  WEEK: 'week',        // 周视图 - 每列显示一周  
+  MONTH: 'month',      // 月视图 - 每列显示一个月
+  QUARTER: 'quarter',  // 季度视图 - 每列显示一个季度
+  YEAR: 'year',        // 年视图 - 每列显示一年
+}
+
+// 时间刻度配置
+interface TimelineScaleConfig {
+  scale: TimelineScale    // 刻度类型
+  cellWidth: number       // 每个时间单元的宽度(px)
+  headerLevels: number    // 表头层级数
+  formatters: {
+    primary: string       // 主要时间标签格式
+    secondary?: string    // 次要时间标签格式
+  }
+}
+```
+
+### 🕐 时间刻度功能说明
+
+组件支持多种时间刻度显示，用户可以通过工具栏的日/周/月按钮组或者编程方式切换时间轴的显示粒度：
+
+#### 内置刻度配置
+
+| 刻度类型 | 单元宽度 | 主标签格式 | 副标签格式 | 适用场景 |
+|----------|----------|------------|------------|----------|
+| `hour` | 40px | yyyy/MM/dd | HH | 精确到小时的项目, 例如药物临床试验 |
+| `day` | 30px | yyyy年MM月 | dd | 日常项目管理的标准视图 |
+| `week` | 120px | yyyy年MM月 | W | 中期项目的周计划视图 |
+| `month` | 180px | yyyy | MM | 长期项目的月度视图 |
+| `quarter` | 360px | yyyy | Q | 战略规划的季度视图 |
+| `year` | 360px | yyyy | 上半年\|下半年 | 超长期项目年度视图 |
+
+#### 使用示例
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { GanttChart, TimelineScale } from 'jordium-gantt-vue3'
+
+const tasks = ref([/* 任务数据 */])
+
+// 工具栏配置 - 启用时间刻度切换按钮
+const toolbarConfig = {
+  showTimeScale: true  // 显示日|周|月按钮组
+}
+
+// 监听刻度切换（可选）
+const handleTimeScaleChange = (scale) => {
+  console.log('时间刻度切换至:', scale)
+  // 可以在这里做一些业务逻辑，如保存用户偏好设置
+}
+</script>
+
+<template>
+  <GanttChart
+    :tasks="tasks"
+    :toolbar-config="toolbarConfig"
+    @timescale-changed="handleTimeScaleChange"
+  />
+</template>
+```
+
 #### 组合式函数 (src/composables)
 
 **useI18n 国际化工具**
@@ -322,15 +522,15 @@ import { GanttChart } from 'jordium-gantt-vue3'
 
 // 工具栏配置
 const toolbarConfig = {
-  showLanguage: true,
-  showTheme: true,
-  showAddTask: true,
-  showAddMilestone: true,
-  showTodayLocate: true,
-  showExportCsv: true,
-  showExportPdf: true,
-  showFullscreen: true,
-  showTimeScale: true  // 控制日|周|月时间刻度按钮组的可见性
+  showLanguage: true,      // 语言切换
+  showTheme: true,         // 主题切换
+  showAddTask: true,       // 新增任务
+  showAddMilestone: true,  // 新增里程碑
+  showTodayLocate: true,   // 定位今天
+  showExportCsv: true,     // 导出CSV
+  showExportPdf: true,     // 导出PDF
+  showFullscreen: true,    // 全屏模式
+  showTimeScale: true      // 时间刻度切换（日|周|月按钮组）
 }
 
 // 自定义多语言配置
@@ -347,6 +547,17 @@ const handleLanguageChange = (lang) => {
 const handleThemeChange = (isDark) => {
   console.log('主题切换到:', isDark ? '暗色' : '亮色')
 }
+
+// 监听时间刻度变化
+const handleTimeScaleChange = (scale) => {
+  console.log('时间刻度切换至:', scale)
+  // 根据刻度调整显示逻辑
+  if (scale === 'day') {
+    // 日视图下的特殊处理
+  } else if (scale === 'week') {
+    // 周视图下的特殊处理  
+  }
+}
 </script>
 
 <template>
@@ -357,10 +568,51 @@ const handleThemeChange = (isDark) => {
     :locale-messages="customLocaleMessages"
     :on-language-change="handleLanguageChange"
     :on-theme-change="handleThemeChange"
+    @timescale-changed="handleTimeScaleChange"
+  />
+</template>
+```
+
+### 🔧 工作时间配置
+
+组件支持设置工作时间，影响任务时长计算和进度显示：
+
+```vue
+<script setup lang="ts">
+// 配置工作时间（24小时制）
+const workingHours = {
+  morning: { start: 9, end: 12 },    // 上午9点-12点
+  afternoon: { start: 14, end: 18 }  // 下午2点-6点
+}
+</script>
+
+<template>
+  <GanttChart
+    :tasks="tasks"
+    :working-hours="workingHours"
   />
 </template>
 ```
 
+### 📊 高精度工时管理
+
+组件支持精确到小数点后2位的工时记录，适合需要精确计费的项目：
+
+```vue
+<script setup lang="ts">
+const tasks = ref([
+  {
+    id: 1,
+    name: '高精度任务',
+    estimatedHours: 8.75,    // 8小时45分钟
+    actualHours: 7.25,       // 7小时15分钟
+    startDate: '2025-01-01',
+    endDate: '2025-01-02'
+  }
+])
+</script>
+```
+
 ## 🤝 贡献与合作
 
 ### 参与贡献