chbim-time-axis-v2 0.0.8 → 0.0.11

package/README.md

@@ -4,67 +4,54 @@
 [![License](https://img.shields.io/npm/l/chbim-time-axis-v2.svg?style=flat-square)](https://www.npmjs.com/package/chbim-time-axis-v2)
 [![Downloads](https://img.shields.io/npm/dt/chbim-time-axis-v2.svg?style=flat-square)](https://www.npmjs.com/package/chbim-time-axis-v2)
 
-一个专为 Vue 3 设计的甘特图组件，完美集成 Cesium 时间轴功能。
-
-## ✨ 特性
-
-- 🤝 **Cesium 集成**: 与 Cesium Viewer 和 Timeline 无缝同步，实现二三维联动。
-- 📅 **多功能甘特图**: 支持任务组、普通任务、时间块（Block）和瞬时点（Instant）多种类型。
-- 🎨 **高度可定制**: 提供丰富的插槽（Slots）和事件（Events）以满足不同业务需求。
-- ⚡ **TypeScript 支持**: 提供完整的类型定义，开发体验更佳。
+一个专为 Vue 3 + Cesium 设计的甘特图组件。它不仅是一个任务管理工具，更是连接二维时间数据与三维空间展示的桥梁。
+
+## ✨ 核心特性
+
+- **🤝 深度 Cesium 集成**:
+  - **双向同步**: 甘特图的时间轴与 Cesium Viewer 的时钟（Clock）完全同步。拖动甘特图时间轴会更新 Cesium 场景时间，反之亦然。
+  - **二三维联动**: 当时间轴播放到特定任务时，会触发事件，方便开发者在三维场景中控制模型的显隐、动画等。
+- **📅 多维任务模型**:
+  - **普通任务 (Task)**: 标准的起止时间任务。
+  - **任务组 (Group)**: 可折叠的任务容器，支持自动计算时间范围和手动限制范围。
+  - **时间块 (Block)**: 单个任务行内包含多个不连续的时间段（如间歇性作业）。
+  - **瞬时点 (Instant)**: 标记特定时间点的关键事件（如里程碑、检查点）。
+- **🎨 高度可定制**:
+  - **插槽 (Slots)**: 提供工具栏、任务操作列、右键菜单等多个插槽，满足个性化 UI 需求。
+  - **样式**: 支持自定义任务颜色、瞬时点颜色等。
+- **⚡ 开发体验**:
+  - **TypeScript**: 提供完整的类型定义。
+  - **Vue 3**: 基于 Composition API 构建，响应式性能优秀。
 
 ## 📦 安装
 
-使用 npm 或 yarn 安装：
-
 ```bash
 npm install chbim-time-axis-v2
-# 或者
-yarn add chbim-time-axis-v2
 ```
 
-## 🚀 使用指南
+## 🚀 快速开始
 
-### 1. 全局注册（可选）
+### 1. 引入样式
 
-在 `main.ts` 中引入并注册：
+在你的入口文件（如 `main.ts`）中引入 CSS：
 
 ```typescript
-// main.ts
-import { createApp } from "vue";
-import App from "./App.vue";
-import CesiumGantt from "chbim-time-axis-v2";
-import "chbim-time-axis-v2/dist/style.css"; // 引入样式文件
-
-const app = createApp(App);
-app.use(CesiumGantt);
-app.mount("#app");
-```
-
-之后可以在任意组件中直接使用，无需再次导入：
-
-```vue
-<CesiumGantt :viewer="viewer" v-model:tasks="tasks" />
+import "chbim-time-axis-v2/style.css";
 ```
 
-### 2. 局部注册（推荐）
+### 2. 基本使用
 
-在组件中直接导入使用：
+在 Vue 组件中使用：
 
 ```vue
 <template>
-  <div class="container">
-    <!-- Cesium Viewer 容器 -->
-    <div ref="cesiumContainer" class="cesium-container"></div>
-
-    <!-- 甘特图组件容器 -->
-    <div class="gantt-container">
+  <div class="layout">
+    <div ref="cesiumContainer" class="cesium-view"></div>
+    <div class="gantt-view">
       <CesiumGantt
-        v-if="viewer"
-        :viewer="viewer"
+        v-if="isViewerReady"
+        :viewer="getViewer()"
         v-model:tasks="tasks"
-        @task-enter="handleTaskEnter"
-        @task-leave="handleTaskLeave"
       />
     </div>
   </div>
@@ -72,133 +59,245 @@ app.mount("#app");
 
 <script setup lang="ts">
 import { ref, onMounted, onUnmounted } from "vue";
-import {
-  CesiumGantt,
-  type GanttTask,
-  type GanttGroup,
-} from "chbim-time-axis-v2";
-import "chbim-time-axis-v2/dist/style.css"; // 务必引入样式
+import { CesiumGantt, type GanttTask } from "chbim-time-axis-v2";
 import * as Cesium from "cesium";
 import dayjs from "dayjs";
 
-// Cesium 相关设置
-const cesiumContainer = ref<HTMLElement | null>(null);
-const viewer = ref<Cesium.Viewer | null>(null);
+// 建议将 Cesium 对象挂载到 window 上，避免 Vue 的响应式代理带来的性能开销
+// @ts-ignore
+window.Cesium = Cesium;
+
+const cesiumContainer = ref<HTMLElement>();
+const isViewerReady = ref(false);
+
+const getViewer = () => {
+  // @ts-ignore
+  return window.viewer;
+};
 
-// 任务数据示例
-const tasks = ref<(GanttTask | GanttGroup)[]>([
+const tasks = ref<GanttTask[]>([
   {
     id: "1",
-    name: "示例任务组 1",
-    type: "group",
-    children: [
-      {
-        id: "1-1",
-        name: "任务 1",
-        startTime: dayjs().toISOString(),
-        endTime: dayjs().add(2, "day").toISOString(),
-      },
-    ],
+    name: "基础工程",
+    startTime: dayjs().toISOString(),
+    endTime: dayjs().add(5, "day").toISOString(),
+    type: "task",
   },
 ]);
 
-// 初始化 Cesium
 onMounted(() => {
   if (cesiumContainer.value) {
-    viewer.value = new Cesium.Viewer(cesiumContainer.value, {
-      timeline: true,
-      animation: true,
-      baseLayerPicker: false,
+    // 初始化 Cesium Viewer 并挂载到 window
+    // @ts-ignore
+    window.viewer = new Cesium.Viewer(cesiumContainer.value, {
+      timeline: false, // 建议关闭原生 timeline，使用本组件代替
+      animation: false,
     });
+
+    isViewerReady.value = true;
   }
 });
 
 onUnmounted(() => {
-  if (viewer.value) {
-    viewer.value.destroy();
+  // @ts-ignore
+  if (window.viewer) {
+    // @ts-ignore
+    window.viewer.destroy();
+    // @ts-ignore
+    window.viewer = undefined;
   }
 });
-
-// 事件处理
-const handleTaskEnter = (items: any[]) => {
-  console.log("进入任务时间段:", items);
-};
-
-const handleTaskLeave = (items: any[]) => {
-  console.log("离开任务时间段:", items);
-};
 </script>
 
 <style>
-.container {
+.layout {
   display: flex;
   flex-direction: column;
   height: 100vh;
 }
-.cesium-container {
+.cesium-view {
   flex: 1;
-  width: 100%;
 }
-.gantt-container {
-  height: 300px; /* 根据需要调整高度 */
-  background: #2b2b2b;
+.gantt-view {
+  height: 300px;
 }
 </style>
 ```
 
-## ⚙️ 组件属性 (Props)
-
-| 属性名   | 类型                          | 描述                                                           |
-| :------- | :---------------------------- | :------------------------------------------------------------- |
-| `viewer` | `Cesium.Viewer`               | **必传**。Cesium Viewer 实例，用于时间轴同步。                 |
-| `clock`  | `Cesium.Clock`                | (可选) 如果不使用 viewer.clock，可显式传入 Cesium Clock 实例。 |
-| `tasks`  | `(GanttTask \| GanttGroup)[]` | 任务列表数据。支持 `v-model:tasks` 双向绑定。                  |
-
-## 📡 事件系统 (Events)
+## 📊 数据结构详解
 
-| 事件名         | 载荷 (Payload) | 描述                                                                                      |
-| :------------- | :------------- | :---------------------------------------------------------------------------------------- |
-| `update:tasks` | `tasks[]`      | 当任务被更新（拖拽、编辑）时触发。                                                        |
-| `task-enter`   | `items[]`      | 当时间轴播放**进入**某个任务的时间范围时触发。Payload 包含 `{ task, block?, instant? }`。 |
-| `task-leave`   | `items[]`      | 当时间轴播放**离开**某个任务的时间范围时触发。                                            |
-| `add`          | `parentId`     | 点击组（group）上的新增按钮时触发（如果使用默认插槽）。                                   |
-| `delete`       | `taskId`       | 点击任务上的删除按钮时触发（如果使用默认插槽）。                                          |
+组件的核心是 `tasks` 数组。理解不同的任务类型对于发挥组件潜力至关重要。
 
-## 📊 数据结构
+### 1. 通用接口
 
-### GanttTask 类型定义
+所有任务类型都遵循的基本结构：
 
 ```typescript
 interface GanttTask {
   id: string;
   name: string;
-  startTime: string; // ISO 8601 格式字符串
-  endTime: string; // ISO 8601 格式字符串
-  type?: "task" | "group" | "block" | "instant";
-  children?: GanttTask[]; // 仅 "group" 类型有效
-
-  // 当 type 为 'block' 时使用
-  blocks?: {
-    startTime: string;
-    endTime: string;
-    name: string;
-    color?: string;
-  }[];
-
-  // 当 type 为 'instant' 时使用
-  instants?: {
-    id: string;
-    time: string;
-    name: string;
-    color?: string;
-  }[];
+  startTime: string; // ISO 8601 格式 (e.g., "2023-01-01T09:00:00Z")
+  endTime: string; // ISO 8601 格式
+  type?: "task" | "group" | "block" | "instant"; // 默认为 'task'
+  parentId?: string;
+  warning?: string; // 内部计算的警告信息
+  allowInstant?: boolean; // 是否允许在此任务行上右键添加瞬时点
 }
 ```
 
-## 🧩 插槽 (Slots)
+### 2. 任务组 (Group)
+
+用于组织子任务。时间范围通常由子任务决定，但也可以设置限制范围。
+
+```typescript
+interface GanttGroup extends GanttTask {
+  type: "group";
+  children: GanttTask[]; // 子任务列表
+  collapsed?: boolean; // 是否折叠
+
+  // 如果设置，子任务超出此范围会显示警告
+  limitStartTime?: string;
+  limitEndTime?: string;
+}
+```
+
+### 3. 块状任务 (Block)
+
+适用于同一行展示多个不连续的时间段。
+
+```typescript
+interface TaskBlock {
+  startTime: string;
+  endTime: string;
+  name?: string;
+  color?: string; // 支持 HEX, RGB 等 CSS 颜色值
+}
+
+// 在 GanttTask 中使用
+interface BlockTask extends GanttTask {
+  type: "block";
+  blocks: TaskBlock[]; // 时间块数组
+}
+```
+
+### 4. 瞬时任务 (Instant)
+
+适用于展示时间点事件。
+
+```typescript
+interface TaskInstant {
+  id: string;
+  time: string;
+  name?: string;
+  color?: string;
+}
+
+// 在 GanttTask 中使用
+interface InstantTask extends GanttTask {
+  type: "instant";
+  instants: TaskInstant[]; // 瞬时点数组
+}
+```
+
+## ⚙️ 组件 API
+
+### Props (属性)
+
+| 属性名   | 类型            | 必填 | 默认值 | 描述                                                                       |
+| :------- | :-------------- | :--- | :----- | :------------------------------------------------------------------------- |
+| `tasks`  | `GanttTask[]`   | ✅   | `[]`   | 任务数据源，支持 `v-model:tasks` 双向绑定。                                |
+| `viewer` | `Cesium.Viewer` | ❌   | -      | Cesium Viewer 实例。传入后组件会自动绑定时钟。                             |
+| `clock`  | `Cesium.Clock`  | ❌   | -      | 单独传入 Cesium Clock 实例。如果传入 `viewer`，则优先使用 `viewer.clock`。 |
+
+### Events (事件)
+
+| 事件名         | 参数 (Payload)                        | 描述                                                                           |
+| :------------- | :------------------------------------ | :----------------------------------------------------------------------------- |
+| `update:tasks` | `tasks: GanttTask[]`                  | 当任务数据发生变化（拖拽、调整大小、编辑属性）时触发。                         |
+| `taskUpdate`   | `task: GanttTask`                     | 单个任务发生更新时触发。                                                       |
+| `task-enter`   | `items: { task, block?, instant? }[]` | 当时间轴播放**进入**任务/块/瞬时点的时间范围时触发。这是二三维联动的核心事件。 |
+| `task-leave`   | `items: { task, block?, instant? }[]` | 当时间轴播放**离开**任务/块/瞬时点的时间范围时触发。                           |
+| `add`          | `parentId: string`                    | 点击分组行的 "+" 按钮时触发。                                                  |
+| `delete`       | `taskId: string`                      | 点击删除按钮时触发。                                                           |
+
+### Slots (插槽)
+
+组件提供了丰富的插槽用于自定义 UI。
+
+#### 1. `toolbar` (顶部工具栏)
+
+自定义时间轴上方的控制区域。
+
+```vue
+<template #toolbar="{ togglePlay, isPlaying, handleResetView }">
+  <button @click="togglePlay">{{ isPlaying ? "暂停" : "开始" }}</button>
+  <button @click="handleResetView">重置视角</button>
+  <!-- 添加自定义按钮 -->
+  <button @click="myCustomAction">导出报表</button>
+</template>
+```
+
+#### 2. `taskOp` (任务列表操作列)
+
+自定义任务列表右侧的操作按钮。
+
+```vue
+<template #taskOp="{ item }">
+  <button @click="editTask(item)">编辑</button>
+  <button @click="deleteTask(item.id)" style="color: red">删除</button>
+</template>
+```
+
+#### 3. `barContextMenu` (右键菜单)
+
+自定义在甘特图条上右键点击时出现的菜单。
+
+```vue
+<template #barContextMenu="{ task, block, instant, close }">
+  <div class="my-context-menu">
+    <div class="menu-header">
+      {{ block ? block.name : instant ? instant.name : task.name }}
+    </div>
+    <div
+      @click="
+        viewDetails(task);
+        close();
+      "
+    >
+      查看详情
+    </div>
+    <div
+      @click="
+        deleteItem(task);
+        close();
+      "
+    >
+      删除
+    </div>
+  </div>
+</template>
+```
+
+## 🧩 Cesium 联动机制
+
+组件通过 `Cesium.Clock.onTick` 事件与 Cesium 保持高频同步：
+
+1.  **时间同步**: 甘特图的 `currentTime` 会实时更新为 Cesium 的当前时间。
+2.  **播放控制**: 点击甘特图的播放按钮会控制 `viewer.clock.shouldAnimate`。
+3.  **视口跟随**: 当播放时间超出当前甘特图可视范围时，时间轴会自动滚动以保持当前时间可见。
+
+## ❓ 常见问题
+
+**Q: 如何自定义任务条的颜色？**
+A:
+
+- 对于 `block` 类型，在 `blocks` 数组中指定 `color` 属性。
+- 对于 `instant` 类型，在 `instants` 数组中指定 `color` 属性。
+- 对于普通 `task`，目前默认使用内置颜色（分组为蓝色，普通任务为青色），可通过 CSS 覆盖 `.taskBar` 样式或等待后续版本支持 `color` 字段。
+
+**Q: 添加瞬时点（Instant）的功能在哪里？**
+A: 在设置了 `allowInstant: true` 的任务行（非分组）对应的空白时间轴区域**右键点击**，会弹出内置菜单 "添加瞬时任务"。
+
+## 📄 License
 
-| 插槽名称         | Props 参数                                   | 描述                                 |
-| :--------------- | :------------------------------------------- | :----------------------------------- |
-| `toolbar`        | `{ togglePlay, isPlaying, handleResetView }` | 自定义顶部工具栏区域的内容。         |
-| `taskOp`         | `{ item }`                                   | 自定义任务列表每一行的操作按钮区域。 |
-| `barContextMenu` | `{ task, block, instant, close }`            | 自定义右键点击任务条时的上下文菜单。 |
+MIT