GoJS图表组件介绍

本文是对 GoJS 官方文档Introduction to GoJS Diagramming Components一节的翻译。

GoJS 图表组件介绍

GoJS 是一个能让你轻易地在现在浏览器中创建可交互式图表的 JavaScript 库。GoJS 支持图表模板和绑定模型数据到图表对象属性。无论你的 app 需要什么样的属性，你只需要保存和恢复模型（由 JavaScript 简单对象组成）即可。许多预定义的工具和命令实现了大部分图表需要的标准行为。定制外观和行为通常主要是设置属性而已。

一个简单的 GoJS 图表

// 更多相关概念 参考 "Building Parts" 介绍页
var $ = go.GraphObject.make;

// 节点模板描述每个节点应该如何构造
diagram.nodeTemplate = $(
  go.Node,
  'Auto', // 形状自适应文本块
  $(
    go.Shape,
    'RoundedRectangle', // 形状类别
    // 绑定 Shape.fill 到 Node.data.color
    new go.Binding('fill', 'color')
  ),
  $(
    go.TextBlock,
    { margin: 3 }, // 围绕文本的空间
    // 绑定 TextBlock.text 到 Node.data.key
    new go.Binding('text', 'key')
  )
);

// 模型仅保持图表需要的必要的信息
diagram.model = new go.GraphLinksModel(
  [
    // JS对象数组, 一项一个节点;
    // the "color" property is added specifically for this app
    { key: 'Alpha', color: 'lightblue' },
    { key: 'Beta', color: 'orange' },
    { key: 'Gamma', color: 'lightgreen' },
    { key: 'Delta', color: 'pink' },
  ],
  [
    // JS对象数组, 一项一个连线
    { from: 'Alpha', to: 'Beta' },
    { from: 'Alpha', to: 'Gamma' },
    { from: 'Beta', to: 'Beta' },
    { from: 'Gamma', to: 'Delta' },
    { from: 'Delta', to: 'Alpha' },
  ]
);

// 启动 Ctrl-Z 撤消 和 Ctrl-Y 重做
diagram.undoManager.isEnabled = true;

GoJS 概念

图表(Diagrams)由部件(Parts)组成：可以由连线(Links)连接的节点(Nodes)和能将连线和节点分组的组(Groups)，所有这些部件集中在层(Layer)上，并由布局(Layouts)和路由(Routers)来组织排列。

每一个图表有一个模型，用来保存和解释应用的数据（节点到节点的连接关系，组-成员的关系）。许多部件是数据绑定到你的应用数据。图表自动为模型的 Model.nodeDataArray 的每一个数据项创建节点和组，为模型的 GraphLinksModel.linkDataArray 的每一个数据项创建连线。你可以添加任何你需要的属性到每一个数据项对象上，仅有少量属性是每类模型要求的。

每个节点和连线通常是由模板来定义，这个模板定义了节点和连线的外观和行为。每个模板由 GraphObject 对象的面板(Panel)组成，例如：文本块(TextBlock)和形状(Shape)。所有部件都有默认的模板，但几乎所有的应用都需要自定义模板来达到期望的外观和行为。GraphObject 属性到数据模型属性的数据绑定使节点和连线针对数据惟一。

节点可以被手动放置（交互方式或编程方式），或者由 Diagram.layout 和每个 Group.layout 自动排列。节点即会由他们的左上角的点(GraphObject.position)也会由程序员给节点定义的 Spot(Part.location 和 Part.locationSpot)定位。

工具处理鼠标和键盘事件。每个图表有许多工具执行交互任务，例如：选择、拖动、在两个节点间连线。ToolManager 决定哪一个工具应该运行，取决于鼠标事件和当前情形。

每个图表有一个 CommandHandler 实现了各种命令，如：删除、拷贝。当 ToolManager 运行时，CommandHanlder 处理键盘事件，如：ctrl + z。

图表提供了滚动和缩放图表部件的能力。图表包含所有的层，而层依次包含所有的部件(Node 和 Link)。部件依次由文本、形状、图片面板嵌套组成。内存中的 JavaScript 对象结构表现为虚拟树的形式，并由图表对象进行绘制。

动画效果由 AnimationManager 实现和控制。自动布局和执行命令后自动发生动画效果。你可以自定义动画效果。

Overview 类允许用户查看整个模型，并操纵图表的显示部分。Palette 类保存了允许用户拖放到图表中的部件。

你可以选择图表中的一个或多个部件。当节点或连线选中时，默认的模板实现会改变其外观。图表也可以添加装饰用于来指示选中状态或支持缩放节点或重连连线的工具。装饰也是工具提示和上下文菜单实现的方式。

所有以编程方式对 Diagram、GraphObject、Model 和模型数据状态作的更改，都应该按每个用户动作放到一个单独的事务里执行，这样才能确保更新正确地发生并支持撤消和重做。所有预定义的工具和命令都是执行事务，因此如果启用了撤消和重做功能（UndoManager 设为 true），则每个用户动作都是可撤消和重做的。图表上的图表事件（DiagramEvent）以及图表和图表对象上的事件处理程序，都被记录在一个事务中。

创建一个图表

GoJS 不依赖任何 JavaScript 库或框架，所以你可以在任何环境中使用它。然而，它要求环境支持现代 HTML 和 JavaScript。

加载 GoJS

在你可以执行任何 JavaScript 代码来构建一个 Diagram 之前，你需要加载 GoJS 库。当你包含该库时，”go” JavaScript 对象会持有所有的 GoJS 类型。在开发时，我们推荐你加载 “go-debug.js” 而不是 “go.js”，以便额外的运行时错误检查和调试能力。

We recommend that you declare that your web page supports modern HTML:

我们推荐你声明你的网页支持现代 HTML：

<!-- 声明标准模式 -->
<!DOCTYPE html>

<html>
  <head>
    <!-- 包含 gojs 库 -->
    <script src="go-debug.js"></script>
  </head>
</html>

如果依赖于你的 npm 环境：

1	import * as go from 'gojs';

如果你的构建环境自动选择了 ECMAScript 模块，你可以使用 release/ 目录下的 go-module.js。

扩展类是用 TypeScript 实现的，并在 extensionsJSM/ 目录下编译为 ECMAScript 模块。这个目录包含在我们网站上下载的包中，或者你可以使用 npm create gojs-kit@latest 安装 create-gojs-kit 包。扩展类被编译为普通的可加载的 JavaScript 文件到 extensions/ 目录。

1	import { DoubleTreeLayout } from './path/to/gojs-kit/dist/extensionsJSM/DoubleTreeLayout.js';

如果使用 RequireJS，GoJS 库支持 UMD 模块定义。将每个扩展文件复制到你的项目中，并更新其 require 语句，使所有代码都加载同一个 GoJS 库，并且只加载一次。

将 GoJS 图表放置到一个 div 元素中

每一个 Diagram 必须由一个 HTML Div 元素托管。GoJS 会管理该 Div 元素的内容，但你可以像任何 HTML 元素一样定位、设置大小和样式化该 Div。图表会将一个 Canvas 元素添加到该 Div 元素中 – 这就是用户实际看到的内容。Canvas 元素会自动调整大小以与 Div 元素保持一致。

<body>
  . . .
  <!-- 图表的 DIV 需要强制声明大小，否则我们不会看见任何东西。 在这个示例中我们添加了一个边框帮助我们识别边界。 -->
  <div
    id="myDiagramDiv"
    style="border: solid 1px blue; width:400px; height:150px"
  ></div>
</body>

然后你可以在 JavaScript 中创建 Diagram 并引用该 Div 元素。通过构造普通的 JavaScript 对象并将其添加到图表的模型中，来构建图表。注意，在 JavaScript 代码中对 GoJS 类型的所有引用都以 “go.” 为前缀。

<!-- 使用 JavaScript 在 DIV 元素中创建图表 -->
<!-- go 对象在其命名空间中保持了所有的 GoJS 类型 -->
<script>
  const diagram = new go.Diagram('myDiagramDiv');
  diagram.model = new go.GraphLinksModel(
    [
      { key: 1, text: 'Hello' }, // 两个节点数据
      { key: 2, text: 'World!' },
    ],
    [{ from: 1, to: 2 }] // 一条连线
  );
</script>

开发你自己的图表

GoJS 输出错误或警告信息，当出现错误时。当使用 GoJS 开发时，请确保检查浏览器的开发者控制台以获取信息。"go-debug.js" 版本的库包含额外的类型检查和错误检查代码，应该在开发时使用。"go.js" 版本没有错误检查，但由于结果更快，因此应该在生产环境中使用。

你的 JavaScript 代码应该仅仅使用 API 文档中的属性和方法。GoJS 库是最小化的，因此你只能在调试模式下查看 GoJS 类的实例，你会看到很多一个或两个字母的属性名称。所有这些都是内部名称，你不应该使用。目前唯一的一个字母属性名称是 Point、Rect、Spot 和 LayoutVertex 上的 “x” 和 “y”。唯一的两个字母属性名称是 InputEvent.up。否则，你不应该尝试在任何 GoJS 定义的对象上使用任何一个或两个字母的属性名称。

不要修改 GoJS 类的原型。

只使用 API 文档中描述的属性和方法。

你可以使用 TypeScript 为了更好的“编辑时”和”编译时”类型检查和“编辑时”文档。GoJS 的 TypeScript 定义文件名为“go.d.ts”和“go-module.d.ts”，它们位于库所在的相同目录中。扩展类是用 TypeScript 实现的，它们位于../extensionsJSM/和../extensions/。将扩展定义复制到你的项目中，并确保它们导入的是与所有代码相同的 GoJS 库。

学习更多的新特性和 bug 修复，请阅读 Change Log。阅读最新版本的下载信息。

你可以在 GoJS Samples 中看到你可以构建的各种图表类型。

In the next introduction page we discuss building GoJS Parts and adding them into Diagrams.
在接下来的介绍页中，我们将讨论如何构建 GoJS 部件并将其添加到图表中。