@xpyjs/gantt-core 0.1.0 → 0.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xpyjs/gantt-core",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A powerful and flexible Gantt chart component library for modern web applications with TypeScript support",
   "type": "module",
   "main": "./dist/x-gantt.umd.cjs",

package/types/models/Task.d.ts

@@ -1,7 +1,6 @@
 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;
@@ -56,9 +55,12 @@ export declare class Task {
      */
     flatIndex: number;
     /**
-     * 时间持续间隔
+     * 工时持续时长
+     *
+     * @description 优先取原始 data 中的 duration
+     * @description 若原始数据未提供，则由 endTime - startTime 计算，仅保存在内部，不回填原始数据
      */
-    private duration;
+    private _duration;
     /**
      * 原始数据
      */
@@ -66,12 +68,38 @@ export declare class Task {
     private fields;
     constructor(store: Store, event: EventBus, data: any, parent?: Task, _id?: string);
     getField(field: string): any;
-    /** 切换展示模式时，需要调整时间 */
+    /** 切换展示模式时，需要调整展示长度 */
     updateMode(): boolean;
     updateData(data: any): void;
-    updateTime(startTime: Dayjs, endTime: Dayjs): void;
+    /**
+     * 更新 Task 时间并修改原始 data
+     */
+    updateTime(startTime: Dayjs, endTime: Dayjs, updateDuration?: boolean): void;
+    /**
+     * 更新 Task 持续时间并修改原始 data
+     */
+    updateDuration(startTime: Dayjs, endTime: Dayjs): void;
+    /**
+     * 按照规则，适配任务时间
+     *
+     * 规则：
+     * - 根据 direction 判断移动内容：left - 开始时间，right - 结束时间，both - 起止时间
+     * - 同时缺失 endTime、duration 的话，直接返回
+     * - 根据 duration 重新计算 endTime
+     * - 启用了跳过非工作日模式，自动调整任务时间，使其落在工作日上
+    */
+    fitWork(direction?: "left" | "right" | "both", options?: {
+        start?: Dayjs;
+        end?: Dayjs;
+    }): void;
+    /** 获取当前 duration */
+    get duration(): number;
     clone(): Task;
-    getEmitData(): EmitData;
+    getEmitData(): {
+        data: any;
+        $index: number;
+        level: number;
+    };
     getAllChildren(): Task[];
     isMilestone(): boolean;
     isSummary(): boolean;

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

@@ -40,6 +40,8 @@ export declare class ChartSlider {
     private bindEvents;
     /**
      * 移动后更新任务时间
+     * - 整体移动：锚定 startTime，duration 不变，用 duration 算 endTime
+     * - 单侧移动：锚定另一侧，重新计算 duration
      */
     private emitUpdate;
     private handleDragStart;

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

@@ -1,5 +1,4 @@
 import Konva from "konva";
-import dayjs from "../../utils/time";
 import { IContext } from "@/types/render";
 /**
  * 周末周末渲染
@@ -17,10 +16,6 @@ export declare class WeekendGroup {
     /** 渲染版本号，用于丢弃过期的异步结果 */
     private renderVersion;
     constructor(context: IContext, layer: Konva.Layer);
-    /**
-     * 检查日期是否为周末
-     */
-    isWeekend(date: dayjs.Dayjs): boolean;
     /**
      * 调整周末大小
      */

package/types/store/DataManager.d.ts

@@ -142,6 +142,10 @@ export declare class DataManager {
     toggleAllChecked(checked: boolean): void;
     isTaskChecked(task: Task): boolean;
     updateTaskTime(task: Task, startTime: Dayjs, endTime: Dayjs, direction?: "left" | "right" | "both", oldTasks?: Task[]): void;
+    /**
+     * 基于某个任务进行时间适配的调整，并联动其子任务
+     */
+    fitTaskTime(task: Task, direction: "left" | "right" | "both", oldTasks?: Task[]): void;
     setBaselines(baselines: any[]): void;
     getBaselines(): Baseline[];
     /** 根据ID获取基线 */

package/types/store/index.d.ts

@@ -6,6 +6,7 @@ import { TimeAxis } from "./TimeAxis";
 import { Dayjs } from "dayjs";
 import { IContext } from "@/types/render";
 import { IOptionConfig, IOptions } from "@/types";
+import { WorkCalendar } from "./workCalendar";
 export declare class Store {
     private context;
     private optionManager;
@@ -13,8 +14,10 @@ export declare class Store {
     private columnManager;
     private linkManager;
     private timeAxis;
+    private workCalendar;
     constructor(context: IContext, options?: IOptions);
     getOptionManager(): OptionManager;
+    getWorkCalendar(): WorkCalendar;
     getDataManager(): DataManager;
     getColumnManager(): ColumnManager;
     getLinkManager(): LinkManager;

package/types/store/workCalendar.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 工作日引擎工具。提供周末、节假日的判定函数，以及工作日计算能力
+ */
+import { type Dayjs } from '../utils/time';
+import type { IHolidayOpts, IWeekendOpts, IWorkTimeOpts } from '../types/calendar';
+/**
+ * 工作日历统一管理类
+ *
+ * @description 统一管理所有日期属性。可以判定、计算工作日、节假日、周末等
+ */
+export declare class WorkCalendar {
+    private weekendOpts?;
+    private holidayOpts?;
+    private workTimeOpts?;
+    constructor(weekendOpts?: IWeekendOpts, holidayOpts?: IHolidayOpts, workTimeOpts?: IWorkTimeOpts);
+    update(opts: {
+        weekendOpts?: IWeekendOpts;
+        holidayOpts?: IHolidayOpts;
+        workTimeOpts?: IWorkTimeOpts;
+    }): void;
+    /** 只有显式置条件判定为周末的，才会标记为周末。完整判定需要与其他方法共同完成 */
+    private _isWeekend;
+    /** 只有显式条件判定为节假日的，才会标记为节假日。完整判定需要与其他方法共同完成 */
+    private _isHoliday;
+    /** 只做特殊日期的标记，对于普通未标记的日期返回 undefined。完整判定需要与其他方法共同完成 */
+    private _isWorkTime;
+    /**
+     * 判断日期是否为工作时间
+     *
+     * @description 优先级：isWorkTime 钩子 > 节假日 > 周末
+     */
+    isWorkTime(date: Date | Dayjs): boolean;
+    /**
+     * 判断日期是否为周末
+     *
+     * @description 判定优先级: isWeekend 钩子 > days > 默认 [0, 6]
+     */
+    isWeekend(date: Date | Dayjs): boolean;
+    /**
+     * 判断日期是否为节假日
+     *
+     * @description 判定优先级: isHoliday 钩子 > holidays 列表
+     */
+    isHoliday(date: Date | Dayjs): boolean;
+    /**
+     * 基于一个日期，获取指定时长后的工作日期
+     *
+     * @param start - 起始日期
+     * @param n - 工作日时长（正数向后，负数向前，可为分数）
+     * @returns 目标日期
+     */
+    workOffset(start: Date | Dayjs, n: number): Dayjs;
+    /**
+     * 基于两个日期，计算之间的工作日时长
+     *
+     * @param start - 起始日期
+     * @param end - 结束日期
+     */
+    workDiff(start: Date | Dayjs, end: Date | Dayjs): number;
+    /**
+     * 基于两个日期，计算其中包含的非工作天数
+     */
+    restDays(start: Date | Dayjs, end: Date | Dayjs): number;
+    /**
+     * 基于某个日期获取最近的工作日(默认向后)
+     */
+    currentWorkTime(date: Date | Dayjs, direction?: 'after' | 'before'): Dayjs;
+}

package/types/types/calendar.d.ts

@@ -0,0 +1,97 @@
+import { IPattern } from "./styles";
+
+/**
+ * 周末配置选项
+ */
+export interface IWeekendOpts {
+  /**
+   * 自定义周末日期。默认周六、周日为周末
+   *
+   * @description 0=周日, 1=周一, ..., 6=周六（dayjs.day() 语义）
+   * @default [0, 6]（周六、周日）
+   *
+   * @example
+   * // 周五、周六为周末
+   * days: [5, 6]
+   *
+   * @example
+   * // 没有周末
+   * days: []
+   */
+  days?: number[];
+  /**
+   * 完全自定义周末的判定方法
+   *
+   * @description 优先级最高
+   * @description 返回 true 表示这天是周末。没有被判定的日期可以置空
+   */
+  isWeekend?: (date: Date) => boolean | undefined;
+}
+
+/**
+ * 节假日配置选项
+ */
+export interface IHolidayOpts {
+  /**
+   * 配置节假日期。可以针对不同节假日配置不同的背景颜色。默认使用统一配置颜色
+   */
+  holidays?: Array<
+    {
+      date: Date | number | string | Array<Date | number | string>;
+      backgroundColor?: string;
+      opacity?: number;
+      /**
+       * 自定义节假日期的文本
+       */
+      text?: {
+        /** 是否显示文本 */
+        show?: boolean;
+        /** 文本内容 */
+        content?: string;
+        /** 文本颜色 */
+        color?: string;
+        /** 背景颜色 */
+        backgroundColor?: string;
+        /** 透明度 */
+        opacity?: number;
+        /** 文本字体大小 */
+        fontSize?: number;
+        /** 文本字体 */
+        fontFamily?: string;
+      }
+    } & IPattern
+  >;
+  /**
+   * 完全自定义节假日的判定方法
+   *
+   * @description 优先级高于 holidays 列表
+   * @description 返回 true 表示这天是节假日。没有被判定的日期可以置空
+   */
+  isHoliday?: (date: Date) => boolean | undefined;
+}
+
+/**
+ * 工时引擎配置选项
+ */
+export interface IWorkTimeOpts {
+  /**
+   * 计算日期周期时，是否跳过周末
+   * @default false
+   * @description 当置为 true 时，任务周期会自动跳过周末。此时可能 duration 时长与 startTime - endTime 长度不一致
+   */
+  skipWeekends?: boolean;
+  /**
+   * 计算日期周期时，是否跳过节假日
+   * @default false
+   * @description 当置为 true 时，任务周期会自动跳过节假日。此时可能 duration 时长与 startTime - endTime 长度不一致
+   */
+  skipHolidays?: boolean;
+
+  /**
+   * 完全自定义工作日的判定方法
+   *
+   * @description 优先级高于节假日和周末。如果将某个日期判定为工作日，那么它不会再被 holiday 与 weekend 捕获。
+   * @returns 返回 true 表示这天是工作日。没有被判定的日期可以置空
+   */
+  isWorkTime?: (date: Date) => boolean | undefined;
+}

package/types/types/options.d.ts

@@ -3,6 +3,7 @@ import { IChartOptions } from "./chart";
 import { ILink } from "./link";
 import { IPattern } from "./styles";
 import { ITableOptions } from "./table";
+import { IHolidayOpts, IWeekendOpts, IWorkTimeOpts } from "./calendar";
 
 export type XGanttUnit = "hour" | "day" | "week" | "month" | "quarter";
 export type TaskType = "task" | "milestone" | "summary";
@@ -106,6 +107,21 @@ export interface IGanttOptions {
     /** 结束时间字段 */
     endTime: string;
 
+    /**
+     * 持续时间字段。
+     *
+     * @description 该字段不适用于 `day（不含）` 以下单位，仅针对单位为 `day` 及以上的情况有效
+     * @description 与 endTime 字段互斥，endTime 优先级更高
+     * @description 当 workTime.enabled = false 时，duration 按日历日解释
+     * @description 当 workTime.enabled = true 时，duration 按工作日解释
+     *
+     * @example
+     * // 只有 duration 没有 endTime
+     * { id: 1, start: '2024-01-05', duration: 5 }
+     * // endTime 自动计算为 2024-01-10（5个日历日）
+     */
+    duration?: string;
+
     /** 名称字段 */
     name: string;
 
@@ -980,7 +996,7 @@ export interface IGanttOptions {
      * @default 0.1
      */
     opacity: number;
-  } & IPattern;
+  } & IPattern & IWeekendOpts;
 
   /** 节假日期配置 */
   holiday: {
@@ -992,42 +1008,20 @@ export interface IGanttOptions {
      * 背景颜色。默认使用主色
      */
     backgroundColor?: string;
+
     /**
      * 透明度
      *
      * @default 0.1
      */
     opacity: number;
-    /**
-     * 配置节假日期。可以针对不同节假日配置不同的背景颜色。默认使用统一配置颜色
-     */
-    holidays?: Array<
-      {
-        date: Date | number | string | Array<Date | number | string>;
-        backgroundColor?: string;
-        opacity?: number;
-        /**
-         * 自定义节假日期的文本
-         */
-        text?: {
-          /** 是否显示文本 */
-          show?: boolean;
-          /** 文本内容 */
-          content?: string;
-          /** 文本颜色 */
-          color?: string;
-          /** 背景颜色 */
-          backgroundColor?: string;
-          /** 透明度 */
-          opacity?: number;
-          /** 文本字体大小 */
-          fontSize?: number;
-          /** 文本字体 */
-          fontFamily?: string;
-        }
-      } & IPattern
-    >;
-  } & IPattern;
+
+  } & IPattern & IHolidayOpts;
+
+  /**
+   * 配置工作日模式。启用后可以将任务范围控制在工作日内
+   */
+  workTime?: IWorkTimeOpts;
 
   /** 标志配置。它用于配置一个或多个标志性日期 */
   flag?: {
@@ -1129,4 +1123,4 @@ export interface IGanttOptions {
      */
     animationDuration?: number;
   };
-}
+};