Frappé Gantt 时间轴对齐问题的分析与解决方案

问题背景

Frappé Gantt 是一款基于 JavaScript 的开源甘特图库，广泛应用于项目管理可视化领域。近期在使用过程中发现了一个关键性的显示问题：在周视图(Week)和月视图(Month)模式下，时间刻度(timescale)与任务时间线(timeline)会出现不对齐的情况，而日视图(Day)则表现正常。

问题现象

该问题表现为：

1. 当任务时间跨度较大时，时间刻度与任务条的位置会出现明显偏移
2. 偏移程度与任务时间跨度成正比，但存在特定年份(如2020)时偏移会突然消失的异常现象
3. 在月视图下滚动到最左侧时，时间刻度会停止响应而任务时间线继续移动

技术分析

经过深入代码分析，发现问题根源在于时间计算逻辑的不一致性：

1. 月份计算缺陷：原代码在处理跨月/跨年任务时，使用简单的日期差值计算，未考虑不同月份的实际天数差异
2. 视图渲染逻辑：月视图模式下，时间刻度和任务条使用不同的定位计算方式，导致两者步调不一致
3. 动态渲染问题：新版引入的动态月份显示机制与静态渲染的旧版相比，在边界条件下容易出现同步问题

解决方案

针对上述问题，我们实施了以下改进措施：

1. 统一时间计算基准

在bar.js的compute_x()方法中，采用"30天伪月份"作为统一计算基准：

if (this.gantt.view_is('Month')) {
    const diffDaysBasedOn30DayMonths = date_utils.diff(task_start, gantt_start, 'month') * 30;
    const dayInMonth = Math.min(29, date_utils.format(task_start, "DD"));
    const diff = diffDaysBasedOn30DayMonths + dayInMonth;
    x = (diff * column_width) / 30;
}

2. 改进日期差值计算

重构date_utils.diff()方法，正确处理跨年跨月的日期计算：

// 计算年份差异
const yearDiff = date_a.getFullYear() - date_b.getFullYear();
const monthDiff = date_a.getMonth() - date_b.getMonth();

// 处理月份边界条件
months = yearDiff * 12 + monthDiff;
if (date_a.getDate() < date_b.getDate()) {
    months--;
}

3. 简化网格刻度计算

在make_grid_ticks()方法中，移除了复杂的月份天数计算，统一使用列宽作为基准：

tick_x += this.options.column_width;

实现效果

经过上述改进后：

1. 各种视图模式下时间刻度与任务条保持完美对齐
2. 跨年/跨月任务显示准确无误
3. 滚动操作响应一致，无滞后或不同步现象

技术启示

1. 时间处理一致性：在可视化组件中，时间计算必须保持严格的一致性，任何微小的差异都会在渲染时被放大
2. 边界条件测试：时间相关功能必须测试各种边界条件，特别是跨年、跨月、闰年等特殊情况
3. 性能与精度平衡：在保证显示精度的前提下，适当采用简化计算模型(如30天月份)可以提高性能

该解决方案已在Frappé Gantt项目中得到验证和应用，有效解决了长期存在的时间轴对齐问题，为项目的稳定性和可靠性提供了重要保障。