@canvas-components/gantt-table 0.1.1 → 0.1.2

package/README.md

@@ -2,4 +2,187 @@
 
 纯原生 Canvas 甘特图核心，目录组织参考 `@canvas-components/list-table`：配置位于 `schema`，布局与日期计算位于 `domain`，绘制位于 `rendering`，命中测试位于 `interaction`。
 
-首版支持时间轴、任务条、进度、依赖线、滚动、任务选中及拖拽平移日期。React 接入位于独立的 `@canvas-components/react-gantt-table` 适配包中。
+首版支持时间轴、任务条、进度、依赖线、横纵滚动、固定时间表头与任务列、任务选中、拖拽平移日期和任务条宽度调整。开启 `editable` 后，可在未排期任务行中拖拽添加任务条，移动或缩放已有任务条，并用 Delete/Backspace 删除选中任务条（清除 `start` / `end`，保留任务行）。选中任务后还可以从左右连接锚点拖到另一任务条，新建或修改依赖；依赖线可独立选中并用 Delete/Backspace 删除。通过 `snapToColumn` 可让移动与缩放吸附到最小日维度，拖拽结果始终限制在时间轴范围内；开启 `rowDraggable` 后可在固定任务列中拖拽调整行顺序，相邻行会以动画让出目标位置，并通过 `onTaskReorder` 返回新顺序。`weekendBackground` 可控制是否显示周末底色，颜色可通过 `theme.weekendBackgroundColor` 调整。滚动位置会根据内容和视口尺寸自动约束，也可以通过实例的 `scrollTo(left, top)` 方法定位。React 接入位于独立的 `@canvas-components/react-gantt-table` 适配包中。
+
+## React 配置示例
+
+```tsx
+import { useState } from "react";
+import { ReactGanttTable } from "@canvas-components/react-gantt-table";
+import type { GanttTask } from "@canvas-components/gantt-table";
+
+const taskContent = {
+  render: (task: GanttTask) => `${task.title} · ${task.progress ?? 0}%`,
+  style: { color: "#ffffff", fontWeight: 600, textAlign: "center" },
+} satisfies Pick<GanttTask, "render" | "style">;
+
+export function ProjectPlan() {
+  const [tasks, setTasks] = useState<GanttTask[]>([
+    {
+      id: "research",
+      title: "需求调研",
+      start: "2026-09-01",
+      end: "2026-09-04",
+      progress: 100,
+      ...taskContent,
+    },
+    {
+      id: "design",
+      title: "交互设计",
+      start: "2026-09-04",
+      end: "2026-09-09",
+      progress: 60,
+      ...taskContent,
+    },
+  ]);
+  const [dependencies, setDependencies] = useState([
+    { from: "research", to: "design", type: "finish-to-start" as const },
+  ]);
+
+  return (
+    <ReactGanttTable
+      tasks={tasks}
+      dependencies={dependencies}
+      startDate="2026-08-31"
+      endDate="2026-10-01"
+      scale="day"
+      taskColumnWidth={180}
+      editable
+      taskColumnResizable
+      taskResizable
+      snapToColumn
+      rowDraggable
+      weekendBackground
+      theme={{ weekendBackgroundColor: "#fafafa" }}
+      onTaskChange={(changedTask) => {
+        setTasks((current) =>
+          current.map((task) =>
+            task.id === changedTask.id ? { ...changedTask } : task,
+          ),
+        );
+      }}
+      onTaskReorder={(reorderedTasks) => {
+        setTasks(reorderedTasks.map((task) => ({ ...task })));
+      }}
+      onDependenciesChange={(nextDependencies) => {
+        setDependencies(nextDependencies.map((item) => ({ ...item })));
+      }}
+      style={{ height: 360 }}
+    />
+  );
+}
+```
+
+## 原生配置示例
+
+```ts
+import { Gantt } from "@canvas-components/gantt-table";
+
+const tasksWithContent = tasks.map((task) => ({
+  ...task,
+  render: (currentTask) =>
+    `${currentTask.title} · ${currentTask.progress ?? 0}%`,
+  style: { color: "#ffffff", fontWeight: 600, textAlign: "center" },
+}));
+
+const gantt = new Gantt(container, {
+  tasks: tasksWithContent,
+  dependencies,
+  startDate: "2026-08-31",
+  endDate: "2026-10-01",
+  scale: "week",
+  editable: true,
+  taskColumnResizable: true,
+  taskResizable: true,
+  snapToColumn: true,
+  rowDraggable: true,
+  weekendBackground: true,
+  onTaskChange: (task) => console.log(task),
+  onTaskReorder: (nextTasks) => console.log(nextTasks),
+  onDependenciesChange: (nextDependencies) => console.log(nextDependencies),
+});
+
+gantt.mount();
+gantt.scrollTo(320, 0);
+// gantt.destroy();
+```
+
+## 常用配置
+
+| 配置                                        | 说明                                 | 默认值        |
+| ------------------------------------------- | ------------------------------------ | ------------- |
+| `scale`                                     | 时间轴维度：`day`、`week`、`month`   | `day`         |
+| `headerLevels`                              | 时间轴多层表头配置                   | 当前 `scale`  |
+| `headerHeight`                              | 每层表头的默认高度                   | `56`          |
+| `editable`                                  | 开启任务条新增、移动、缩放与键盘删除 | `false`       |
+| `taskResizable`                             | 编辑模式下允许移动及拖拽两端调整日期 | `true`        |
+| `snapToColumn`                              | 鼠标释放后吸附到最小日维度           | `false`       |
+| `rowDraggable`                              | 在固定任务列中拖拽改变任务顺序       | `false`       |
+| `multiTask`                                 | 开启一行多个任务条模式               | `false`       |
+| `taskColumnResizable`                       | 允许拖拽改变固定任务列宽度           | `true`        |
+| `taskColumnMinWidth` / `taskColumnMaxWidth` | 固定任务列宽度限制                   | `120` / `480` |
+| `weekendBackground`                         | 是否显示周末底色                     | `true`        |
+| `theme.weekendBackgroundColor`              | 周末背景颜色                         | `#fafafa`     |
+| `GanttTask.render`                          | 自定义当前任务条内部内容             | -             |
+| `GanttTask.style`                           | 当前任务条内部文字样式               | -             |
+| `onTaskChange`                              | 任务条新增、移动、缩放或删除完成回调 | -             |
+| `onTaskReorder`                             | 行拖拽排序完成回调                   | -             |
+| `onDependenciesChange`                      | 依赖连线新增、修改或删除回调         | -             |
+
+任务可通过 `color` 单独设置未完成区域颜色，通过 `progressColor` 设置已完成区域颜色，`progress` 接受 `0` 到 `100` 的进度百分比。未配置任务级颜色时，分别回退到 `theme.taskColor` 与 `theme.taskProgressColor`。
+
+每个任务可通过同级的 `render(task, rowIndex)` 与 `style` 分别配置内部内容和文字样式。`render` 返回字符串、数字或空值；`style` 支持 `color`、`fontSize`、`fontWeight`、`fontFamily` 和 `textAlign`。内容会裁剪在任务条的圆角范围内，空间不足时自动显示省略号。
+
+默认每个顶层 `GanttTask` 对应一行和一个任务条。开启 `multiTask` 后，顶层任务作为行定义，固定列显示其 `title`，并通过 `tasks` 配置同一行内的多个任务条：
+
+```tsx
+<ReactGanttTable
+  multiTask
+  tasks={[
+    {
+      id: "development-row",
+      title: "核心开发",
+      tasks: [
+        {
+          id: "api",
+          title: "接口开发",
+          start: "2026-09-09",
+          end: "2026-09-13",
+        },
+        {
+          id: "ui",
+          title: "界面开发",
+          start: "2026-09-13",
+          end: "2026-09-17",
+        },
+      ],
+    },
+  ]}
+/>
+```
+
+多任务模式下，选择、移动、缩放、删除、`onTaskChange` 和依赖连线均以行内任务为单位；固定列拖拽仍以顶层行为单位。若需要在空白区域拖拽创建任务条，可在行内预先提供未设置 `start` / `end` 的任务。
+
+通过 `headerLevels` 可由上至下配置多层时间表头。支持 `year`、`quarter`、`month`、`week` 和 `day`，每层可单独设置 `height` 或通过 `formatter(start, end)` 自定义文案。未配置时保持当前 `scale` 对应的单层表头：
+
+```tsx
+<ReactGanttTable
+  headerHeight={36}
+  headerLevels={[
+    { unit: "month", height: 42 },
+    { unit: "week" },
+    {
+      unit: "day",
+      formatter: (start) => String(start.getDate()),
+    },
+  ]}
+/>
+```
+
+左侧任务列表头会自动纵向合并并覆盖全部时间表头层级；横向滚动时，各层表头与时间网格保持同步固定。
+
+任务的 `start` 和 `end` 可省略，用于展示尚未排期的空白行。编辑模式下在该行时间轴区域按住并水平拖拽即可创建任务条；选中后按 Delete 或 Backspace 会再次清除这两个字段。请在 `onTaskChange` 中同步受控数据。
+
+依赖关系的 `type` 支持 `finish-to-start`、`start-to-start`、`finish-to-finish`，默认使用 `finish-to-start`。每条依赖可以通过 `color` 单独设置连线颜色；未配置时回退到 `theme.milestoneColor`。
+
+编辑模式下先选中任务，任务条两侧会显示连接锚点。拖动左锚点到另一任务的开始端会创建 `start-to-start`；拖动右锚点到目标开始端会创建 `finish-to-start`，拖到目标完成端会创建 `finish-to-finish`。同一对任务重复连接时会更新原连线类型并保留其自定义颜色。