Frappe Gantt “今日线”实现机制深度解析

作者: Jim Wang 公众号: 巴博萨船长

摘要：本文深入分析 Frappe Gantt 官方代码中“今日线（Today Line）”的实现逻辑。通过追踪函数调用路径，揭示了一个关键细节：只有当“今天”位于任务时间范围内时，今日线才会被绘制。
这一机制虽然符合设计意图，却常常让开发者误以为“高亮功能无效”。本文将详细剖析源码结构、绘制逻辑及判断条件，并给出相应的改进建议。

Abstract: This article analyzes how Frappe Gantt internally implements the “Today Line” feature that highlights the current date on a Gantt chart. By tracing its function call stack, we discover that the library only renders the line when “today” falls within the visible task date range. This design decision explains why many users fail to see the today line when their task set does not include the current date. The article also discusses how to override this limitation and force-render the today line beyond the defined task range.

作者: Jim Wang 公众号: 巴博萨船长

背景介绍

Frappe Gantt 是一个轻量级、可交互的甘特图（Gantt Chart）库，支持任务依赖、假期标识、视图切换、滚动定位等功能。在新版中，官方加入了“今日高亮（Today Highlight）”机制，用于在图表上标示当前日期位置。

然而，很多开发者在实际使用时发现：

设置了 scroll_to: 'today' 后可以滚动到今天，但并没有看到明显的“今日线”。

这并非渲染问题，而是源自于 官方实现中的逻辑判断。

源码分析：从 change_view_mode() 到 highlight_current()

在 frappe-gantt.umd.js 中，渲染主流程大致如下：

change_view_mode()
 └── render()
      └── make_grid_extras()
           └── make_grid_highlights()
                └── highlight_current()

整个“今日线”的绘制核心在 highlight_current() 函数中。

核心函数 highlight_current()

反编译源码后，逻辑大致如下（加入注释说明）：

highlight_current() {
    // 获取最接近今天的日期和其对应的日期标签
    const [date, labelEl] = this.get_closest_date();
    if (!date || !labelEl) return;

    // 💡关键判断：
    // 如果今天早于任务最早开始时间或晚于任务最晚结束时间，则直接返回
    if (this.gantt_start > date || this.gantt_end < date) return;

    // 为当前日期标签添加高亮样式
    labelEl.classList.add("current-date-highlight");

    // 计算今天相对 Gantt 开始时间的偏移量
    const diff = (date - this.gantt_start) / this.config.step;
    const x = diff * this.config.column_width;

    // 创建纵向红色高亮条
    this.create_el({
        left: x,
        top: this.config.header_height,
        height: this.grid_height - this.config.header_height,
        classes: "current-highlight",
        append_to: this.$container
    });

    // 创建顶部红点标记
    this.create_el({
        left: x - 2.5,
        top: this.config.header_height - 6,
        width: 6,
        height: 6,
        classes: "current-ball-highlight",
        append_to: this.$header
    });
}

“今日线”不显示的根本原因

核心在这行逻辑：

if (this.gantt_start > date || this.gantt_end < date) return;

换句话说：

• 如果今天在所有任务最早开始日期 之前；
• 或者在所有任务最晚结束日期 之后；
• 那么 Frappe Gantt 不会绘制 今日线。

例子：

tasks = [
  { start: '2024-06-01', end: '2024-06-15' },
  { start: '2024-06-10', end: '2024-06-25' },
];

若今天是 2025-10-09，此时：

gantt_start = 2024-06-01
gantt_end   = 2024-06-25
today       = 2025-10-09

因为今天超出了任务范围，highlight_current() 在执行时立即返回，不再绘制红线。

官方设计意图

这并非 Bug，而是一个设计选择（Design Decision）。
Frappe 团队的假设是：

“今日线”仅在任务时间范围内才有意义。
若今天完全超出任务时间轴，绘制高亮线反而会引起误导。

这符合“任务导向”的可视化理念——Gantt 图强调项目时间线，而非日历线性时间。

实测验证：手动调用与覆盖逻辑

在开发者控制台中执行：

gantt.highlight_current();

即可立即触发绘制逻辑。
如果当日超出任务范围，调用后依然无任何效果，原因正是上述条件。

扩展实现：强制显示“今日线”

如果你希望无论任务范围如何，都能显示今日线，可以在渲染后追加自定义逻辑：

setTimeout(() => {
  const today = new Date();
  const start = gantt.start;
  const end = gantt.end;
  const totalDays = (end - start) / (1000 * 60 * 60 * 24);
  const dayWidth = gantt.options.column_width;
  const daysSinceStart = (today - start) / (1000 * 60 * 60 * 24);
  const x = daysSinceStart * dayWidth;

  const line = document.createElement("div");
  line.style.position = "absolute";
  line.style.left = `${x}px`;
  line.style.top = `${gantt.options.header_height || 40}px`;
  line.style.height = `${gantt.$svg.getBBox().height}px`;
  line.style.width = "2px";
  line.style.background = "red";
  line.style.zIndex = 10;

  gantt.$container.appendChild(line);
}, 300);

这样就能在任何情况下“强制显示”今日线，适用于跨季度或项目暂停的情景。

视觉样式补充

Frappe 默认定义了以下三个 CSS 类：

.current-highlight {
  position: absolute;
  background-color: rgba(255,0,0,0.15);
  pointer-events: none;
  z-index: 1;
}

.current-ball-highlight {
  position: absolute;
  background-color: red;
  border-radius: 50%;
  z-index: 2;
}

.current-date-highlight {
  color: red;
  font-weight: bold;
}

如果你发现红线颜色太浅，可在自定义样式中覆盖透明度或层级。

结论

项目	说明
绘制函数	highlight_current()
调用路径	render() → make_grid_highlights() → highlight_current()
不显示原因	今天不在 gantt_start 与 gantt_end 范围内
设计意图	避免在任务范围外绘制无意义线条
修复方法	手动绘制今日线或重载判断逻辑

从设计哲学上看，这种约束符合“数据驱动视图”的理念； 但从用户体验上说，开发者往往期望看到“今天”在整个时间轴上的位置，哪怕超出任务范围。个人浅见，不足之处，望请指正。