@xpyjs/gantt-core 0.0.1-alpha.2 → 0.0.1-alpha.4

package/types/XGantt.d.ts

@@ -0,0 +1,248 @@
+import { IOptionConfig, IOptions } from "./types";
+import { EventMap } from "./types/event";
+/**
+ * XGantt 甘特图组件的主要接口
+ *
+ * @description 这是 XGantt 甘特图组件的核心接口，提供了创建、配置、渲染和管理甘特图的所有功能。
+ * XGantt 是一个功能强大的甘特图组件，支持任务管理、时间轴显示、关联线、进度跟踪等功能。
+ *
+ * @example
+ * ```typescript
+ * // 基本使用
+ * const gantt = new XGantt('#container', {
+ *   data: [
+ *     {
+ *       id: 1,
+ *       name: '任务1',
+ *       startTime: '2023-01-01',
+ *       endTime: '2023-01-10',
+ *       progress: 50
+ *     }
+ *   ]
+ * });
+ *
+ * // 监听事件
+ * gantt.on('select', (data, checked, all) => {
+ *   console.log('选择了任务:', data);
+ * });
+ *
+ * // 更新配置
+ * gantt.update({
+ *   unit: 'week',
+ *   primaryColor: '#007acc'
+ * });
+ *
+ * // 跳转到指定日期
+ * gantt.jumpTo('2023-06-01');
+ *
+ * // 销毁组件
+ * gantt.destroy();
+ * ```
+ */
+export declare class XGantt {
+    private context;
+    private events;
+    constructor(element: string | HTMLElement, options?: IOptions);
+    /**
+     * 更新 XGantt 的配置选项
+     *
+     * @param options - 新的配置选项，支持部分更新
+     * @param config - 配置更新参数的方式
+     *
+     * @description 此方法允许在运行时动态更新甘特图的配置。
+     * 只需要传入需要更改的配置项，其他配置项将保持不变。
+     * 更新后会自动重新渲染相关部分以反映新的配置。
+     *
+     * @example
+     * ```typescript
+     * // 更新数据源。数据会被完全替换，除非原数据的 key 一致
+     * gantt.update({
+     *   data: newTaskData
+     * });
+     *
+     * // 更新显示单位
+     * gantt.update({
+     *   unit: 'month'
+     * });
+     *
+     * // 更新主题色
+     * gantt.update({
+     *   primaryColor: '#ff6b6b'
+     * });
+     *
+     * // 批量更新多个配置
+     * gantt.update({
+     *   unit: 'week',
+     *   primaryColor: '#4ecdc4',
+     *   dateFormat: 'YYYY-MM-DD',
+     *   row: {
+     *     height: 40
+     *   }
+     * });
+     *
+     * // 完全替换配置（不合并）
+     * gantt.update(newOptions, { merge: false });
+     * ```
+     *
+     */
+    update(options: IOptions, config?: IOptionConfig): void;
+    /**
+     * 渲染甘特图视图
+     *
+     * @description 此方法通常不需要主动调用，初始化以及 `update` 中都会自动更新。 如果你需要强制刷新页面，可以在合适的时候调用此方法
+     */
+    render(): void;
+    /**
+     * 销毁甘特图实例，清理所有资源
+     *
+     * @description 完全销毁甘特图实例并清理所有相关资源，包括：
+     * - 移除所有事件监听器
+     * - 清理 DOM 元素和事件绑定
+     * - 释放内存中的数据引用
+     * - 停止所有动画和定时器
+     * - 清理渲染上下文
+     *
+     * 调用此方法后，甘特图实例将不再可用，需要重新创建新实例。
+     * 这对于防止内存泄漏和确保组件的正确生命周期管理非常重要。
+     *
+     * @example
+     * ```typescript
+     * const gantt = new XGantt('#container', options);
+     * gantt.render();
+     *
+     * // 在组件卸载或页面离开时销毁
+     * gantt.destroy();
+     *
+     * // React 组件中的使用示例
+     * useEffect(() => {
+     *   const gantt = new XGantt('#gantt-container', options);
+     *   gantt.render();
+     *
+     *   return () => {
+     *     gantt.destroy(); // 组件卸载时清理
+     *   };
+     * }, []);
+     * ```
+     *
+     * @warning 销毁后的实例不能再次使用，调用任何方法都可能导致错误
+     */
+    destroy(): void;
+    /**
+     * 跳转到指定日期
+     *
+     * @param date - 要跳转到的日期，支持多种格式：
+     *   - Date 对象
+     *   - ISO 日期字符串 (如 '2023-06-01')
+     *   - 时间戳数字
+     *   - 其他可被 Date 构造函数解析的格式
+     *   - 如果不传入参数或传入 undefined，则跳转到今天
+     *
+     * @returns 是否成功跳转到指定日期
+     *   - `true`: 成功跳转，视图已更新到指定日期
+     *   - `false`: 跳转失败，可能是日期无效或超出数据范围
+     *
+     * @description 此方法将甘特图的视图定位到指定日期，使该日期在当前视窗中可见。
+     * 具体行为取决于当前的显示单位和视图范围：
+     * - 如果指定日期在当前视图范围内，视图会滚动到该日期
+     * - 如果指定日期超出当前数据范围，可能会扩展时间轴或返回 false
+     * - 跳转会触发相应的滚动动画（如果启用）
+     *
+     * @example
+     * ```typescript
+     * // 跳转到今天（默认行为）
+     * const success1 = gantt.jumpTo();
+     * const success2 = gantt.jumpTo(undefined);
+     *
+     * // 跳转到指定日期
+     * const success3 = gantt.jumpTo('2023-06-01');
+     * const success4 = gantt.jumpTo(new Date('2023-06-01'));
+     * const success5 = gantt.jumpTo(1685577600000); // 时间戳
+     *
+     * // 检查跳转结果
+     * if (gantt.jumpTo('2023-12-25')) {
+     *   console.log('成功跳转到圣诞节');
+     * } else {
+     *   console.log('跳转失败，日期可能超出范围');
+     * }
+     *
+     * // 跳转到项目开始日期
+     * const projectStartDate = data[0]?.startTime;
+     * if (projectStartDate) {
+     *   gantt.jumpTo(projectStartDate);
+     * }
+     * ```
+     */
+    jumpTo(date?: any): boolean;
+    /**
+     * 注册事件监听器
+     *
+     * @template K - 事件名称的类型
+     * @param event - 要监听的事件名称
+     * @param cb - 事件回调函数
+     *
+     * @description 为甘特图注册事件监听器，支持监听各种用户交互和状态变化事件。
+     * 同一个事件注册多个，只会执行最后一个监听器。
+     *
+     * 支持的事件类型包括：
+     * - `loaded`: 加载完成事件，组件初始化完成后触发
+     * - `error`: 错误事件，当组件发生错误时触发
+     * - `update:link`: 关联线更新事件
+     * - `create:link`: 关联线创建事件
+     * - `select:link`: 关联线选择事件
+     * - `select`: 任务选择事件
+     * - `click:row`: 行点击事件
+     * - `dblclick:row`: 行双击事件
+     * - `contextmenu:row`: 行右键菜单事件
+     * - `click:slider`: 任务条点击事件
+     * - `dblclick:slider`: 任务条双击事件
+     * - `contextmenu:slider`: 任务条右键菜单事件
+     * - `move`: 任务移动事件
+     *
+     * @example
+     * ```typescript
+     * // 监听任务选择事件
+     * gantt.on('select', (selectedData, isChecked, allSelectedData) => {
+     *   console.log('选择状态:', isChecked);
+     *   console.log('当前选择的数据:', selectedData);
+     *   console.log('所有选择的数据:', allSelectedData);
+     * });
+     *
+     * // 监听行点击事件
+     * gantt.on('click:row', (event, rowData) => {
+     *   console.log('点击了行:', rowData.name);
+     *   console.log('鼠标事件:', event);
+     * });
+     *
+     * // 监听任务条双击事件
+     * gantt.on('dblclick:slider', (event, taskData) => {
+     *   console.log('双击了任务条:', taskData.name);
+     *   // 可以打开任务详情弹窗
+     *   openTaskDetailModal(taskData);
+     * });
+     *
+     * // 监听任务移动事件
+     * gantt.on('move', (moveData) => {
+     *   moveData.forEach(item => {
+     *     console.log(`任务 ${item.row.name} 从 ${item.old.startTime} 移动到 ${item.row.startTime}`);
+     *   });
+     * });
+     *
+     * // 监听关联线创建事件
+     * gantt.on('create:link', (link) => {
+     *   console.log('创建了新的关联线:', link);
+     *   // 可以保存到后端
+     *   saveLinkToServer(link);
+     * });
+     *
+     * // 监听错误事件
+     * gantt.on('error', (error) => {
+     *   console.error('甘特图发生错误:', error);
+     *   // 可以上报错误或显示用户友好的错误信息
+     *   showErrorNotification(error.message);
+     * });
+     * ```
+     *
+     * @see {@link EventMap} 查看所有可用事件及其参数类型
+     */
+    on<K extends keyof EventMap>(event: K, cb: EventMap[K]): void;
+}

package/types/event/index.d.ts

@@ -0,0 +1,75 @@
+export declare class EventBus {
+    private events;
+    /**
+     * 注册事件监听器
+     * @param event 事件名称
+     * @param callback 回调函数
+     */
+    on(event: EventName, callback: Function): void;
+    /**
+     * 触发事件
+     * @param event 事件名称
+     * @param args 参数列表
+     */
+    emit(event: string, ...args: any[]): void;
+    /**
+     * 移除特定事件的特定监听器
+     * @param event 事件名称
+     * @param callback 要移除的回调函数
+     */
+    off(event: string, callback: Function): void;
+    /**
+     * 移除所有事件监听器
+     */
+    offAll(): void;
+}
+export declare enum EventName {
+    LOADED = "loaded",
+    COLUMN_WIDTH_CHANGE = "column-width-change",
+    MOVE_GUIDELINE = "move-guideline",
+    SHOW_GUIDELINE = "show-guideline",
+    HIDE_GUIDELINE = "hide-guideline",
+    TOGGLE_COLLAPSE = "toggle-collapse",
+    SCROLL = "scroll",
+    CHART_OFFSET_CHANGE = "chart_offset_change",
+    DATA_UPDATE = "data-update",
+    VIEW_UPDATE = "view-update",
+    UPDATE_TABLE_HEADER = "update_table_header",
+    UPDATE_TABLE_BODY = "update_table_body",
+    UPDATE_CHART_HEADER = "update_chart_header",
+    UPDATE_TASK = "update_task",
+    UPDATE_LINK = "update_link",
+    CREATE_LINK = "create_link",
+    TASK_SELECTED = "task_selected",
+    TASK_UNSELECTED = "task_unselected",
+    SELECT_LINK = "select_link",
+    CHECK_TASK = "check_task",
+    CONTEXT_LINK = "context_link",
+    ROW_CLICK = "row-click",
+    ROW_DBL_CLICK = "row-dbl-click",
+    ROW_CONTEXTMENU = "row-contextmenu",
+    SLIDER_CLICK = "slider-click",
+    SLIDER_DBL_CLICK = "slider-dbl-click",
+    SLIDER_CONTEXTMENU = "slider-contextmenu",
+    SLIDER_MOVING = "slider-moving",
+    SLIDER_HOVER = "slider-hover",
+    SLIDER_LEAVE = "slider-leave",
+    ROW_HIGHLIGHT = "row-highlight",
+    ROW_UNHIGHLIGHT = "row-unhighlight",
+    TASK_DRAG_START = "task-drag-start",
+    TASK_DRAG_MOVE = "task-drag-move",
+    TASK_DRAG_END = "task-drag-end",
+    BASELINE_CLICK = "baseline-click",
+    BASELINE_CONTEXTMENU = "baseline-contextmenu",
+    BASELINE_MOUSEOVER = "baseline-mouseover",
+    BASELINE_MOUSEOUT = "baseline-mouseout",
+    ERROR = "error"
+}
+export declare enum ErrorType {
+    /** 连线不被允许 */
+    LINK_NOT_ALLOWED = "LINK_NOT_ALLOWED",
+    /** 相同节点 */
+    LINK_SAME = "LINK_SAME",
+    /** 当前关联已存在 */
+    LINK_EXIST = "LINK_EXIST"
+}

package/types/index.d.ts

@@ -0,0 +1,13 @@
+import "./styles/main.scss";
+export { XGantt } from "./XGantt";
+export { generateId } from "./utils/id";
+export { default as dayjs } from "./utils/time";
+export type { Dayjs } from "./utils/time";
+export { colorjs, type Colorjs } from "./utils/color";
+export declare const version: string;
+import type { IOptions, IOptionConfig, EmitData } from "./types";
+import type { EventMap } from "./types/event";
+import type { ILink } from "./types/link";
+import type { ErrorType } from "./event";
+import type { XGanttUnit } from "./types/options";
+export type { IOptions, IOptionConfig, EmitData, EventMap, ILink, ErrorType, XGanttUnit };

package/types/logo.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: string;
+export declare function printLogo(): void;

package/types/models/Baseline.d.ts

@@ -0,0 +1,37 @@
+import type { Dayjs } from "dayjs";
+import { Store } from "@/store";
+import { type EventBus } from "../event";
+import { BaselineDiff } from "../types/baseline";
+/**
+ * 基线数据模型
+ */
+export declare class Baseline {
+    private store;
+    private event;
+    /** 基线ID */
+    id: string;
+    /** 任务ID */
+    taskId: string;
+    /** 开始时间 */
+    startTime?: Dayjs;
+    /** 结束时间 */
+    endTime?: Dayjs;
+    /** 基线名称 */
+    name?: string;
+    /** 原始数据 */
+    data: any;
+    /** 是否高亮 */
+    highlight: boolean;
+    /** 是否为指示器对比基线 */
+    target: boolean;
+    constructor(store: Store, event: EventBus, data: any);
+    getField(field: string): any;
+    /**
+     * 验证基线的有效性
+     */
+    validate(): boolean;
+    /**
+     * 获取基线与任务的时间差异分析
+     */
+    getTimeDiff(): BaselineDiff | null;
+}

package/types/models/Task.d.ts

@@ -0,0 +1,77 @@
+import type { Dayjs } from "dayjs";
+import { type EventBus } from "../event";
+import { TaskType } from "../types/options";
+import { EmitData } from "@/types";
+import { Store } from "@/store";
+export declare class Task {
+    private store;
+    private event;
+    __key__: string;
+    /**
+     * 任务ID
+     * 如果没有提供，则会自动生成一个唯一ID
+     */
+    id: string;
+    /**
+     * 任务名称
+     */
+    name: string;
+    /**
+     * 任务开始时间
+     * 如果没有提供，则默认为 undefined
+     */
+    startTime?: Dayjs;
+    /**
+     * 任务结束时间
+     * 如果没有提供，则默认为 undefined
+     */
+    endTime?: Dayjs;
+    /**
+     * 任务进度
+     */
+    progress?: number;
+    /** 任务类型 */
+    type: TaskType;
+    /**
+     * 是否展开
+     * 如果没有提供，则默认为 true
+     */
+    expanded?: boolean;
+    /**
+     * 子任务列表
+     * 如果没有子任务，则默认为空数组
+     */
+    children: Task[];
+    /**
+     * 父任务
+     * 如果没有父任务，则默认为 undefined
+     */
+    parent?: Task;
+    /**
+     * 任务层级，从0开始
+     */
+    level: number;
+    /**
+     * 在扁平化列表中的索引位置，从0开始
+     */
+    flatIndex: number;
+    /**
+     * 时间持续间隔
+     */
+    private duration;
+    /**
+     * 原始数据
+     */
+    data: any;
+    private fields;
+    constructor(store: Store, event: EventBus, data: any, parent?: Task, _id?: string);
+    getField(field: string): any;
+    /** 切换展示模式时，需要调整时间 */
+    updateMode(): void;
+    updateData(data: any): void;
+    updateTime(startTime: Dayjs, endTime: Dayjs): void;
+    clone(): Task;
+    getEmitData(): EmitData;
+    getAllChildren(): Task[];
+    isMilestone(): boolean;
+}

package/types/rendering/RenderScheduler.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 渲染任务类型
+ */
+export interface RenderTask {
+    type: string;
+    refresh?: boolean;
+    callback: (...args: any[]) => void;
+    args?: any[];
+    immediate?: boolean;
+}
+/**
+ * 任务处理器配置
+ */
+export interface TaskHandler {
+    callback: (...args: any[]) => void;
+    immediate?: boolean;
+}
+/**
+ * 渲染调度器
+ * 用于收集和调度不同类型的渲染任务，避免短时间内重复执行
+ */
+export declare class RenderScheduler {
+    private taskQueue;
+    private taskHandlers;
+    private isScheduled;
+    private delay;
+    private debouncedFlush;
+    constructor(delay?: number);
+    /**
+     * 注册任务处理器
+     * @param taskType 任务类型
+     * @param handler 处理器配置
+     */
+    registerHandler(taskType: string, handler: TaskHandler): void;
+    /**
+     * 注册任务处理器（简化版本，只传回调函数）
+     * @param taskType 任务类型
+     * @param callback 回调函数
+     * @param immediate 是否总是立即执行
+     */
+    registerSimpleHandler(taskType: string, callback: (...args: any[]) => void, immediate?: boolean): void;
+    /**
+     * 调度任务执行
+     * @param taskType 任务类型
+     * @param args 传递给处理器的参数
+     * @param options 任务选项
+     */
+    scheduleTask(taskType: string, args?: any[], options?: {
+        refresh?: boolean;
+        immediate?: boolean;
+    }): void;
+    /**
+     * 立即执行指定类型的任务（跳过队列）
+     * @param taskType 任务类型
+     * @param args 传递给处理器的参数
+     * @param refresh 是否强制刷新
+     */
+    immediateExecuteTask(taskType: string, args?: any[], refresh?: boolean): void;
+    /**
+     * 立即执行所有队列中的任务
+     */
+    immediateFlushAll(): void;
+    /**
+     * 执行单个任务
+     * @param task 任务对象
+     */
+    private executeTask;
+    /**
+     * 清空并执行任务队列
+     */
+    private flushTaskQueue;
+    /**
+     * 取消已调度的任务执行
+     */
+    cancelScheduled(): void;
+    /**
+     * 移除指定类型的任务处理器
+     * @param taskType 任务类型
+     */
+    unregisterHandler(taskType: string): void;
+    /**
+     * 获取当前队列中的任务数量
+     */
+    getQueueSize(): number;
+    /**
+     * 获取已注册的处理器类型列表
+     */
+    getRegisteredHandlers(): string[];
+    /**
+     * 销毁调度器
+     */
+    destroy(): void;
+}

package/types/rendering/Renderer.d.ts

@@ -0,0 +1,52 @@
+import { Scrollbar } from "./scrollbar";
+import { IContext } from "@/types/render";
+export declare class Renderer {
+    private context;
+    private container;
+    private scrollbar;
+    private rootElement;
+    private tableContainer;
+    private chartContainer;
+    private table;
+    private chart;
+    private middleLine;
+    private renderScheduler;
+    private _id;
+    private width;
+    private height;
+    private isInitialized;
+    getScrollbar(): Scrollbar;
+    constructor(context: IContext, // 渲染器上下文
+    container: HTMLElement);
+    /**
+     * 设置任务处理器
+     */
+    private setupTaskHandlers;
+    /**
+     * 设置事件监听器
+     */
+    private setupEventListeners;
+    /**
+     * 实际执行渲染的方法
+     * @param refresh 是否强制刷新
+     */
+    private performRender;
+    /**
+     * 公共渲染方法，向后兼容
+     * @param refresh 是否强制刷新
+     */
+    render(refresh?: boolean): void;
+    /**
+     * 立即执行渲染，不经过调度器
+     * @param refresh 是否强制刷新
+     */
+    immediateRender(refresh?: boolean): void;
+    private updateSize;
+    /**
+     * 设置样式值
+     */
+    private setStyleValue;
+    private handleUpdateTask;
+    private handleColumnWidthChange;
+    destroy(): void;
+}

package/types/rendering/chart/ChartBaseline.d.ts

@@ -0,0 +1,50 @@
+import Konva from "konva";
+import { Task } from "../../models/Task";
+import { IContext } from "@/types/render";
+export declare class ChartBaseline {
+    private context;
+    private stage;
+    private layer;
+    private tasks;
+    private chartBaselineGroup;
+    private indicatorGroup;
+    private baselineGroup;
+    private width;
+    private height;
+    private offsetX;
+    private offsetY;
+    constructor(context: IContext, stage: Konva.Stage, layer: Konva.Layer);
+    /**
+     * 注册事件
+     */
+    private registerEvents;
+    /**
+     * 调整基线大小
+     */
+    resize(width: number, height: number): void;
+    /**
+     * 设置偏移量 (响应滚动)
+     */
+    setOffset(x: number, y: number): void;
+    /**
+     * 更新数据
+     */
+    update(): void;
+    /**
+     * 渲染基线
+     */
+    render(tasks: Task[]): void;
+    /**
+     * 销毁关联线
+     */
+    destroy(): void;
+    /**
+     * 计算并渲染基线
+     */
+    private calculateBaselines;
+    private renderBaselineBar;
+    private renderText;
+    private renderCompareHighlight;
+    private renderCompareIndicator;
+    private bindEvents;
+}