工具提示可以在不让屏幕充满过多文本的情况下,显示额外的信息。默认情况下,工具提示会显示在 Gantt 任务上。
你可以通过相应的 API 为任意 Gantt 元素添加工具提示。
要为任务启用工具提示,只需通过 gantt.plugins 方法开启 tooltip 插件:
<script>
gantt.plugins({ tooltip: true });
gantt.init("gantt_here");
</script>
当该扩展被激活后,工具提示会以默认设置自动显示。
默认情况下,工具提示会显示任务的三个属性:
如果你想自定义工具提示文本,可以像这样使用 tooltip_text 模板:
gantt.templates.tooltip_text = (start, end, task) =>
`<b>Task:</b> ${task.text}<br/><b>Duration:</b> ${task.duration}`;
工具提示对象可以通过 gantt.ext.tooltips.tooltip 访问。它提供了用于控制工具提示位置、内容和可见性的方法:
有几种方法可以帮助你在悬停 DOM 元素时控制工具提示的行为。
添加带有扩展配置的工具提示。该方法接受一个包含以下设置的对象:
为特定 Gantt 元素添加工具提示。该方法比 attach() 更简单。它接受一个包含工具提示详细信息的对象:
移除工具提示。参数如下:
默认情况下,工具提示只会添加到 Gantt 任务上,但你也可以将其应用到其他 Gantt 元素,例如资源标记:
这里可以用到 tooltip API 的两个方法:
例如,为时间轴刻度单元格添加工具提示:
const domHelper = gantt.utils.dom;
const pos = domHelper.getRelativeEventPosition(event, gantt.$task_scale);
return gantt.templates.task_date(gantt.dateFromPos(pos.x));
请注意,要在 Gantt 初始化后调用 gantt.ext.tooltips.tooltipFor()。比如可以放在 onGanttReady 事件处理函数中:
gantt.attachEvent("onGanttReady", () => {
const tooltips = gantt.ext.tooltips;
tooltips.tooltipFor({
selector: ".gantt_task_link",
html: (event, node) => {
// ...
}
});
gantt.init("gantt_here");
});
Related sample: Custom Tooltips
或如下方式:
gantt.init("gantt_here");
gantt.parse(tasks);
gantt.ext.tooltips.tooltipFor({
selector: ".gantt_task_cell",
html: (event, domElement) => {
const id = event.target.parentNode.getAttribute("task_id");
const task = gantt.getTask(id);
return task.text;
}
});
Related sample: Gantt. Custom tooltips for cells
通过这种方式添加的工具提示会跟随鼠标指针,并遵循 tooltip_offset_x, tooltip_offset_y, tooltip_timeout, tooltip_hide_timeout 等相关设置。
该方法允许你通过更详细的配置来添加工具提示,从而更好地控制鼠标移动时的行为。
你可以通过移除内置处理器并添加自定义处理器来更改默认的工具提示行为:
// 移除任务的内置工具提示处理器
gantt.ext.tooltips.detach(`[${gantt.config.task_attribute}]:not(.gantt_task_row)`);
gantt.ext.tooltips.tooltipFor({
selector: `.gantt_grid [${gantt.config.task_attribute}]`,
html: (event: MouseEvent) => {
if (gantt.config.touch && !gantt.config.touch_tooltip) {
return;
}
const targetTaskId = gantt.locate(event);
if (gantt.isTaskExists(targetTaskId)) {
const task = gantt.getTask(targetTaskId);
return gantt.templates.tooltip_text(task.start_date, task.end_date, task);
}
return null;
},
global: false
});
显示和隐藏工具提示的时间可以通过相关设置进行调整。
要设置任务工具提示出现前的延时时间(毫秒),请使用 tooltip_timeout:
gantt.config.tooltip_timeout = 50;
gantt.init("gantt_here");
要控制鼠标移开后工具提示保持可见的时间(毫秒),请使用 tooltip_hide_timeout:
gantt.config.tooltip_hide_timeout = 5000;
gantt.init("gantt_here");
你可以通过以下配置属性调整工具提示的位置偏移:
gantt.config.tooltip_offset_x = 30;
gantt.config.tooltip_offset_y = 40;
gantt.init("gantt_here");
6.1 之前,工具提示只会在时间轴区域内显示。从 v6.1 起,工具提示可以出现在任意位置并跟随鼠标指针。
如果你想恢复之前的行为,可以在初始化 Gantt 前使用如下代码:
gantt.attachEvent("onGanttReady", () => {
const tooltips = gantt.ext.tooltips;
tooltips.tooltip.setViewport(gantt.$task_data);
});
gantt.init("gantt_here");
gantt.parse(demo_tasks);
Back to top