jsPlumb.jsAPI阅读笔记(官方文档翻译)

jsPlumb DOCS

公司要开始作流程控制器，因此先调研下jsPlumb，下文是阅读jsPlumb提供的document所产生的概括总结

setup

若是不使用jQuery或者类jQuery库，则传入的节点得用id的形式,不然jsPlumb会为元素设置一个id。

jsPlumb.ready(function(){
  ···
});
//or
jsPlumb.bind("ready",function(){
  ···
});

最好确认jsPlumb加载完毕以后，再开始使用相关功能。

默认状况下，jsPlumb在浏览器的窗口中注册，为整个页面提供一个静态实例，因此也能够把它当作一个类，来实例化jsPlumb：

var firstInstance = jsPlumb.getInstance();

---

若是在使用过程当中，元素的id产生了新的变化（可能是生成了新的节点，旧的节点被删除了）。则能够：

• jsPlumb.setId(el,newId)

• jsPlumb.setIdChanged(oldId,newId)

在使用过程当中，每一个部分的z-index须要注意，不然连线可能会被覆盖，jsPlumb会为每一个节点设置端点，用于定位端点。

jsPlumb也提供了拖动方法：

var secondInstance = jsPlumb.getInstance();
secondInstance.draggable("some element");

---

重绘，每次使用连线时，都会致使相关联的元素重绘，但当加载大量数据时，可使用：

jsPlumb.setSuspendDrawing(true);

jsPlumb.setSuspendDrawing(false,true);

这里第二个参数的true，会使整个jsPlumb当即重绘。
也可使用batch：

jsPlumb.batch(fn,[doNotRepaintAfterwards]);

这个函数也是同样，能够先将全部的链接所有注册好，再一次重绘。
这个方法在1.7.3版本以前名称为doWhileSuspended.

config defaults

固然，jsPlumb会有一些默认的参数：
分为全局默认参数和连线默认参数，

Anchor : "BottomCenter",//端点的定位点的位置声明（锚点）：left，top，bottom等
Anchors : [ null, null ],//多个锚点的位置声明
ConnectionsDetachable   : true,//链接是否可使用鼠标默认分离
ConnectionOverlays  : [],//附加到每一个链接的默认重叠
Connector : "Bezier",//要使用的默认链接器的类型：折线，流程等
Container : null,//设置父级的元素，一个容器
DoNotThrowErrors  : false,//若是请求不存在的Anchor，Endpoint或Connector，是否会抛出
DragOptions : { },//用于配置拖拽元素的参数
DropOptions : { },//用于配置元素的drop行为的参数
Endpoint : "Dot",//端点（锚点）的样式声明（Dot）
Endpoints : [ null, null ],//多个端点的样式声明（Dot）
EndpointOverlays : [ ],//端点的重叠
EndpointStyle : { fill : "#456" },//端点的css样式声明
EndpointStyles : [ null, null ],//同上
EndpointHoverStyle : null,//鼠标通过样式
EndpointHoverStyles : [ null, null ],//同上
HoverPaintStyle : null,//鼠标通过线的样式
LabelStyle : { color : "black" },／／标签的默认样式。
LogEnabled : false,//是否打开jsPlumb的内部日志记录
Overlays : [ ],//重叠
MaxConnections : 1,//最大链接数
PaintStyle : { lineWidth : 8, stroke : "#456" },//连线样式
ReattachConnections : false,//是否从新链接使用鼠标分离的线
RenderMode : "svg",//默认渲染模式
Scope : "jsPlumb_DefaultScope"//范围，标识

若是是全局则可使用jsPlumb.importDefaults({···})，
也能够在实例化时，从新定义jsPlumb.getInstance({···})，

Basic Concepts

jsPlumb关键点就是链接线，从上面也能够看出，大部分的配置项都是为了线而设。
其分为五个方面：

• Anchor：锚点位置
• Endpoint：端点，链接的起点或终点
• Connector：连线，链接两个节点的直观表现，有四种默认类型：Bezier（贝塞尔曲线），Straight（直线），Flowchart（流程图），State machine（状态机）
• Overlay：装饰链接器的组件，相似箭头之类
• Group：包含在某个其余元素中的一组元素，能够折叠，致使与全部组成员的链接被合并到折叠的组容器上。

Anchor

锚点位置有四种类型：

• Static：静态，会固定到元素上的某个点，不会移动
• Dynamic：动态，是静态锚的集合，就是jsPlumb每次链接时选择最合适的锚
• Perimeter anchors：周边锚，动态锚的应用。

• Continuous anchors：连续锚

1. Static
   jsPlumb有九个默认位置，元素的四个角，元素的中心，元素的每一个边的中点。

• Top(TopCenter),TopRight,TopLeft
• Right(RightMiddle)
• Bottom(BottomCenter),BottomRight,BottomLeft
• Left(LeftMiddle)
• center
  可使用基于数组的形式来定义锚点位置：[x,y,dx,dy,offsetX,offsetY]。
  [0,0]表示节点的左上角。
  x表示锚点在横轴上的距离，y表示锚点在纵轴上的距离，这两个值能够从0到1来设置，0.5为center。
  而dx表示锚点向横轴射出线，dy表示锚点向纵轴射出线，有0，-1，1三个值来设置。0为不放射线。
  offsetX表示锚点偏移量x（px），offsetY表示锚点偏移量y（px）。

1. Dynamic Anchors
   选择每当某物移动或在UI中绘制时最合适的位置。

var dynamicAnchors = [ [0.2,0,0,0],"Top","Bottom" ]

在使用过程当中，发现其就是指定锚点应该出如今哪一个地方。jsPlumb会选取最近的点，来看成锚点。能够设置多个点，来看成可能出现的锚点。
固然，jsPlumb自带了默认的参数，AutoDefault。其实与["Top","Right","Bottom","Left"]相同。

1. Perimeter Anchors
   jsPlumb提供了六种形状：

• Circle
• Ellipse
• Triangle
• Diamond
• Rectangle
• Square

1. Continuous Anchors

anchor:"Continuous"
//or
anchor:["Continuous",{faces:["top","left"]}]

faces一样有四个值：top,left,right,bottom。

将CSS类与Anchors相关联

var ep = jsPlumb.addEndpoint("ele1",{
  anchor:[0,0,0,0,0,0,"test"]
});

也能够修改前缀：

jsPlumb.endpointAnchorClass="anchor_";

Connectors

链接器是实际链接UI元素的线，默认链接器是贝塞尔曲线，也就是默认值是"Bezier";
这里才是画线的地方，

• Bezier：它有一个配置项，curviness（弯曲度），默认为150.这定义了Bezier的控制点与锚点的距离
• Straight：在两个端点之间绘制一条直线，支持两个配置参数：stub，默认为0。gap，默认为0
• Flowchart：由一系列垂直或水平段组成的链接。支持四个参数，stub，默认为30；alwaysRespectStubs，默认为false；gap，默认为0；midpoint，默认为0.5；cornerRadius，默认为0；
• StateMachine：状态器，支持在同一元素上开始和结束的链接，支持的参数有：margin，默认为5；curviness，默认为10；proximityLimit，默认为80；

Endpoints

端点的配置和外观参数。
jsPlumb带有四个端点实现-点，矩形，空白和图像，能够在使用connect(),addEndpoint(),makeSource()或jsPlumb.makeTarget时使用endpoint参数指定Endpoint属性。

给端点进行配置

• jsPlumb.connect(),建立链接的时候能够配置端点的属性
• jsPlumb.addEndpoint(),建立一个新的端点时配置属性
• jsPlumb.makeSource(),配置元素并随后从该元素中拖动链接时，将建立并分配一个新的端点

端点的预设类型

1. Dot：支持三个参数：
   radius，默认为10px，定义圆点的半径
   cssClass，附加到Endpoint建立的元素的CSS类
   hoverClass，一个CSS类，当鼠标悬停在元素或链接的线上时附加到EndPoint建立的元素

2. Rectangle：支持的参数：
   width，默认为20，定义矩形的宽度
   height，默认为20，定义矩形的高度
   cssClass，附加到Endpoint建立的元素的CSS类
   hoverClass，当鼠标悬停在元素或链接的线上时附加到EndPoint建立的元素

3. image：从给定的URL中绘制图像，支持三个参数：
   src，必选，指定要使用的图像的URL，
   cssClass，附加到Endpoint建立的元素的CSS类
   hoverClass，当鼠标悬停在元素或链接的线上时附加到EndPoint建立的元素，

4. Blank：空白

Overlays（叠加层）

jsPlumb有五种类型的叠加：

1. Arrow：箭头，在链接器的某个点绘制的可配置箭头，能够控制箭头的长度和宽度,参数有：
   width，箭头尾部的宽度
   length，从箭头的尾部到头部的距离
   location，位置，建议使用0～1之间，看成百分比，便于理解
   direction，方向，默认值为1（表示向前），可选-1（表示向后）
   foldback，折回，也就是尾翼的角度，默认0.623，当为1时，为正三角
   paintStyle，样式对象

2. Label：在链接点的可配置标签，参数有
   label，要显示的文本
   cssClass，Label的可选css
   labelStyle，标签外观的可选参数：font，适应canvas的字体大小参数；color，标签文本的颜色；padding，标签的可选填充，比例而不是px；borderWidth，标签边框的可选参数，默认为0；borderStyle，颜色等边框参数
   location，位置，默认0.5
   也可使用getLabel，和setLabel，来获取和设置label的文本,可传函数

3. PlainArrow：箭头形状为三角形
   只是Arrow的foldback为1时的例子，参数与Arrow相同

4. Diamond：棱形
   一样是Arrow的foldback为2时的例子，参数与Arrow相同

5. Custom：自定义
   容许建立自定义的叠加层，须要使用create(),来返回DOM元素或者有效的选择器（ID）

var conn = jsPlumb.connect({
source:"d1",
target:"d2",
paintStyle:{
  stroke:"red",
  strokeWidth:3
},
overlays:[
  ["Custom", {
    create:function(component) {
      return $("<select id='myDropDown'><option value='foo'>foo</option><option value='bar'>bar</option></select>");
    },
    location:0.7,
    id:"customOverlay"
  }]
]
});

做为[0,1]的小数，其表示沿着由链接器内接的路径的一些成比例的行程，默认值为0.5。
做为大于1的整数，表示从起点沿链接器行进的某些绝对像素数。等于1时，在终点。
做为小于零的整数，其指示沿着链接器从端点向后行进的一些绝对值的像素。等于0时，在起点。

全部叠加层都支持：
getLocation-返回当前位置
setLocation-设置当前位置

添加叠加层

例子：

jsPlumb.connect({
  overlays:[
    "Arrow",
      [ "Label", { label:"foo", location:0.25, id:"myLabel" } ]
    ]
});

而在addEndpoint和makeSource方法中，则不能使用overlays,须要使用connectOverlays.
也可使用addOverlay:

var e = jsPlumb.addEndpoint("someElement");
e.addOverlay([ "Arrow", { width:10, height:10, id:"arrow" }]);

固然还有获取叠加层的方法：getOverlay(id)这里的id与元素中的id不一样，只是组件在jsPlumb中的惟一标识而已，在控制台打印以后，能看到内部提供了不少方法,另外注意原型链中的方法。

在官方的Hiding/Showing Overlays中，向咱们展现了setVisible,showOverlay(id),hideOverlay(id)，removeOverlay(id)等方法，固然，由于对象中有DOM元素，咱们也可使用其余方法来控制DOM元素。

Groups

至关于给节点之间加入了分组的概念，一旦分组，那么就可使用组来控制组下的全部元素。
但这里的分组仍然是在jsPlumb中创建索引，当有相关事例时，再进行介绍。

Drag

若是不使用jsPlumb提供的拖动，则须要使用repaint()来对拖动以后的连线进行重绘。
而当修改了节点的层级，或者偏移则须要使用revalidate(container)来刷新。

Establishing Connections

在上面的例子中，已经介绍了基本的链接方式jsPlumb.connect({source:"element1",target:"element2"})。
这种方式建立的链接线一旦移除，则建立的端点也会自动移除。若是不想端点被移除，则能够继续加参数，将
deleteEndpointsOnDetach设为false。若是不想鼠标可以移除链接线，则能够在局部配置中将ConnectionsDetachable设为false，或者在connect时，加入detachable:false。

拖放链接

一开始就要建立一个端点来做为源点

var endpoint = jsPlumb.addEndpoint('elementId',{isSource:true})

这样就能够从该端点拉线出去。
若是给另外一个建立的点加入isTarget:true，则就能够用上面的点连入这个点。

或者使用makeSource或者makeTarget：

jsPlumb.makeSource("ele1",{
  anchor:"Continuous",
  maxConnections:1
  ···
})

上述例子中，若是配置了maxConnections，则最多只能出现这个参数的连线，一旦多于这个数目的连线，就能够用onMaxConnections(params,originalEvent)这个回调函数来作其余事.
connect与makeSource，makeTarget，均可以配置第三个参数，至关于公共配置参数，与第二个参数相似。
-----------------------------------------------------------------------

在connect中若是使用newConnection：true参数，则会取消makeTarget，makeSoucr，addEndpoint中所添加的配置项,重绘链接线。

而makeTarget也有onMaxConnections方法。
由于makeTarget包括上面介绍的isTarget均可以指向源点元素，因此，若是不想形成回环（本身连本身），则能够在makeTarget中设置allowLoopback：false.若是只想产生一个端点，而不是多个端点，则须要使用uniqueEndpoint:true.
默认状况下，使用makeTarget建立的端点将deleteEndpointsOnDetach设置为true，即删除连线，端点删除；若是不要删除，则须要手动改成false。
--------------------------------------------------------

若是既配置了元素可拖动，又设置了元素可拖放链接，那jsPlumb没有办法区分拖动元素和从元素中拖动链接，因此它提供了filter方法。

jsPlumb.makeSource("foo",{
  filter:"span",
  filterExclude:true
});

则除span元素的其余元素均可以建立拖放链接，filter也接受函数。filter:function(event,element).

也可使用isTarget("id"),isSource("id")来判断节点是否成为了源点。
若是配置了source和target以后，想切换源的激活状态，则可使用setTargetEnabled(id),setSourceEnabled(id)。
若是想取消makeTarget和makeSource所建立的源点，可使用：

• unmakeTarget("id")
• unmakeSource("id")
• unmakeEveryTarget
• unmakeEverySource

Drag and Drop scope

若是使用了jsPlumb自带的drag或者drop，那么给端点配置scope是颇有必要的，这意味着以后建立端点只能链接到对应scope的端点。若是不设置scope，其默认的scope是同样的。

Removeing Nodes

移除节点没什么好说的，关键仍是要移除与之关联的端点和链接线。

Removeing Connections／Endpoints

Connections

1. detach

var conn = jsPlumb.connect({...});
jsPlumb.detach(conn);

若是使用该方法来删除链接线，那么会有几种状况：

• 若是使用jsPlumb.connect建立的线，并且没有设置deleteEndpointsOnDetach:false,则使用detach时，端点也会一块儿被移除。
• 若是经过makeSource配置的元素建立了链接线，并且没有设置deleteEndpointsOnDetach:false,则使用detach时，端点也会一块儿被移除。
• 若是使用addEndpoint注册的元素经过鼠标建立了链接线，则不会删除端点。

1. detachAllConnections(el,[params])
   用于删除元素上的全部链接线。

2. detachEveryConnection()
   删除全部链接线。

Endpoints

1. deleteEndpoint
   删除一个端点。
2. deleteEveryEndpoint
   删除全部的端点

Connection and Endpoint Types

能够经过提供的方法来动态的修改链接线或端点的样式。

Connection Type

jsPlumb.registerConnectionType("example",{
  paintStyle:{stroke:"blue",strokeWidth:5},
});
var c = jsPlumb.connect({source:"someDiv",target:"someOtherDiv"});
c.bind("click",function(){
  c.setType("example")
});

当点击链接线时，会替换链接线的样式
也可使用：

jsPlumb.registerConnectionTypes({
  "basic":{
    paintStyle:{stroke:"blue",strokeWidth:7}
  },
  "selected":{
    paintStyle:{stroke:"red",strokeWidth:5}
  }
});

c.bind("click",function(){
  c.toggleType("selected");
});

而type支持的属性都和css相关：

• anchor
• anchors
• detachable
• paintStyle
• hoverPaintStyle
• scope
• cssClass
• parameters
• overlays
• endpoint

Endpoint type

jsPlumb.registerEndpointTypes({
  "basic":{
    paintStyle:{fill:"blue"}
  }
});

端点的type支持的参数：

• paintStyle
• endpointStyle
• hoverPaintStyle
• endpointHoverStyle
• maxConnections
• connectorStyle
• connectorHoverStyle
• connector
• connectionType
• scope
• cssClass
• parameters
• overlays

Events

首先看个小例子：

jsPlumb.bind("connection",function(info){
  console.log(info);
});

connection(info,originalEvent)即监听全部的链接事件。info包含的信息有：

• connection
• sourceId
• targetId
• source
• target
• sourceEndpoint
• targetEndpoint

connectionDetached(info,originalEvent)即监听当链接断掉时的事件。info相似connection.

右键点击也有相应的contextmenu方法。

关于connection和endpoint的事件方法，请参考官网api。
记录下overlay的事件。

jsPlumb.connect({
  source:"el1",
  target:"el2",
  overlays:[
    ["Label",{
      events:{
        click:function(labelOverlay,originalEvent){
          console.log(labelOverlay);
        }
      }
      }
    }],
  ]
})

一样，使用unbind方法，能够移除上面所添加的监听。

筛选jsPlumb

使用jsPlumb.select()方法，用于在Connections列表上作筛选，打印一下值：

就可使用这些方法对于链接线来进行获取（get）和修改（set）。
还有getConnections,getAllConnections()等方法也能够获取到链接线，只不过这两个方法没有上面slect的方法，至关于静态属性

使用jsPlumb.selectEndpoints()方法，用于在Endpoints上作筛选，一样有相应的方法。

select()和selectEndpoints()都有一个each方法，用于对筛选出的方法进行操做。

Repainting an element or elements

当须要对修改事后的元素从新计算端点和链接线时，则可使用

jsPlumb.repaint(el,[ui])

或

jsPlumb.repaintEverything().

Element Ids

当元素上的id也被改变时，可使用

jsPlumb.setId(el,newId);
//or
jsPlumb.setIdChanged(oldId,newId);

来从新对以前注册的节点进行修改。

小结

前期调研完成，接下来开始使用jsPlumb作几个小例子。
demo地址: https://github.com/leomYili/Axis/tree/master/umlDemo 下载直接运行便可