jsPlumb.jsAPI閱讀筆記(官方文檔翻譯)

時間 2019-11-13

標籤 jsplumb.jsapi jsplumb jsapi 閱讀筆記官方文檔翻譯欄目 JavaScript 简体版

原文原文鏈接

jsPlumb DOCS

公司要開始作流程控制器，因此先調研下jsPlumb，下文是閱讀jsPlumb提供的document所產生的概括總結css

setup

若是不使用jQuery或者類jQuery庫，則傳入的節點得用id的形式,不然jsPlumb會爲元素設置一個id。node

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

最好確認jsPlumb加載完畢以後，再開始使用相關功能。

默認狀況下，jsPlumb在瀏覽器的窗口中註冊，爲整個頁面提供一個靜態實例，因此也能夠把它當作一個類，來實例化jsPlumb：git

var firstInstance = jsPlumb.getInstance();

若是在使用過程當中，元素的id產生了新的變化（可能是生成了新的節點，舊的節點被刪除了）。則能夠：github

jsPlumb.setId(el,newId)
jsPlumb.setIdChanged(oldId,newId)

在使用過程當中，每一個部分的z-index須要注意，不然連線可能會被覆蓋，jsPlumb會爲每一個節點設置端點，用於定位端點。canvas

jsPlumb也提供了拖動方法：api

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.jsp

config defaults

固然，jsPlumb會有一些默認的參數：
分爲全局默認參數和連線默認參數，ide

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：連續錨

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）。

Dynamic Anchors
選擇每當某物移動或在UI中繪製時最合適的位置。

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

在使用過程當中，發現其就是指定錨點應該出如今哪一個地方。jsPlumb會選取最近的點，來看成錨點。能夠設置多個點，來看成可能出現的錨點。
固然，jsPlumb自帶了默認的參數，AutoDefault。其實與["Top","Right","Bottom","Left"]相同。

Perimeter Anchors
jsPlumb提供了六種形狀：

Circle
Ellipse
Triangle
Diamond
Rectangle
Square

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(),配置元素並隨後從該元素中拖動鏈接時，將建立並分配一個新的端點

端點的預設類型

Dot：支持三個參數：
radius，默認爲10px，定義圓點的半徑
cssClass，附加到Endpoint建立的元素的CSS類
hoverClass，一個CSS類，當鼠標懸停在元素或鏈接的線上時附加到EndPoint建立的元素
Rectangle：支持的參數：
width，默認爲20，定義矩形的寬度
height，默認爲20，定義矩形的高度
cssClass，附加到Endpoint建立的元素的CSS類
hoverClass，當鼠標懸停在元素或鏈接的線上時附加到EndPoint建立的元素
image：從給定的URL中繪製圖像，支持三個參數：
src，必選，指定要使用的圖像的URL，
cssClass，附加到Endpoint建立的元素的CSS類
hoverClass，當鼠標懸停在元素或鏈接的線上時附加到EndPoint建立的元素，
Blank：空白

Overlays（疊加層）

jsPlumb有五種類型的疊加：

Arrow：箭頭，在鏈接器的某個點繪製的可配置箭頭，能夠控制箭頭的長度和寬度,參數有：
width，箭頭尾部的寬度
length，從箭頭的尾部到頭部的距離
location，位置，建議使用0～1之間，看成百分比，便於理解
direction，方向，默認值爲1（表示向前），可選-1（表示向後）
foldback，折回，也就是尾翼的角度，默認0.623，當爲1時，爲正三角
paintStyle，樣式對象
Label：在鏈接點的可配置標籤，參數有
label，要顯示的文本
cssClass，Label的可選css
labelStyle，標籤外觀的可選參數：font，適應canvas的字體大小參數；color，標籤文本的顏色；padding，標籤的可選填充，比例而不是px；borderWidth，標籤邊框的可選參數，默認爲0；borderStyle，顏色等邊框參數
location，位置，默認0.5
也可使用getLabel，和setLabel，來獲取和設置label的文本,可傳函數
PlainArrow：箭頭形狀爲三角形
只是Arrow的foldback爲1時的例子，參數與Arrow相同
Diamond：棱形
一樣是Arrow的foldback爲2時的例子，參數與Arrow相同
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

detach

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

若是使用該方法來刪除鏈接線，那麼會有幾種狀況：

若是使用jsPlumb.connect建立的線，並且沒有設置deleteEndpointsOnDetach:false,則使用detach時，端點也會一塊兒被移除。
若是經過makeSource配置的元素建立了鏈接線，並且沒有設置deleteEndpointsOnDetach:false,則使用detach時，端點也會一塊兒被移除。
若是使用addEndpoint註冊的元素經過鼠標建立了鏈接線，則不會刪除端點。

detachAllConnections(el,[params])
用於刪除元素上的全部鏈接線。
detachEveryConnection()
刪除全部鏈接線。

Endpoints

deleteEndpoint
刪除一個端點。
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 下載直接運行便可

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。