DAG设计文档

安装使用

请在使用这个项目的项目的html中通过cdn引入viz.js的script标签，比如

<script src="https://cdn.bootcss.com/viz.js/1.8.1/viz-lite.js"></script>

结构

场景

场景即最外的整个包装层，暴露了直接交互的api，自有地维护了ui的交互功能和内部数据结构

import {Scenen} from './dag';

let scene = new Scene(document.getElementById('app'));
scene.load({
  	nodeId: node,
  	...
});

• 组成

  场景由核心的处理计算的模型层，负责可视化和ui交互的图像层，和它自身以及它自身的事件处理器组成，是一个基于mvc思想的单独组件，理论上，需要包在外部的应用层里，提供一套完整的应用，用来与计算层，一般来说应该是一个服务器，进行交互，根据服务器的实际需求，可以选择是否使用增量计算处理

• 数据定义

  /*
  * Definition of Node
  */
  {
    	id: 'a_unique_id',
      // the text shown in the bottom of this node
      name: 'a_no-need-unique_name',
      description: 'a text to help you know this node',
      // the screen position that want this node be
      pos: [x, y],
      // NOTE: the structure of metadata has no limit, prefer an Array includes many objects
      metadata: [{
          name: '偏置',
          value: 3
      }],
      inputs: [input, input, ...],
      outputs: [output, output, ...],
      options: {
          style: {
              bg: {
                	// the node's color
                  background: '#FEF8E1',
              },
              icon: {
                	// the icon you wanna show in the node by icon fonts such as Material Icons
                  font: '60px Material Icons',
                  fillStyle: 'gray',
                  text: 'favorite_border'
              }
          }
      }
  }
  
  /*
  * Definition of Input
  */
  {
  	name: 'fdsaerqwersd',
  	id: 'a_unique_input_id',
  	// outputId means which output this input has connected from the prev link, if hasn't connected, no value for this porperty
  	outputId: 'output_231412eewrew'
  }
  
  /*
  * Definition of Output
  */
  {
  	name: 'a',
  	id: 'a_unique_output_id'
      // no need to record the linked inputs
  }

  ​

模型层

模型层对数据产生的DAG进行结构上的计算，主要进行数据结构的处理，想要了解更多这一层的设计可以阅读模型层内的文档

• 构造连接

  在现有node的数据结构下，传统的nodes/links结构中的links属于不需要的数据，并且推荐在load时根据nodes自己的inputs上的连接关系计算links，避免存储错误等可能导致数据不合法而使模型崩溃的情况。这一层自己构造了对计算层完全隐藏的连接数据并完整地控制了生命周期

• 数据结构处理

  处理了通过API调用和ui操作的图结构修改的各种操作，并且进行增量计算

图像层

图像层负责且仅负责对数据的渲染，不涉及任何计算

• 渲染

  数据的渲染包括了每个节点和顶点的连接，选中状态等，在数据更新时也会进行更新，是数据的实时反应

• 分层

  分为3层，中间层负责展示当前数据，对不完全创建的临时数据，比如正在通过ui进行连接的link，则通过最上层进行展示，最下层目前暂时没有明确的使用情景和目标

事件处理器

场景本身就是一个事件发布／接收的处理器，或者说基于BaseComponent类继承的所有类都具有事件发布与接收功能。这个处理器包含了以下事件流动

• 在图像层监听的ui事件的基本处理，变成数据模型事件
• 监听部分模型事件并直接在模型层进行处理
• 监听部分模型事件并且处理成自定义事件来发布，让其他监听这个事件的对象自己做处理，主要用于内部的交互
• 包装并发布一些自定义事件，主要是对外的事件

对外API

原则上只允许使用对外暴露的API，通过API获取到的数据并没有切断内部引用，在使用API时请务必注意切断引用，推荐创建新数据结构传入

• load(nodes)

  // better to load the data formed by the getData API
  {
      nodeId: nodeEntity,
      anotherNodeId: anotherNodeEntity
  }

  重新载入数据并构建结构，推荐载入数据为getData得到的数据

• getData()

  获取所有的顶点数据

• insertNode(node)

  插入一个新顶点

• removeNode(nodeId)

  删除一个顶点，并且连带删除所有相关连接

• updateNodeProperties(id, node)

  /*
  * Definition of node
  */
  {
    	name: 'bot',
      description: 'it\'s said that this is a robot '
  }

  更新一个顶点的属性，所谓属性是指不影响模型的参数，比如name， description等，这一操作不会产生后续影响

• updateNodeMetadata(nodeId, metadata)

  更新一个顶点的metadata，所谓metadata是指影响到模型的参数，这一操作会影响到模型并产生影响链路

• updateNodeIO(nodeId, inputs, outputs)

  更新顶点的IO属性，这个API支持io数量的变更

  /*
  * Definition of inputs & outputs
  * the definition of input & output are as above
  */
  
  inputs: [input, ...]
  outputs: [output, ...]
  

• complexUpdate(id, properties, metadata, inputs, outputs)

  对一个顶点进行复杂更新，除了id以外其他参数均可以为null或者undefined，意味着不需要更新

• updateNodes(nodes)

  批量更新多个顶点，包含其properties，metadata和IO连接

• adjustViewBox

  调整可视区域的位置以找回这个图

• layout

  自动对图进行布局

对外事件

scene.on('eventName', handler);

通过事件获取到的数据并没有切断内部引用，在使用这些数据时请务必注意切断引用

整个应用具有完善的事件机制，一方面内部实现交互，另一方面对外部抛出一些自定义事件用以同步实时状态，原则上不推荐外部监听较为底层的事件，而是应该监听已做了基本转义处理的自定义事件，目前有如下几个事件

• dagChanged

  任何ui交互，api主动调用（包括load）等引起的图数据模型变动，都会发出这个事件，这些模型变动包括了输入和输出的动态修改，可能影响节点计算逻辑生成的metadata的修改。如果选择增量地去接受模型改变，需要重新生成受影响的节点的计算逻辑，并根据影响链路重新计算链路上的节点的输出

  抛出的模型更改内容仍然保持了模型内部节点数据的引用，对其处理的时候请务必注意

  {
      // nodes whose model like metadata, connections or even existance has changed
      nodes: {
          nodeId: node,
          // for nodes that no longer exist, only return the id info
          deletedNodeId: null
      },
      // the influenced nodes that may need computation again, the order to recomputation is as below, node ids are grouped by layer, the ids in same layer can be executed in parallel cause the node in same layer don't depend on each other
      chain: [[id1], [id2, id3], ...]
  }

• nodePropertyChanged

  一个节点的properties发生了修改时会抛出此事件，一般发生在调用updateNodeProperties API时

  {
      nodeId: nodeEntity
  }

  ​

• dblclickOnNode

  在节点上产生了一个双击的交互，将会给出这个节点的数据模型，用以外部进行修改操作

• rightclickOnNode

  在节点上产生了一个右键单击的交互，将会给出这个节点的数据模型，用以外部进行修改操作

• rightclickOnLink

  在连接上产生了一个右键单击的交互，将会给出这个连接的数据模型，用以外部进行修改操作

• dblclickOnLink (no longer available)

  当前认为所有连接为内部数据

  在连接上产生了一个双击的交互，将会给出两个节点的数据模型，用以重新定义相关的两个节点的具体连接关系，在做这个处理的时候请务必注意数据的合法性

• TODO

  增加你自己认为需要的其他事件