jordium-gantt-vue3/dist/utils/calendarTimeUtils.d.ts

A Vue 3 Gantt chart component for project management, task scheduling, resource planning, calendar, resource usage and timeline visualization.

import { WorkingHoursConfig } from '../models/types/CalendarTypes';
/** 一天的毫秒数 */
export declare const DAY_MS: number;
/**
 * 判断某天是否为周末（周六=6，周日=0）
 */
export declare function isWeekendDay(dayOfWeek: number): boolean;
/**
 * 判断两个日期是否为同一天
 */
export declare function isSameDay(a: Date, b: Date): boolean;
export declare function isToday(date: Date): boolean;
/**
 * 解析任务 startDate/endDate 字符串为 Date 对象，正确处理"仅日期"格式（如 "2025-04-15"）。
 *
 * 修复：`new Date("2025-04-15")` 这类不带时间部分的 ISO 8601 日期字符串，会被 JS 引擎按
 * **UTC 零点**解析（规范行为），在东八区等非 UTC 时区下会被转换成本地时间 08:00 而非
 * 00:00，导致 `classifyTaskForDate` 里的"整点判断"（`start.getHours()===0`）失真，把本应
 * 全天展示的任务误判为"从 08:00 开始的具体时段"（表现为日历日/周视图里全天任务被错误地
 * 画进小时网格，标题显示为 "08:00 ~ 24:00"）。
 * 而 `"2025-04-15 00:00"`（空格分隔，带时间部分）等格式本身就会被解析为本地时间，不受
 * 此问题影响，无需特殊处理，直接走 `new Date(value)` 即可。
 */
export declare function parseTaskDateTime(value?: string): Date | null;
/**
 * 计算某个时间点距当日零点的分钟数（用于"当前时间指示线"定位）
 */
export declare function minutesSinceMidnight(date: Date): number;
/**
 * 判断一段任务起止时间是否覆盖到指定日期（按天粒度比较，忽略起止时间的具体时分秒）。
 * 修复此前 `start <= date && end >= date` 直接比较 Date 对象的缺陷：
 * 当任务起止带有具体时分（如 08:00）时，与当日 00:00 的 date 参数比较会恒为 false，
 * 导致月视图等按天渲染的场景遗漏当天有明确起止小时的任务。
 */
export declare function isTaskOnDate(start: Date, end: Date, date: Date): boolean;
/**
 * 判断指定小时是否为工作时间
 * @param hour 0-23 小时数
 * @param dayOfWeek 0-6，0=周日
 * @param workingHours 工作时间配置，不传则视为全部非工作时间
 */
export declare function isWorkingHour(hour: number, dayOfWeek: number, workingHours?: WorkingHoursConfig): boolean;
/** 日历日视图使用的小时单元数据 */
export interface CalendarHourCell {
    hour: number;
    label: string;
    date: Date;
    isWorkingHour: boolean;
    isCurrentHour: boolean;
}
/**
 * 生成指定日期的 24 小时单元数据（供日视图/周视图复用）
 */
export declare function generateDayHours(date: Date, workingHours?: WorkingHoursConfig): CalendarHourCell[];
/**
 * 获取指定日期所在周的周一（周起始日）
 */
export declare function getWeekStart(date: Date): Date;
/** 日历周视图使用的一天数据 */
export interface CalendarWeekDayCell {
    date: Date;
    dayOfWeek: number;
    isWeekend: boolean;
    isToday: boolean;
    hours: CalendarHourCell[];
}
/**
 * 生成指定日期所在周的 7 天数据（周一到周日）
 */
export declare function generateWeekDays(anchorDate: Date, workingHours?: WorkingHoursConfig): CalendarWeekDayCell[];
/** 日历月视图使用的一天格子数据 */
export interface CalendarMonthDayCell {
    date: Date;
    /** 是否属于当前展示月份（false 表示为补齐网格的上月/下月弱化日期） */
    isCurrentMonth: boolean;
    isWeekend: boolean;
    isToday: boolean;
}
/**
 * 生成传统日历方格所需的月视图网格（含首尾补齐的相邻月日期）
 * 固定周一为一周首日，网格行数随自然月天数浮动（5~6 行）
 */
export declare function generateMonthGrid(anchorDate: Date): CalendarMonthDayCell[][];
/**
 * 将日期按指定分钟粒度吸附（向下取整），用于拖拽选区的最小刻度吸附
 */
export declare function snapToMinuteStep(date: Date, minuteStep: number): Date;
/**
 * 将日期吸附到当天 00:00（用于月视图的天粒度选区）
 */
export declare function snapToDayStart(date: Date): Date;
/**
 * 将 Date 格式化为 Task.startDate/endDate 使用的字符串格式（YYYY-MM-DD HH:mm），
 * 与 GanttChart.vue 中 handleCalendarSelectionComplete 的 formatForDrawer 保持一致（v1.13.0）
 */
export declare function formatTaskDateTime(date: Date): string;
/**
 * 将时间格式化为 HH:mm（用于任务卡片时间段展示）
 */
export declare function formatHourMinute(date: Date): string;
/**
 * 格式化任务时间段文案，如 "08:30 ~ 09:30"（v1.13.0 任务卡片标题追加时间信息）
 */
export declare function formatTaskTimeRange(start: Date, end: Date): string;
/**
 * 生成日历任务卡片标题：全天任务展示 "任务名 - 全天"，有具体起止时间的任务展示
 * "任务名 - HH:mm ~ HH:mm"（v1.13.0）
 */
export declare function formatTaskCardTitle(taskName: string, isAllDay: boolean, start: Date, end: Date, allDayLabel?: string): string;
/** 任务在指定日期（date）上的展示分类结果，供日/周视图统一判定全天/具体时段 */
export interface TaskDateClassification {
    /** 'all-day' 展示为全天条目；'timed' 按分钟区间绘制具体时段；'none' 与该日期无关，不展示 */
    type: 'all-day' | 'timed' | 'none';
    /** type === 'timed' 时有效：当日区间起点（距当日零点的分钟数） */
    startMinutes?: number;
    /** type === 'timed' 时有效：当日区间止点（距当日零点的分钟数）；跨天任务在起始日的止点固定为 1440（当日24:00） */
    endMinutes?: number;
}
/**
 * 判断任务在指定日期（date）应如何展示。仅依据 startDate/endDate 的日期与时间部分判断，
 * 不依赖 estimatedHours（预计工时仅用于资源利用率占比计算，与日历展示位置无关）。
 *
 * 规则：
 * 1. 起止日期为同一天：起止时间均为 00:00 -> 全天；否则按实际起止时间绘制具体时段。
 * 2. 起止日期不同（跨天任务），按 date 与起止日期的关系分别处理：
 *    a. date 等于起始日期：起始时间为 00:00 -> 全天；否则从起始时间 ~ 当日24:00 绘制。
 *    b. date 等于结束日期：结束时间为 00:00 -> 全天；否则从当日00:00 ~ 结束时间绘制。
 *    c. date 严格介于起止日期之间（不含两端）-> 全天。
 * 与 date 无任何交集 -> 'none'。
 */
export declare function classifyTaskForDate(start: Date, end: Date, date: Date): TaskDateClassification;
/** 将"距当日零点分钟数"格式化为 HH:mm；跨天任务当日片段的终点 1440 分钟格式化为 24:00 */
export declare function formatMinutesLabel(minutes: number): string;
/**
 * 依据"距当日零点分钟数"区间生成任务卡片标题："标题 - HH:mm ~ HH:mm"。
 * 用于跨天任务：传入的是当日片段区间（如起始日的 "09:30 ~ 24:00"），而非任务整体起止时间。
 */
export declare function formatTaskCardTitleByMinutes(taskName: string, startMinutes: number, endMinutes: number): string;
/** Outlook 风格拖拽选区的分段渲染数据：每个半小时（或指定粒度）槽位一组 slot(底色)/indicator(精确覆盖比例) 矩形 */
export interface SelectionSegmentRect {
    /** 槽位（如半小时格）在网格中的像素顶部偏移 */
    slotTop: number;
    /** 槽位整体像素高度 */
    slotHeight: number;
    /** 实际选区与该槽位重叠部分的像素顶部偏移 */
    indicatorTop: number;
    /** 实际选区与该槽位重叠部分的像素高度（未占满槽位时小于 slotHeight，对应"不满30分钟"的比例呈现） */
    indicatorHeight: number;
}
/**
 * 按固定粒度（默认 30 分钟）将一段选区拆分为多个槽位，每个槽位返回：
 * - 槽位自身的完整像素区间（用于渲染整槽浅色背景）
 * - 选区与该槽位的实际重叠像素区间（用于渲染左侧深色比例指示条）
 * 供 CalendarDayView/CalendarWeekView 的拖拽选区高亮使用，实现类似 Outlook 的
 * "半小时格淡蓝底 + 左侧比例指示条" 视觉效果。
 */
export declare function computeSelectionSegments(startMinutesRaw: number, endMinutesRaw: number, hourHeight: number, slotMinutes?: number): SelectionSegmentRect[];
/** 一段以"距当日零点分钟数"表示的时间区间 */
export interface MinuteRange {
    start: number;
    end: number;
}
/**
 * 计算指定星期几的工作时间区间（分钟粒度，供全天任务的"工作时间高亮"渲染使用）。
 * 周末或未配置 workingHours 时返回空数组。
 */
export declare function getWorkingHourMinuteRanges(dayOfWeek: number, workingHours?: WorkingHoursConfig): MinuteRange[];
/** 时间轴任务的列布局结果：column 为 0 基列序号，columnCount 为其所属重叠簇的总列数 */
export interface TimedTaskLayout {
    column: number;
    columnCount: number;
}
/**
 * 经典的"日历事件重叠布局"算法（Google Calendar/Outlook 日视图同款思路）：
 * 按开始时间排序后，尽量复用已结束的列，无法复用时新增列；当某个重叠簇处理完毕
 * （下一个事件的开始时间不早于当前簇内所有事件的最大结束时间）时，回填该簇内所有
 * 事件的 columnCount，使同一簇内的事件按列等宽并排显示。
 */
export declare function computeTimedTaskLayout(intervals: MinuteRange[]): TimedTaskLayout[];