PlusGantt（普加甘特图）V3.0 中文 API 文档

PlusGantt（普加甘特图）V3.0 中文 API 文档

官方网站：http://www.plusgantt.com
文档版本：V3.0
控件类型：纯 JavaScript Web 甘特图控件，兼容 IE6+ 及现代浏览器
最后整理时间：2026年1月14日

目录

一、初始化方式

<div id="gantt1" style="width:100%; height:500px;"></div>
<script src="scripts/plusgantt.js"></script>
<script>
  var gantt = new PlusGantt();
  gantt.render(document.getElementById("gantt1"));
</script>

⚠️ 注意：不能直接对属性赋值，必须通过 setter 方法操作。

二、属性（Properties）

属性名 类型 说明 示例
readOnly Boolean 是否只读（禁止编辑） gantt.readOnly → true/false
visible Boolean 是否可见 gantt.visible
style String 样式字符串 \"width:100%;height:400px\"
width Number 宽度（像素） gantt.width
height Number 高度（像素） gantt.height
showTableView Boolean 是否显示左侧任务表格 默认 true
showGanttView Boolean 是否显示右侧甘特条形图 默认 true
showLinkLines Boolean 是否显示任务依赖连线（箭头） 默认 true
showCritical Boolean 是否显示关键路径（红色条） 默认 true
showGridLines Boolean 是否显示时间刻度背景线 默认 true
timeLines Array 自定义时间线（竖线标注） 见下方示例
rowHeight Number 行高（像素） 默认 24
allowDragDrop Boolean 是否允许拖拽任务行 默认 true
multiSelect Boolean 是否允许多选任务 默认 false
allowResize Boolean 是否允许拖拽调整甘特图区域大小 默认 true

✅ timeLines 示例：

gantt.setTimeLines([
  { date: new Date(2026, 0, 15), text: "项目中期评审" },
  { date: new Date(2026, 1, 1), text: "春节", style: "background:red;color:white;" }
]);

三、核心方法（Methods）

1. 初始化与渲染

方法 参数 说明
render(domElement) DOM 元素 将甘特图渲染到指定容器
setStyle(styleString) 字符串 设置整体样式（如宽高） 
gantt.setStyle("width:100%;height:600px");
gantt.render(document.getElementById("ganttBox"));

2. 数据加载与获取

方法 返回值 说明
loadTasks(tasks) void 加载树形任务数据（JSON）
getTaskTree() Array 获取当前任务树（含 children）
getTaskList() Array 获取扁平任务列表（含 ParentTaskUID）
getRemovedTasks() Array 获取已被删除的任务
acceptChanges() void 提交变更，清空“已删除/新增”标记 
// 加载数据
gantt.loadTasks([
  {
    UID: "1",
    Name: "项目启动",
    Start: "2026-01-10T00:00:00",
    Finish: "2026-01-15T23:59:59",
    Duration: 5,
    PercentComplete: 100,
    Summary: 1,
    children: [
      { UID: "2", Name: "需求调研", Start: "2026-01-10T00:00:00", Finish: "2026-01-12T23:59:59", Duration: 3, PercentComplete: 100 }
    ]
  }
]);

3. 任务操作（增删改查）

方法 参数 说明
getTask(uid) UID 根据 UID 获取任务对象
findTasks(field, value) 字段名, 值 查找符合条件的任务数组
addTask(task, [index/action], [parentTask]) 任务对象, 位置/动作, 父任务 新增任务
removeTask(task) 任务对象 删除任务
updateTask(task, prop, value) 或 updateTask(task, {key: val}) 任务, 属性名+值 / 对象 更新任务属性
moveTask(task, target, action) 任务, 目标任务, "before"/"after"/"add" 移动任务位置
upgradeTask(task) 任务 升级（提升层级）
downgradeTask(task) 任务 降级（降低层级） 
// 更新任务进度
var task = gantt.getTask("2");
gantt.updateTask(task, "PercentComplete", 50);

// 或批量更新
gantt.updateTask(task, { PercentComplete: 50, Name: "需求调研（进行中）" });

4. 选中与遍历

方法 说明
getSelected() 获取单个选中任务
getSelecteds() 获取多个选中任务（数组）
isSelected(task) 判断是否选中
select(task) / deselect(task) 选中/取消选中
selectAll() / deselectAll() 全选/取消全选
getParentTask(task) 获取父任务
getChildTasks(task) 获取直接子任务
getAllChildTasks(task) 获取所有后代任务
getAncestorTasks(task) 获取所有祖先任务
isAncestor(parent, child) 判断是否为祖先关系
eachChild(task, fn) 遍历直接子任务
cascadeChild(task, fn) 递归遍历所有子任务
bubbleParent(task, fn) 向上遍历父任务链

5. 视图控制

方法 说明
setShowTableView(bool) 显示/隐藏左侧表格
setShowGanttView(bool) 显示/隐藏右侧甘特图
setTableViewWidth(num) 设置表格宽度（像素）
setGanttViewWidth(num) 设置甘特图区域宽度
setTopTimeScale(scale) 设置顶层时间刻度（"year"/"month"/"week"/"day"/"hour"）
setBottomTimeScale(scale) 设置底层时间刻度（需比顶层更细）
zoomIn() / zoomOut() 放大/缩小时间刻度
scrollIntoView(task) 滚动到指定任务位置
collapse(task) / expand(task) 折叠/展开任务
collapseAll() / expandAll() 全部折叠/展开
collapseLevel(n) / expandLevel(n) 折叠/展开到第 n 层 
gantt.setTopTimeScale("month");
gantt.setBottomTimeScale("day");
gantt.zoomIn(); // 放大到小时级别（若底层为 hour）

四、事件（Events）

通过 on(eventName, handler) 监听事件。

1. 单元格与条形图绘制

事件名 事件对象结构 触发时机
drawcell { source, record, column, field, value, cellHtml } 绘制表格单元格时
drawitem { source, item, itemBox, itemHtml } 绘制甘特条形图时

✅ 自定义单元格示例：

gantt.on("drawcell", function(e) {
  if (e.field === "Name" && e.record.Duration > 10) {
    e.cellHtml = '<b style="color:red;">' + e.value + '</b>';
  }
});

✅ 自定义条形图示例：

gantt.on("drawitem", function(e) {
  if (!e.item.Summary && !e.item.Milestone) {
    var w = e.itemBox.width * (e.item.PercentComplete / 100);
    e.itemHtml = `<div class="my-bar" style="left:${e.itemBox.left}px; width:${e.itemBox.width}px;">
                    <div class="progress" style="width:${w}px;"></div>
                  </div>`;
  }
});

2. 用户交互事件

事件名 事件对象 说明
taskclick { source, task } 单击任务
taskdblclick { source, task } 双击任务
taskdragdrop { source, tasks, targetTask, action, cancel } 拖拽任务后释放
cellbeginedit { source, record, column, field, value, cancel } 单元格开始编辑
CellCommitEdit { source, record, column, field, value, cancel } 单元格提交编辑
itemdragstart { source, item, action, cancel } 条形图开始拖拽（action: "move", "start", "finish", "percentcomplete"）
itemdragcomplete { source, item, action, value } 条形图拖拽完成（value 为新日期或数值）

✅ 禁止摘要任务编辑：

gantt.on("cellbeginedit", function(e) {
  if (e.record.Summary === 1) {
    e.cancel = true; // 取消编辑
  }
});

✅ 监听进度拖拽：

gantt.on("itemdragcomplete", function(e) {
  if (e.action === "percentcomplete") {
    console.log("新进度:", e.value); // 0～100 的数字
  }
});

五、任务数据结构

每个任务对象必须包含以下字段：

字段 类型 必填 说明
UID String ✅ 唯一标识（不可重复）
Name String ✅ 任务名称
Start Date/String ✅ 开始时间（ISO 8601 格式，如 "2026-01-10T00:00:00"）
Finish Date/String ✅ 结束时间
Duration Number ✅ 工期（单位由时间刻度决定）
PercentComplete Number (0～100) ✅ 完成百分比
Summary 0/1 ❌ 是否为摘要任务（1=是）
Critical 0/1 ❌ 是否关键任务（1=红色显示）
Milestone 0/1 ❌ 是否里程碑（1=显示菱形）
PredecessorLink Array ❌ 前置任务依赖，格式：[{ PredecessorUID: "2", Type: 1 }]
children Array ❌ 子任务（树形结构）
ParentTaskUID String ❌ 父任务 UID（列表结构用）

依赖类型 Type：

  • 0 = FF（完成-完成）
  • 1 = FS（完成-开始）← 最常用
  • 2 = SF（开始-完成）
  • 3 = SS（开始-开始）

六、集成第三方框架（如 ExtJS）

var extPanel = Ext.get("myExtPanel");
gantt.setStyle("width:100%;height:100%");
gantt.render(extPanel.dom); // 渲染到 ExtJS 容器

七、语言本地化

只需引入对应语言包：

<!-- 英文 -->
<script src="scripts/miniui/locale/en_US.js"></script>

<!-- 中文（默认）无需额外引入 -->

八、完整最小示例

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>PlusGantt 示例</title>
  <script src="scripts/plusgantt.js"></script>
</head>
<body>
  <div id="gantt1" style="width:100%; height:500px;"></div>
  <script>
    var gantt = new PlusGantt();
    gantt.render(document.getElementById("gantt1"));

    gantt.loadTasks([{
      UID: "1",
      Name: "开发阶段",
      Start: "2026-01-10T00:00:00",
      Finish: "2026-01-20T23:59:59",
      Duration: 10,
      PercentComplete: 30,
      Summary: 1,
      children: [{
        UID: "2",
        Name: "前端开发",
        Start: "2026-01-10T00:00:00",
        Finish: "2026-01-15T23:59:59",
        Duration: 5,
        PercentComplete: 100,
        Summary: 0
      }]
    }]);

    // 双击编辑
    gantt.on("taskdblclick", function(e) {
      alert("双击任务: " + e.task.Name);
    });
  </script>
</body>
</html>

九、官方资源

posted @ 2026-01-14 10:44  氢夏  阅读(63)  评论(0)    收藏  举报