Graph

阅读时间约 60 分钟

constructor

new Graph(options: Options)
选项类型必选默认值描述
containerHTMLElement画布的容器。
modelModelundefined画布对应的模型,默认创建一个新模型。
widthnumberundefined画布宽度,默认使用容器宽度。
heightnumberundefined画布高度,默认使用容器高度。
gridboolean | number | objectfalse网格,默认使用 10px 的网格,但不绘制网格背景。
backgroundfalse | objectfalse背景,默认不绘制背景。
snaplineboolean | objectfalse对齐线,默认禁用。
scrollerboolean | objectfalse滚动画布,默认禁用。
minimapboolean | objectfalse小地图,默认禁用。
historyboolean | objectfalse撤销/重做,默认禁用。
clipboardboolean | objectfalse剪切板,默认禁用。
keyboardboolean | objectfalse键盘快捷键,默认禁用。
mousewheelboolean | objectfalse鼠标滚轮缩放,默认禁用。
selectingboolean | objectfalse点选/框选,默认禁用。
rotatingboolean | objectfalse旋转节点,默认禁用。
resizingboolean | objectfalse缩放节点,默认禁用。
translatingobjectobject平移节点。
transformingobjectobject平移和缩放节点的基础选项。
embeddingboolean | objectfalse嵌套节点,默认禁用。
connectingobjectobject连线选项。
highlightingobjectobject高亮选项。
interactingobject | function{ edgeLabelMovable: false }定制节点和边的交互行为。
sorting'none' | 'approx' | 'exact''exact'节点和边视图的排序方式。
asyncbooleanfalse是否是异步渲染的画布。
frozenbooleanfalse异步渲染的画布是否处于冻结状态。
checkViewfunction-返回指定的视图是否应该渲染到 DOM 中。
magnetThresholdnumber | 'onleave'0鼠标移动多少次后才触发连线,或者设置为 'onleave' 时表示鼠标移出元素时才触发连线。
moveThresholdnumber0触发 'mousemove' 事件之前,允许鼠标移动的次数。
clickThresholdnumber0当鼠标移动次数超过指定的数字时,将不触发鼠标点击事件。
preventDefaultContextMenubooleantrue是否禁用浏览器默认右键菜单。
preventDefaultBlankActionbooleantrue在画布空白位置响应鼠标事件时,是否禁用鼠标默认行为。
guardfunction() => false返回是否应该忽略某个鼠标事件,返回 true 时忽略指定的鼠标事件。
allowRubberbandfunction() => true返回是否响应框选事件。
allowPanningfunction() => true返回是否响应画布平移事件。
getCellViewfunction() => null获取节点/边的视图类。
createCellViewfunctionundefined创建节点/边的视图,默认自动根据节点和边的 view 选项创建对应的视图。
getHTMLComponentfunctionundefined获取 HTML 节点的 HTML 元素,默认根据节点的 html 选项返回对应的 HTML 元素。
onPortRenderedfunctionundefined当某个链接桩渲染完成时触发的回调。
onEdgeLabelRenderedfunctionundefined当边的文本标签渲染完成时触发的回调。
onToolItemCreatedfunctionundefined当工具项渲染完成时触发的回调。

container

画布容器。

model

画布对应的模型,默认创建一个新模型。

width

画布宽度,默认使用容器宽度。创建画布后可以使用 resize(w, h) 方法来设置画布大小。

height

画布高度,默认使用容器高度。 创建画布后可以使用 resize(w, h) 方法来设置画布大小。

grid

网格是渲染/移动节点的最小单位。网格默认大小为 10px,渲染节点时表示以 10 为最小单位对齐到网格,如位置为 { x: 24, y: 38 }的节点渲染到画布后的实际位置为 { x: 20, y: 40 }, 移动节点时表示每次移动最小距离为 10px

size

创建画布时,通过下面配置来设置网格大小。

const graph = new Graph({
  grid: 10,
})

// 等同于
const graph = new Graph({
  grid: {
    size: 10,
  },
})

创建画布后,可以调用 graph.setGridSize(gridSize: number) 方法来修改网格大小,并触发网格重绘(如果网格可见)。

graph.setGridSize(10)

type

网格默认不可见,创建画布时,通过下面配置来启用网格绘制。

const graph = new Graph({
  grid: true, // 网格大小 10px,并绘制网格
})

// 等同于
const graph = new Graph({
  grid: {
    size: 10,      // 网格大小 10px
    visible: true, // 绘制网格,默认绘制 dot 类型网格
  },
})

同时,我们内置了以下四种网格类型,通过 type 选项来指定网格类型,默认值为 'dot',并支持通过 args 选项来配置网格样式。

  • dot (默认值)
  • fixedDot
  • mesh

    const graph = new Graph({
      grid: {
        size: 10,
        visible: true,
        type: 'dot', // 'dot' | 'fixedDot' | 'mesh'
        args: { 
          color: '#a0a0a0', // 网格线/点颜色
          thickness: 1,     // 网格线宽度/网格点大小
        },
      },
    })
  • doubleMesh

    const graph = new Graph({
      grid: {
        size: 10,
        visible: true,
        type: 'doubleMesh',
        args: [
          { 
            color: '#eee', // 主网格线颜色
            thickness: 1,     // 主网格线宽度
          },
          { 
            color: '#ddd', // 次网格线颜色
            thickness: 1,     // 次网格线宽度
            factor: 4,        // 主次网格线间隔
          },
        ],
      },
    })

创建画布后,可以调用 graph.drawGrid(options?: DrawGridOptions) 来重绘网格。

例如,使用网格颜色 #f0f0f0 和默认线宽绘制 mesh 类型网格。

graph.drawGrid({
  type: 'mesh',
  args: {
    color: '#f0f0f0'
  },
})

API

background

背景用于为画布指定背景颜色或背景图片,支持水印背景自定义背景图片的重复方式,背景层在 DOM 层级上位于画布的最底层。

创建画布时,通过 background 选项来设置画布的背景颜色或背景图片,默认值为 false 表示没有(透明)背景。

const graph = new Graph({
  background: false | BackgroundOptions
})

创建画布后,可以调用 graph.drawBackground(options?: BackgroundOptions) 方法来重绘背景。

graph.drawBackground({
  color: '#f5f5f5',
})

支持的选项如下:

interface BackgroundOptions {
  color?: string
  image?: string
  position?: CSS.BackgroundPositionProperty<{
    x: number
    y: number
  }>
  size?: CSS.BackgroundSizeProperty<{
    width: number
    height: number
  }>
  repeat?: CSS.BackgroundRepeatProperty
  opacity?: number
  quality?: number
  angle?: number
}

color

背景颜色,支持所有 CSS background-color 属性的取值,如:

  • 'red'
  • '#f5f5f5'
  • 'rgba(255, 255, 128, 0.5)'
  • 'hsla(50, 33%, 25%, 0.75)'
  • 'radial-gradient(ellipse at center, red, green)'

image

背景图片的 URL 地址。默认值为 undefined,表示没有背景图片。

position

背景图片位置,支持所有 CSS background-position 属性的取值,默认为 'center'

size

背景图片大小,支持所有 CSS background-size 属性的取值,默认为 'auto auto'

repeat

背景图片重复方式,支持所有 CSS background-repeat 属性的取值,默认为 'no-repeat'

另外,还支持以下几个预定义值:

opacity

背景透明度,取值范围 [0, 1],默认值为 1

quality

背景图片质量,取值范围 [0, 1],默认值为 1

angle

水印旋转角度,仅当 repeat'watermark' 时有效,默认值为 20

API

snapline

对齐线是移动节点排版的辅助工具,默认禁用。创建画布时,通过如下配置启用。

const graph = new Graph({
  snapline: true,
})

// 等同于
const graph = new Graph({
  snapline: {
    enabled: true,
  },
})

创建画布后,可以调用 graph.enableSnapline()graph.disableSnapline() 来启用和禁用对齐线。

if (graph.isSnaplineEnabled()) {
  graph.disableSnapline()
} else {
  graph.enableSnapline()
}

支持的选项如下:

interface SnaplineOptions {
  className?: string
  tolerance?: number
  sharp?: boolean
  resizing?: boolean
  clean?: boolean
  filter?: (string | { id: string })[] | ((this: Graph, node: Node) => boolean)
}

className

附加样式名,用于定制对齐线样式。默认为 undefined

const graph = new Graph({
  snapline: {
    enabled: true,
    className: 'my-snapline',
  },
})

tolerance

对齐精度,即移动节点时与目标位置的距离小于 tolerance 时触发显示对齐线。默认为 10

const graph = new Graph({
  snapline: {
    enabled: true,
    tolerance: 10,
  },
})

sharp

是否显示截断的对齐线,默认为 false

resizing

改变节点大小时是否触发对齐线,默认为 false

clean

当对齐线隐藏后,是否自动将其从 DOM 中移除。支持 booleannumber 类型,当为 number 类型时,表示延迟多少毫秒后从 DOM 移除,这样就可以避免移动节点时对齐线被频繁添加/移除到 DOM,又能保证停止移动节点一定时间后能清理掉对齐线。当 cleantrue 时,相当于延迟 3000ms 后清理对齐线。

const graph = new Graph({
  snapline: {
    enabled: true,
    clean: 5000,
  },
})

filter

节点过滤器,被过滤的节点不参与对齐计算。支持以下三种类型:

  • string[] 节点类型数组,指定的节点类型不参与对齐计算
  • ({ id: string })[] 节点(类节点)数组,指定的节点不参与对齐计算
  • (this: Graph, node: Node) => boolean 返回 true 的节点不参与对齐计算
const graph = new Graph({
  snapline: {
    enabled: true,
    filter: ['rect'],
  },
})

// 等同于
const graph = new Graph({
  snapline: {
    enabled: true,
    filter(node) {
      return node.type === 'rect'
    },
  },
})

API

scroller

Scroller 使画布具备滚动、平移、居中、缩放等能力,默认禁用。创建画布时,通过下面配置即可开启。

const graph = new Graph({
  scroller: true,
})

// 等同于
const graph = new Graph({
  scroller: {
    enabled: true,
  },
})

支持的选项如下:

interface ScrollerOptions {
  enabled?: boolean
  pannable?: boolean
  className?: string
  width?: number
  height?: number
  modifiers?: string | ('alt' | 'ctrl' | 'meta' | 'shift')[] | null
  cursor?: string
  pageWidth?: number
  pageHeight?: number
  pageVisible?: boolean
  pageBreak?: boolean
  autoResize?: boolean
  minVisibleWidth?: number
  minVisibleHeight?: number
  padding?: number | { top: number; right: number; bottom: number; left: number}
  background?: false | BackgroundOptions
}

className

附加样式名,用于定制样式。默认为 undefined

const graph = new Graph({
  scroller: {
    enabled: true,
    className: 'my-scroller',
  },
})

width

Scroller 的宽度,默认为画布容器宽度。

height

Scroller 的高度,默认为画布容器高度。

pannable

是否启用画布平移能力(在空白位置按下鼠标后拖动平移画布),默认为 false

const graph = new Graph({
  scroller: {
    enabled: true,
    pannable: true,
  },
})

创建画布后,也可以调用 graph.enablePanning()graph.disablePanning() 来启用和禁用画布平移。

if (graph.isPannable()) {
  graph.disablePanning()
} else {
  graph.enablePanning()
}

modifiers

修饰键('alt''ctrl''meta''shift'),设置修饰键后需要点击鼠标并按下修饰键才能触发画布拖拽。修饰键在某些场景下非常有用,比如同时开始框选和拖拽画布时,而框选和拖拽画布的触发时机都是鼠标左键在画布空白位置按下,这时可以为框选和拖拽画布设置不一样的修饰键,达到同时开启又不冲突的效果。

支持配置单个(如 'alt')或多个(如 ['alt', 'ctrl'])修饰键,通过数组形式配置的多个修饰键是或关系,比如刚刚配置的修饰键表示按下 'alt''ctrl',如果需要更加灵活的配置,可以使用如下这些形式:

  • 'alt|ctrl' 表示按下 'alt''ctrl'
  • 'alt&ctrl' 表示同时按下 'alt''ctrl'
  • 'alt|ctrl&shift' 表示同时按下 'alt''shift' 或者同时按下 'ctrl''shift'

cursor

画布鼠标样式,默认为空。

cursor 为空并开启拖拽时,将自动为画布设置 grab 鼠标样式。

padding

设置画布四周的 padding 边距。默认根据 minVisibleWidthminVisibleHeight 自动计算得到,保证画布滚动时,在宽度和高度方向至少有 minVisibleWidthminVisibleHeight 大小的画布可见。

minVisibleWidth

padding 为空时有效,设置画布滚动时画布的最小可见宽度。

minVisibleHeight

padding 为空时有效,设置画布滚动时画布的最小可见高度。

pageVisible

是否分页,默认为 false

pageBreak

是否显示分页符,默认为 false

pageWidth

每一页的宽度,默认为画布容器宽度。

pageHeight

每一页的高度,默认为画布容器高度。

autoResize

是否自动扩充/缩小画布,默认为 true。开启后,移动节点/边时将自动计算需要的画布大小,当超出当前画布大小时,按照 pageWidthpageHeight 自动扩充画布。反之,则自动缩小画布。

API

  • zoom(...) 缩放画布。
  • zoomTo(...) 缩放画布到指定的缩放比例。
  • zoomToFit(...) 缩放画布内容,使画布内容充满视口。
  • zoomToRect(...) 缩放和平移画布,使 rect 表示的矩形区域(相对于画布坐标)充满视口。
  • center(...) 将画布中心与视口中心对齐。如果不能通过滚动来对齐,则自动为 Scroller 的容器增加一定的 padding 边距来强制对齐。
  • centerPoint(...)xy 指定的点(相对于画布)与视口中心对齐。如果不能通过滚动来对齐,则自动为 Scroller 的容器增加一定的 padding 边距来强制对齐。
  • centerContent(...) 将画布内容中心与视口中心对齐。如果不能通过滚动来对齐,则自动为 Scroller 的容器增加一定的 padding 边距来强制对齐。
  • centerCell(...) 将节点/边的中心与视口中心对齐。如果不能通过滚动来对齐,则自动为 Scroller 的容器增加一定的 padding 边距来强制对齐。
  • positionContent(...)pos 代表的画布内容 BBox 位置与对应的画布视口位置对齐。
  • positionCell(...)pos 代表的节点/边 BBox 位置与对应的画布视口位置对齐。
  • positionRect(...)pos 代表的矩形位置与对应的画布视口位置对齐。
  • positionPoint(...)point 指定的点(相对于画布)与 xy 代表的画布视口位置对齐。
  • scrollToPoint(...)xy 指定的点(相对于画布)滚动到视口中心,如果只指定了其中一个方向,则只滚动对应的方向。该方法将尽量滚动画布,使指定的点位于视口中心,这意味着滚动后指定的点不一定位于视口中心。
  • scrollToContent(...) 滚动画布,使画布的内容中心位于画布的视口中心。该方法将尽量滚动画布,使画布的内容中心位于画布的视口中心,这意味着滚动后内容中心不一定位于视口中心。
  • scrollToCell(...) 滚动画布,使节点/边的中心位于画布的视口中心。该方法将尽量滚动画布,使节点/边的中心位于视口中心,这意味着滚动后节点/边的中心不一定位于视口中心。
  • transitionToPoint(...) 使用动画平移画布,将画布上指定点(相对于画布的坐标)与视口中心对齐。
  • transitionToRect(...) 使用动画缩放和平移画布,使指定的矩形(相对于画布的坐标)充满视口。
  • isPannable() 画布是否可被平移。
  • enablePanning() 启用画布平移。
  • disablePanning() 禁用画布平移。
  • togglePanning() 切换或设置画布平移。
  • lockScroller() 禁止滚动。
  • unlockScroller() 启用滚动。
  • updateScroller()
  • getScrollbarPosition() 获取滚动条位置。
  • setScrollbarPosition(...) 设置滚动条位置。

minimap

启用 Scroller 后可开启小地图,小地图是完整画布的预览,支持通过平移缩放小地图的视口来平移缩放画布。

const graph = new Graph({
  scroller: {
    enabled: true,
  },
  minimap: {
    enabled: true,
    container: minimapContainer,
  }
})

支持的选项如下:

interface MiniMapOptions {
  enabled: boolean 
  container: HTMLElement 
  width: number   
  height: number  
  padding: number  
  scalable?: boolean 
  minScale?: number
  maxScale?: number
  graphOptions?: Graph.Options
  createGraph?: (options: Graph.Options) => Graph
}

enabled

小地图是否被启用,默认为 false

container

挂载小地图的容器,必选。

width

小地图的宽度,默认为 300。将通过 CSS 应用到小地图容器 container 上。

height

小地图的高度,默认为 200。将通过 CSS 应用到小地图容器 container 上。

padding

小地图容器的 padding 边距,默认为 10。将通过 CSS 应用到小地图容器 container 上。

scalable

是否可缩放,默认为 true

minScale

最小缩放比例,默认为 0.01

maxScale

最大缩放比例,默认为 16

graphOptions

创建小地图 Graph 的选项,默认为 null

通过该选项可以定制小地图画布的表现和行为,如下面配置(在小地图中只渲染节点,并且节点的 View 被替换为指定的 View)。

const graph = new Graph({
  scroller: {
    enabled: true,
  },
  minimap: {
    enabled: true,
    container: minimapContainer,
    graphOptions: {
      async: true,
      getCellView(cell) {
        // 用指定的 View 替换节点默认的 View
        if (cell.isNode()) {
          return SimpleNodeView
        }
      },
      createCellView(cell) {
        // 在小地图中不渲染边
        if (cell.isEdge()) {
          return null
        }
      },
    }
  }
})

createGraph

创建小地图 Graph,默认返回默认 Graph 的实例。

history

撤销/重做,默认禁用。创建画布时,通过以下配置开启画布撤销/重做能力。

const graph = new Graph({
  history: true,
})

// 等同于
const graph = new Graph({
  history: {
    enable: true,
  },
})

创建画布后,调用 graph.enableHistory()graph.disableHistory() 来启用和禁用。

if (graph.isHistoryEnabled()) {
  graph.disableHistory()
} else {
  graph.enableHistory()
}

支持的选项如下:

interface HistoryOptions {
  ignoreAdd?: boolean
  ignoreRemove?: boolean
  ignoreChange?: boolean
  beforeAddCommand?: <T extends ModelEvents>(
    this: HistoryManager,
    event: T,
    args: Model.EventArgs[T],
  ) => any
  afterAddCommand?: <T extends ModelEvents>(
    this: HistoryManager,
    event: T,
    args: Model.EventArgs[T],
    cmd: Command,
  ) => any
  executeCommand?: (
    this: HistoryManager,
    cmd: Command,
    revert: boolean,
    options: KeyValue,
  ) => any
  revertOptionsList?: string[]
  applyOptionsList?: string[]
}

ignoreAdd, ignoreRemove, ignoreChange

默认情况下,画布中节点/边的任何变化(添加/删除/属性变化)都将被追踪,我们提供了一些选项来控制需要追踪哪些变化:

  • ignoreAdd 是否忽略添加,默认为 false
  • ignoreRemove 是否忽略删除,默认为 false
  • ignoreChange 是否忽略属性变化,默认为 false

例如,下面配置只追踪节点和边的属性变化:

const graph = new Graph({
  history: {
    enable: true,
    ignoreAdd: true,
    ignoreRemove: true,
    ignoreChange: false,
  },
})

beforeAddCommand

当一个命令被添加到 Undo 队列前被调用,如果该方法返回 false,那么这个命令将不会被添加到 Undo 队列中。

const graph = new Graph({
  history: {
    enable: true,
    beforeAddCommand(event, args) {
      if (args.options) {
        return args.options.ignore !== false
      }
    },
  },
})

afterAddCommand

当一个命令被添加到 Undo 队列后被调用。

executeCommand

executeCommand?: (
  this: HistoryManager,
  cmd: Command,
  revert: boolean,
  options: KeyValue,
) => any

当命令被撤销或重做时被调用,reverttrue 表示命令被撤销,否则表示命令被重做。

revertOptionsList

传递给撤销动作的选项名数组。

const graph = new Graph({
  history: {
    enable: true,
    revertOptionsList: [ 'option1' ],
  },
})

node.prop('name', 'value', { option1: 5, option2: 6 });
graph.undo(); // -> calls node.prop('name', 'prevValue', { option1: 5 });

applyOptionsList

传递给重做动作的选项名数组。

const graph = new Graph({
  history: {
    enable: true,
    applyOptionsList: [ 'option2' ],
  },
})

node.set('name', 'value', { option1: 5, option2: 6 });
graph.undo();
graph.redo(); // -> calls node.set('name', 'value', { option2: 6 });

事件

  • undo 当命令被撤销时触发。

    graph.history.on('undo', (args: {
      cmds: Command[]
      options: KeyValue
    }) => { 
      // code here
    })
  • redo 当命令被重做时触发。

    graph.history.on('redo', (args: {
      cmds: Command[]
      options: KeyValue
    }) => { 
      // code here
    })
  • cancel 当命令被取消时触发。

    graph.history.on('cancel', (args: {
      cmds: Command[]
      options: KeyValue
    }) => { 
      // code here
    })
  • add 当命令被添加到队列时触发。

    graph.history.on('add', (args: {
      cmds: Command[]
      options: KeyValue
    }) => { 
      // code here
    })
  • clean 当历史队列被清空时触发。

    graph.history.on('clean', (args: {
      cmds: Command[] | null
      options: KeyValue
    }) => { 
      // code here
    })
  • change 当历史队列改变时触发。

    graph.history.on('change', (args: {
      cmds: Command[] | null
      options: KeyValue
    }) => { 
      // code here
    })
  • batch 当接收到 batch 命令时触发。

    graph.history.on('batch', (args: { 
      cmd: Command 
      options: KeyValue 
    }) => { 
      // code here
    })

API

clipboard

剪切板,默认禁用。创建画布时通过以下配置启用。

const graph = new Graph({
  clipboard: true,
})

// 等同于
const graph = new Graph({
  clipboard: {
    enabled: true,
  }
})

创建画布后,可以调用 graph.enableClipboard()graph.disableClipboard() 来启用和禁用剪贴板。

if (graph.isClipboardEnabled()) {
  graph.disableClipboard()
} else {
  graph.enableClipboard()
}

useLocalStorage

开启 useLocalStorage 后,被复制的节点/边同时被保存到 localStorage 中,浏览器刷新或者关闭后重新打开,复制/粘贴也能正常工作。

可以在创建画布时全局开启。

const graph = new Graph({
  clipboard: {
    enabled: true,
    useLocalStorage: true,
  }
})

也可以在调用以下三个方法时开启。

例如:

graph.copy(cells, {
  useLocalStorage: true,
})

API

keyboard

键盘快捷键,默认禁用。创建画布时通过以下配置启用。

const graph = new Graph({
  keyboard: true,
})

// 等同于
const graph = new Graph({
  keyboard: {
    enabled: true,
  },
})

创建画布后,也可以调用 graph.enableKeyboard()graph.disableKeyboard() 来启用和禁用键盘事件。

if (graph.isKeyboardEnabled()) {
  graph.disableKeyboard()
} else {
  graph.enableKeyboard()
}

由于示例通过 iframe 嵌入,导致快捷键失效,请点击【在新窗口中打开】按钮去体验。

支持的选项如下:

interface KeyboardOptions {
  enabled?: boolean
  global?: boolean
  format?: (this: Graph, key: string) => string
  guard?: (this: Graph, e: KeyboardEvent) => boolean
}

enabled

是否开启键盘快捷键。

global

是否为全局键盘事件,设置为 true 时键盘事件绑定在 Document 上,否则绑定在画布容器上。当绑定在画布容器上时,需要容器获得焦点才能触发键盘事件。默认为 false

format

绑定或解绑键盘事件时,格式化按键字符串。

const graph = new Graph({
  keyboard: {
    enabled: true,
    format(key) { 
      return key
      .replace(/\s/g, '')
      .replace('cmd', 'command')
    },
  },
})

graph.bindKey('cmd', (e) => { })
// 被格式化后等同于 graph.bindKey('command', (e) => { })

guard

判断一个键盘事件是否应该被处理,返回 false 时对应的键盘事件被忽略。

const graph = new Graph({
  keyboard: {
    enabled: true,
    guard(this: Graph, e: KeyboardEvent) {
      if (e.altKey) { // 当按下 alt 键时,忽略所有键盘事件
        return false 
      }
      return true
    },
  },
})

API

mousewheel

鼠标滚轮的默认行为是滚动页面,启用 Scroller 后用于滚动画布,但在某些场景下我们需要用滚轮来缩放画布,所为了避免交互冲突,通常配合修饰键来实现滚轮缩放画布,参考下面配置。

const graph = new Graph({
  scroller: {
    enabled: true,
    pannable: true,
    pageVisible: true,
    pageBreak: false,
  },
  mousewheel: {
    enabled: true,
    modifiers: ['ctrl', 'meta'],
  },
})

按住 Command 键通过滚轮缩放画布。

支持的选项如下:

interface MouseWheelOptions {
  enabled?: boolean
  global?: boolean
  factor?: number
  zoomAtMousePosition?: boolean
  modifiers?: string | ('alt' | 'ctrl' | 'meta' | 'shift')[] | null
  guard?: (this: Graph, e: WheelEvent) => boolean
}

enabled

是否开启滚轮缩放交互。

factor

滚动缩放因子。默认为 1.2

zoomAtMousePosition

是否将鼠标位置作为中心缩放,默认为 true

global

是否为全局事件,设置为 true 时滚轮事件绑定在 Document 上,否则绑定在画布容器上。默认为 false

modifiers

修饰键('alt''ctrl''meta''shift'),设置修饰键后需要按下修饰键并滚动鼠标滚轮时才触发画布缩放。通过设置修饰键可以解决默认滚动行为与画布缩放冲突问题。

支持配置单个(如 'alt')或多个(如 ['alt', 'ctrl'])修饰键,通过数组形式配置的多个修饰键是或关系,比如刚刚配置的修饰键表示按下 'alt''ctrl',如果需要更加灵活的配置,可以使用如下这些形式:

  • 'alt|ctrl' 表示按下 'alt''ctrl'
  • 'alt&ctrl' 表示同时按下 'alt''ctrl'
  • 'alt|ctrl&shift' 表示同时按下 'alt''shift' 或者同时按下 'ctrl''shift'

guard

判断一个滚轮事件是否应该被处理,返回 false 时对应的事件被忽略。

const graph = new Graph({
  mousewheel: {
    enabled: true,
    guard(this: Graph, e: WheelEvent) {
      if (e.altKey) { // 当按下 alt 键时,忽略所有滚动事件
        return false
      }
      return true
    },
  },
})

API

selecting

点选/框选,默认禁用。创建画布时,通过以下配置开启选择交互,开启后可以通过点击或者套索框选节点。

const graph = new Graph({
  selecting: true,
})

// 等同于
const graph = new Graph({
  selecting: {
    enabled: true,
  },
})

创建画布后,可以调用 graph.enableSelection()graph.disableSelection() 来启用和禁用选择交互。

if (graph.isSelectionEnabled()) {
  graph.disableSelection()
} else {
  graph.enableSelection()
}

支持的选项如下:

interface SelectionOptions {
  className?: string
  multiple?: boolean
  rubberband?: boolean
  strict?: boolean
  modifiers?: string | ('alt' | 'ctrl' | 'meta' | 'shift')[] | null
  movable?: boolean
  content?:
    | null
    | false
    | string
    | ((
        this: Graph,
        selection: Selection,
        contentElement: HTMLElement,
      ) => string)
  filter?: 
    | null 
    | (string 
    | { id: string })[] 
    | ((this: Graph, cell: Cell) => boolean)
}

className

附加样式名,用于定制样式,默认为 undefined

const graph = new Graph({
  selecting: {
    enabled: true,
    className: 'my-selecting',
  },
})

multiple

是否启用点击多选,默认为 true。启用多选后按住 ctrlcommand 键点击节点实现多选。

rubberband

是否启用框选,默认为 false

const graph = new Graph({
  selecting: {
    enabled: true,
    rubberband: true, // 启用框选
  },
})

创建画布后,可以调用 graph.enableRubberband()graph.disableRubberband() 来启用和禁用框选。

if (graph.isRubberbandEnabled()) {
  graph.disableRubberband()
} else {
  graph.enableRubberband()
}

strict

启用框选时,选框完全包围节点时才选中节点,否则只需要选框与节点的包围盒(BBox)相交即可选中节点,默认为 false

modifiers

修饰键('alt''ctrl''meta''shift'),设置修饰键后需要点击鼠标并按下修饰键才能触发框选。修饰键在某些场景下非常有用,比如同时开始框选和拖拽画布时,而框选和拖拽画布的触发时机都是鼠标左键在画布空白位置按下,这时可以为框选和拖拽画布设置不一样的修饰键,达到同时开启又不冲突的效果。

支持配置单个(如 'alt')或多个(如 ['alt', 'ctrl'])修饰键,通过数组形式配置的多个修饰键是或关系,比如刚刚配置的修饰键表示按下 'alt''ctrl',如果需要更加灵活的配置,可以使用如下这些形式:

  • 'alt|ctrl' 表示按下 'alt''ctrl'
  • 'alt&ctrl' 表示同时按下 'alt''ctrl'
  • 'alt|ctrl&shift' 表示同时按下 'alt''shift' 或者同时按下 'ctrl''shift'

movable

选中的节点是否可以被移动,设置为 true 时,拖动选框触发节点移动,默认为 true

content

设置附加显示的内容。

filter

节点过滤器,被过滤的节点将不能被选中。支持以下三种类型:

  • string[] 节点类型数组,指定的节点类型不参与对齐计算
  • ({ id: string })[] 节点(类节点)数组,指定的节点不参与对齐计算
  • (this: Graph, node: Node) => boolean 返回 true 的节点不参与对齐计算
const graph = new Graph({
  selecting: {
    enabled: true,
    filter: ['rect'], // 'rect' 类型节点不能被选中
  },
})

// 等同于
const graph = new Graph({
  selecting: {
    enabled: true,
    filter(node) {
      return node.type === 'rect'
    },
  },
})

事件

  • cell:selected 节点/边被选中时触发。
  • node:selected 节点被选中时触发。
  • edge:selected 边被选中时触发。
  • cell:unselected 节点/边被取消选中时触发。
  • node:unselected 节点被取消选中时触发。
  • edge:unselected 边被取消选中时触发。
  • selection:changed 选中的节点/边发生改变(增删)时触发。

API

rotating

旋转节点,默认禁用。开启后可以对节点进行旋转。

const graph = new Graph({
  rotating: true,
})

// 等同于
const graph = new Graph({
  rotating: {
    enabled: true,
    grid: 15,
  },
})

支持的选项如下:

export interface RotatingRaw {
  enabled?: boolean
  grid?: number
}

enabled

是否开启节点旋转,默认值为 false

grid

每次旋转的角度,默认值为 15

resizing

缩放节点,默认禁用。开启后可以对节点进行缩放。

const graph = new Graph({
  resizing: true,
})

// 等同于
const graph = new Graph({
  resizing: {
    enabled: true,
    minWidth: 0,
    minHeight: 0,
    maxWidth: Number.MAX_SAFE_INTEGER,
    maxHeight: Number.MAX_SAFE_INTEGER,
    orthogonal: true,
    restricted: false,
    autoScroll: true,
    preserveAspectRatio: false,
  },
})

每一个配置都支持函数,比如 enabled:

 new graph({ 
   resizing: { 
     enabled:  (this: Graph, arg: Node<Node.Properties>) => boolean 
    }
  })

enabled

是否开启节点缩放,默认为 false

minWidth

缩放后的最小宽度。

maxWidth

缩放后的最大宽度。

minHeight

缩放后的最小高度。

maxHeight

缩放后的最大高度。

orthogonal

是否显示中间缩放点,默认为 true

restricted

是否限制缩放大小为画布边缘,默认为 false

autoScroll

是否自动滚动画布,仅当开启 Srcoller 并且 restrictedfalse 时有效,默认为 true

preserveAspectRatio

缩放过程中是否保持节点的宽高比例,默认为 false

translating

配置节点的可移动区域,默认值为 false

const graph = new Graph({
  translating: {
    restrict: true,
  }
})

restrict 支持以下两种类型:

  • boolean 设置为 true,节点无法超过画布区域
  • Rectangle.RectangleLike | (arg: CellView) => Rectangle.RectangleLike 指定节点的移动区域

transforming

平移、缩放和旋转节点的基础选项。

const graph = new Graph({
  transforming: {
    clearAll: true,
    clearOnBlankMouseDown: true,
  }
})

支持的选项如下:

export interface Options {
  clearAll?: boolean
  clearOnBlankMouseDown?: boolean
}

clearAll

创建新组件的时候是否清除页面上存在的其他组件,默认为 true

clearOnBlankMouseDown

点击空白区域的时候是否清除组件,默认为 true

embedding

通过embedding可以将一个节点拖动到另一个节点中,使其成为另一节点的子节点,默认禁用。

支持的选项如下:

export interface Embedding {
  enabled?: boolean
  findParent?:
    | 'bbox'
    | 'center'
    | 'topLeft'
    | 'topRight'
    | 'bottomLeft'
    | 'bottomRight'
    | ((this: Graph, args: { node: Node; view: NodeView }) => Cell[])
  frontOnly?: boolean
  validate: (
    this: Graph,
    args: {
      child: Node
      parent: Node
      childView: CellView
      parentView: CellView
    },
  ) => boolean
}

enabled

是否允许节点之间嵌套,默认值为 false

findParent

在节点被移动时通过 findParent 指定的方法返回父节点。默认值为 bbox

frontOnly

如果 frontOnlytrue,则只能嵌入显示在最前面的节点,默认值为 true

validate

validate 为判断节点能否被嵌入父节点的函数,默认返回 true

connecting

配置全局的连线规则,支持的选项如下:

export interface Connecting {
  snap: boolean | { radius: number }
  dangling:
    | boolean
    | ((
        this: Graph,
        args: {
          edge: Edge
          sourceCell?: Cell | null
          targetCell?: Cell | null
          sourcePort?: string
          targetPort?: string
        },
      ) => boolean)
  multi:
    | boolean
    | ((
        this: Graph,
        args: {
          edge: Edge
          sourceCell?: Cell | null
          targetCell?: Cell | null
          sourcePort?: string
          targetPort?: string
        },
      ) => boolean)
  highlight: boolean
  anchor: NodeAnchorOptions
  sourceAnchor?: NodeAnchorOptions
  targetAnchor?: NodeAnchorOptions
  edgeAnchor: EdgeAnchorOptions
  sourceEdgeAnchor?: EdgeAnchorOptions
  targetEdgeAnchor?: EdgeAnchorOptions
  connectionPoint: ConnectionPointOptions
  sourceConnectionPoint?: ConnectionPointOptions
  targetConnectionPoint?: ConnectionPointOptions
  router: string | Router.NativeItem | Router.ManaualItem
  connector: string | Connector.NativeItem | Connector.ManaualItem
  strategy?:
    | string
    | ConnectionStrategy.NativeItem
    | ConnectionPoint.ManaualItem
    | null
  validateMagnet?: (
    this: Graph,
    args: {
      cell: Cell
      view: CellView
      magnet: Element
      e: JQuery.MouseDownEvent
    },
  ) => boolean
  createEdge?: (
    this: Graph,
    args: {
      sourceCell: Cell
      sourceView: CellView
      sourceMagnet: Element
    },
  ) => Nilable<Edge> | void
  validateEdge?: (
    this: Graph,
    args: {
      edge: Edge
      type: Edge.TerminalType
      previous: Edge.TerminalData
    },
  ) => boolean
  validateConnection: (
    this: Graph,
    args: {
      type: Edge.TerminalType
      edge?: Edge | null
      edgeView?: EdgeView
      sourceCell?: Cell | null
      sourceView?: CellView | null
      sourceMagnet?: Element | null
      targetCell?: Cell | null
      targetView?: CellView | null
      targetMagnet?: Element | null
    },
  ) => boolean
}

snap

snap 设置为 true 时连线的过程中距离节点或者连接桩 50px 时会触发自动吸附,可以通过配置 radius 属性自定义触发吸附的距离。当 snap 设置为 false 时不会触发自动吸附。默认值为 false

const graph = new Graph({
  connecting: {
    snap: true,
  }
})
// 等价于
const graph = new Graph({
  connecting: {
    snap: {
      radius: 50,
    },
  }
})

dangling

画布上的任意一点是否作为边的起点和终点。默认值值为 true,如果设置为 false, 边的起点或者终点只能是节点或者连接桩。

multi

highlight

拖动边时,是否高亮显示所有可用的连接桩或节点,默认值为 false

anchor

当连接到节点时,通过 anchor 来指定被连接的节点的锚点,默认值为 center

sourceAnchor

当连接到节点时,通过 sourceAnchor 来指定源节点的锚点。

targetAnchor

当连接到节点时,通过 targetAnchor 来指定目标节点的锚点。

edgeAnchor

当连接到边时,通过 edgeAnchor 来指定被连接的边的锚点,默认值为 ratio

sourceEdgeAnchor

当连接到边时,通过 sourceEdgeAnchor 来指定源边的锚点。

targetEdgeAnchor

当连接到边时,通过 targetEdgeAnchor 来指定目标边的锚点。

connectionPoint

指定连接点,默认值为 boundary

sourceConnectionPoint

连接源的连接点。

targetConnectionPoint

连接目标的连接点。

router

路由将边的路径点 vertices 做进一步转换处理,并在必要时添加额外的点,然后返回处理后的点,默认值为 normal

connector

连接器将起点、路由返回的点、终点加工为 元素的 d 属性,决定了边渲染到画布后的样式,默认值为 normal

validateMagnet

点击 magnet 时 根据 validateMagnet 返回值来判断是否新增边

createEdge

连接的过程中创建新的边

validateEdge

当停止拖动边的时候根据 validateEdge 返回值来判断边是否生效,如果返回 false, 该边会被清除。

validateConnection

判断连接是否有效,如果返回 false ,连接无效。

highlighting

可以通过 highlighting 选项来指定触发某种交互时的高亮样式,如:

new Graph({
  highlighting: {
    // 当链接桩可以被链接时,在链接桩外围渲染一个 2px 宽的红色矩形框
    magnetAvailable: {
      name: 'stroke',
      args: {
        padding: 4,
        attrs: {
          'stroke-width': 2,
          stroke: 'red',
        }
      },
    },
  },
})

支持的 highlighting 配置项有:

  • 'default' 默认高亮选项,当以下几种高亮配置缺省时被使用。
  • 'embedding' 拖动节点进行嵌入操作过程中,节点可以被嵌入时被使用。
  • 'nodeAvailable' 连线过程中,节点可以被链接时被使用。
  • 'magnetAvailable' 连线过程中,链接桩可以被链接时被使用。
  • 'magnetAdsorbed' 连线过程中,自动吸附到链接桩时被使用。

另外,也可以直接使用在 cellView.highlight(...) 方法中,用来高亮指定的元素。

cellView.highlight(elem, { 
  highlighter: {
    name: 'stroke',
    args: {
      padding: 4,
      attrs: {
        'stroke-width': 2,
        stroke: 'red',
      }
    },
  },
})

interacting

定制节点和边的交互行为,支持以下三种类型:

  • boolean 节点或边是否可交互
  • InteractionMap 节点或边的交互细节,支持以下属性:

    • 'nodeMovable' 节点是否可以被移动。
    • 'magnetConnectable' 当在具有 'magnet' 属性的元素上按下鼠标开始拖动时,是否触发连线交互。
    • 'edgeMovable' 边是否可以被移动。
    • 'edgeLabelMovable' 边的标签是否可以被移动。
    • 'arrowheadMovable' 边的起始/终止箭头是否可以被移动。
    • 'vertexMovable' 边的路径点是否可以被移动。
    • 'vertexAddable' 是否可以添加边的路径点。
    • 'vertexDeletable' 边的路径点是否可以被删除。
  • (this: Graph, cellView: CellView) => InteractionMap | boolean
const graph = new Graph({
  container: this.container,
  width: 800,
  height: 1400,
  grid: 10,
  interacting: function (cellView: CellView) {
    if (cellView.cell.getProp('customLinkInteractions')) {
      return { vertexAdd: false }
    }
    return true
  },
})

sorting

节点和边视图的排序方式。

原生 SVG 不支持 z-index 样式,所以我们在 x6 中通过代码的形式来支持节点和边的层级设置。创建节点和边时,可以通过 zIndex 选项来设置节点和边的层级;也可以拿到节点/边的实例后,通过 cell.setZIndex(z)cell.toFront()cell.toBack() 等方法来修改层级。

支持以下三种取值:

  • 'none' 时,不进行排序,节点和边的 zIndex 选项失效。
  • 'exact'zIndex 从低到高渲染,当 zIndex 相同时按照添加顺序渲染。
  • 'approx'zIndex 从低到高渲染,当 zIndex 相同时渲染顺序不确定,但渲染效率更高。

async

是否是异步渲染的画布。异步渲染不会阻塞 UI,对需要添加大量节点和边时的性能提升非常明显。但需要注意的是,一些同步操作可能会出现意外结果,比如获取某个节点的视图、获取节点/边的包围盒等,因为这些同步操作触发时异步渲染可能并没有完成,此时只能通过监听 render:done 事件来确保所有变更都已经生效,然后在事件回调中进行这些操作。

frozen

异步渲染的画布是否处于冻结状态,处于冻结状态的画布不会立即响应画布中节点和边的变更,直到调用 unfreeze(...) 方法来解除冻结并重新渲染画布。

const graph = new Graph({
  container: this.container,
  async: true,
  frozen: true,
})

// add many nodes and edges

graph.unfreeze()

checkView

(
  this: Graph,
  args: {
    view: CellView
    unmounted: boolean
  },
) => boolean

返回指定的视图是否应该渲染到 DOM 中。

magnetThreshold

鼠标移动多少次后才触发连线,或者设置为 'onleave' 时表示鼠标移出元素时才触发连线,默认为 0

moveThreshold

触发 'mousemove' 事件之前,允许鼠标移动的次数,默认为 0

clickThreshold

当鼠标移动次数超过指定的数字时,将不触发鼠标点击事件,默认为 0

preventDefaultContextMenu

是否禁用画布的默认右键,默认为 true

preventDefaultBlankAction

在画布空白位置响应鼠标事件时,是否禁用鼠标默认行为,默认为 true

guard

(e: JQuery.TriggeredEvent, view?: CellView | null) => boolean

是否应该忽略某个鼠标事件,返回 true 时忽略指定的鼠标事件,否则不忽略。

allowRubberband

(e: JQuery.MouseDownEvent) => boolean

返回是否响应框选事件,默认为 () => true

allowPanning

(e: JQuery.MouseDownEvent) => boolean

返回是否响应画布平移事件,默认为 () => true

getCellView

(this: Graph, cell: Cell) => null | undefined | typeof CellView | (new (...args: any[]) => CellView)

获取节点/边的视图类,默认为 () => null

createCellView

(this: Graph, cell: Cell) => CellView | null | undefined

创建节点/边的视图,默认自动根据节点和边的 view 选项创建对应的视图。

getHTMLComponent

(this: Graph, node: HTML) => HTMLElement | string | null | undefined

获取 HTML 节点的 HTML 元素,默认根据节点的 html 选项返回对应的 HTML 元素。更多细节请参考使用 HTML 节点教程

const graph = new Graph({
  getHTMLComponent(node) {
    const data = node.getData()
    if (data.flag) {
      return document.createElement('div')
    }
    return document.createElement('p')
  }
})

onPortRendered

(
  this: Graph, 
  args: {
    node: Node
    port: Port
    container: Element
    selectors?: Markup.Selectors
    labelContainer: Element
    labelSelectors?: Markup.Selectors
    contentContainer: Element
    contentSelectors?: Markup.Selectors
  },
) => void

当某个链接桩渲染完成时触发的回调。

args 参数

名称类型非空描述
nodeNode节点实例。
portPort链接桩选项。
containerElement链接桩的容器元素。
selectorsMarkup.Selectors链接桩 Markup 渲染后的选择器键值对。
labelContainerElement链接桩标签的容器元素。
labelSelectorsMarkup.Selectors链接桩标签 Markup 渲染后的选择器键值对。
contentContainerElement链接桩内容的容器元素。
contentSelectorsMarkup.Selectors链接桩内容 Markup 渲染后的选择器键值对。

使用

例如,我们可以渲染一个 React 类型的链接桩。

const graph = new Graph({
  container: this.container,
  onPortRendered(args) {
    const selectors = args.contentSelectors
    const container = selectors && selectors.foContent
    if (container) {
      ReactDOM.render(
        <Tooltip title="port">
          <div className="my-port" />
        </Tooltip>,
        container,
      )
    }
  },
})

onEdgeLabelRendered

(
  this: Graph, 
  args: {
    edge: Edge
    label: Edge.Label
    container: Element
    selectors: Markup.Selectors
  },
) => void

当边的文本标签渲染完成时触发的回调。

args 参数

名称类型非空描述
edgeEdge边实例。
labelEdge.Label文本标签选项。
containerElement文本标签容器。
selectorsMarkup.Selectors文本标签 Markup 渲染后的选择器键值对。

使用

例如,我们可以在标签上渲染任何想要的元素。

const graph = new Graph({
  container: this.container,
  onEdgeLabelRendered(args) {
    const { label, container, selectors } = args
    const data = label.data
    
    if (data) {
      // 在 Label 容器中渲染一个 foreignObject 来承载 HTML 元素和 React 组件
      const content = this.appendForeignObject(container)

      if (data === 1) {
        // 渲染一个 Div 元素
        const txt = document.createTextNode('text node')
        content.style.border = '1px solid #f0f0f0'
        content.style.borderRadius = '4px'
        content.appendChild(txt)
      } else if (data === 2) {
        // 渲染一个 HTML 按钮
        const btn = document.createElement('button')
        btn.appendChild(document.createTextNode('HTML Button'))
        btn.style.height = '30px'
        btn.style.lineHeight = '1'
        btn.addEventListener('click', () => {
          alert('clicked')
        })
        content.appendChild(btn)
      } else if (data === 3) {
        // 渲染一个 Atnd 的按钮
        ReactDOM.render(<Button size="small">Antd Button</Button>, content)
      }
    }
  },
})

我们也可以在定义 Label 的 Markup 时添加 <foreignObject> 元素来支持 HTML 和 React 的渲染能力。

const graph = new Graph({
  container: this.container,
  onEdgeLabelRendered: (args) => {
    const { selectors } = args
    const content = selectors.foContent as HTMLDivElement

    if (content) {
      content.style.display = 'flex'
      content.style.alignItems = 'center'
      content.style.justifyContent = 'center'
      ReactDOM.render(<Button size="small">Antd Button</Button>, content)
    }
  },
})

onToolItemCreated

(
  this: Graph, 
  args: {
    name: string
    cell: Cell
    view: CellView
    tool: View
  },
) => void

当工具项渲染完成时触发的回调。

args 参数

名称类型非空描述
cellCell节点/边实例。
viewCellView节点/边视图。
namestring工具项名称。
toolView工具视图。

使用

例如,我们为 vertices 工具设置间隔填充效果。

const graph = new Graph({
  container: this.container,
  grid: true,
  onToolItemCreated({ name, cell, tool }) {
    if (name === 'vertices' && cell === edge2) {
      const options = (tool as any).options
      if (options && options.index % 2 === 1) {
        tool.setAttrs({ fill: 'red' })
      }
    }
  },
})

prototype

模型 Model

isNode(...)

isNode(cell: Cell): cell is Node

返回指定的 Cell 是否是节点。

参数

名称类型必选默认值描述
cellCell指定的 Cell。

isEdge(...)

isNode(cell: Cell): cell is Edge

返回指定的 Cell 是否是边。

参数

名称类型必选默认值描述
cellCell指定的 Cell。

createNode(...)

createNode(metadata: Node.Metadata): Node

创建节点。

参数

名称类型必选默认值描述
metadataNode.Metadata节点元数据

addNode(...)

addNode(metadata: Node.Metadata, options?: AddOptions): Node
addNode(node: Node, options?: AddOptions): Node

添加节点到画布,返回添加的节点。

参数

名称类型必选默认值描述
nodeNode.Metadata | Node节点元数据节点实例
options.silentbooleanfalsetrue 时不触发 'node:added''cell:added' 事件和画布重绘。
options.sortbooleantrue是否按照 zIndex 排序。
options...othersobject其他自定义键值对,可以在事件回调中使用。

removeNode(...)

removeNode(nodeId: string, options?: RemoveOptions): Node | null
removeNode(node: Node, options?: RemoveOptions): Node | null

删除节点,返回删除的节点。

参数

名称类型必选默认值描述
nodestring | Node节点 ID 或节点实例
options.silentbooleanfalsetrue 时不触发 'node:removed''cell:removed' 事件和画布重绘。
options...othersobject其他自定义键值对,可以在事件回调中使用。

createEdge(...)

createNode(metadata: Edge.Metadata): Edge

创建边。

参数

名称类型必选默认值描述
metadataEdge.Metadata节点元数据

addEdge(...)

addEdge(metadata: Edge.Metadata, options?: AddOptions): Edge
addEdge(edge:Edge, options?: AddOptions): Edge

添加边到画布,返回添加的边。

参数

名称类型必选默认值描述
edgeEdge.Metadata | Edge边元数据边实例
options.silentbooleanfalsetrue 时不触发 'edge:added''cell:added' 事件和画布重绘。
options.sortbooleantrue是否按照 zIndex 排序。
options...othersobject其他自定义键值对,可以在事件回调中使用。

removeEdge(...)

removeEdge(edgeId: string, options?: RemoveOptions): Edge | null
removeEdge(edge: Edge, options?: RemoveOptions): Edge | null

删除边,返回删除的边。

参数

名称类型必选默认值描述
edgestring | Edge边 ID 或边实例
options.silentbooleanfalsetrue 时不触发 'edge:removed''cell:removed' 事件和画布重绘。
options...othersobject其他自定义键值对,可以在事件回调中使用。

addCell(...)

addCell(cell: Cell | Cell[], options?: AddOptions): this

添加节点或边到画布。

参数

名称类型必选默认值描述
cellCell | Cell[]节点实例边实例,支持传入数组同时添加多个节点或边。
options.silentbooleanfalsetrue 时不触发 'cell:added''node:added''edge:added' 事件和画布重绘。
options.sortbooleantrue是否按照 zIndex 排序。
options...othersobject其他自定义键值对,可以在事件回调中使用。

removeCell(...)

removeCell(cellId: string, options?: RemoveOptions): Cell | null
removeCell(cell: Cell, options?: RemoveOptions): Cell | null

删除节点或边,返回删除的节点或边。

参数

名称类型必选默认值描述
cellstring | Cell节点/边 ID 或节点/边的实例。
options.silentbooleanfalsetrue 时不触发 'cell:removed''node:removed''edge:removed' 事件和画布重绘。
options...othersobject其他自定义键值对,可以在事件回调中使用。

removeCells(...)

removeCells(cells: (Cell | string)[], options?: RemoveOptions): Cell[]

删除多个节点/边,返回删除的节点或边的数组。

参数

名称类型必选默认值描述
cell(string | Cell)[]节点/边 ID 或节点/边数组。
options.silentbooleanfalsetrue 时不触发 'cell:removed''node:removed''edge:removed' 事件和画布重绘。
options...othersobject其他自定义键值对,可以在事件回调中使用。

removeConnectedEdges(...)

removeConnectedEdges(cell: Cell | string, options?: RemoveOptions): Edge[]

删除连接到节点/边的边,返回被删除边的数组。

参数

名称类型必选默认值描述
cellstring | Cell节点/边 ID 或节点/边。
options.silentbooleanfalsetrue 时不触发 'cell:removed''edge:removed' 事件和画布重绘。
options...othersobject其他自定义键值对,可以在事件回调中使用。

disconnectConnectedEdges(...)

disconnectConnectedEdges(cell: Cell | string, options?: Edge.SetOptions): this

将链接到节点/边的边的起点和终点设置为原点 {x: 0, y: 0},即断开连接。

参数

名称类型必选默认值描述
cellstring | Cell节点/边 ID 或节点/边。
options.silentbooleanfalsetrue 时不触发 'edge:change:source''edge:change:target' 事件和画布重绘。
options...othersobject其他自定义键值对,可以在事件回调中使用。

clearCells(...)

clearCells(options?: SetOptions): this

清空画布。

参数

名称类型必选默认值描述
options.silentbooleanfalsetrue 时不触发 'cell:removed''node:removed''edge:removed' 事件和画布重绘。
options...othersobject其他自定义键值对,可以在事件回调中使用。

resetCells(...)

resetCells(cells: Cell[], options?: SetOptions): this

清空画布并添加用指定的节点/边。

参数

名称类型必选默认值描述
cellCell[]节点/边数组。
options.silentbooleanfalsetrue 时不触发 'cell:added''node:added''edge:added''cell:removed''node:removed''edge:removed' 事件和画布重绘。
options...othersobject其他自定义键值对,可以在事件回调中使用。

hasCell(...)

hasCell(cellId: string): boolean
hasCell(cell: Cell): boolean

返回画布中是否包含指定的节点/边。

参数

名称类型必选默认值描述
cellstring | Cell节点/边 ID 或节点/边。

getCell(...)

getCell<T extends Cell = Cell>(id: string): T

根据节点/边的 ID 获取节点/边。

参数

名称类型必选默认值描述
cellstring节点/边的 ID。

getCells()

getCells(): Cell[]

返回画布中所有节点和边。

getCellCount()

getCellCount(): number

返回画布中所有节点和边的数量。

getNodes()

getNodes(): Node[]

返回画布中所有节点。

getEdges()

getEdges(): Edge[]

返回画布中所有边。

getOutgoingEdges(...)

getOutgoingEdges(cell: Cell | string): Edge[] | null

获取连接到节点/边的输出边,即边的起点为指定节点/边的边。

参数

名称类型必选默认值描述
cellstring | Cell节点/边 ID 或节点/边。

getIncomingEdges(...)

getIncomingEdges(cell: Cell | string): Edge[] | null

获取连接到节点/边的输入边,即边的终点为指定节点/边的边。

参数

名称类型必选默认值描述
cellstring | Cell节点/边 ID 或节点/边。

getConnectedEdges(...)

getConnectedEdges(cell: Cell | string, options?: GetConnectedEdgesOptions): Edge[]

获取与节点/边相连接的边。

参数

名称类型必选默认值描述
cellstring | Cell节点/边 ID 或节点/边。
options.incomingboolean-是否包含输入边,默认返回所有输入和输出边,incomingoutgoing 两个选项中,当 incomingtrue 时只返回输入边。
options.outgoingboolean-是否包含输出边,默认返回所有输入和输出边,incomingoutgoing 两个选项中,当 outgoingtrue 时只返回输出边。
options.deepbooleanfalse是否递归获取所有子节点/边,为 true 时将同时返回链接到所有子孙节点/边的边。
options.enclosedbooleanfalse是否包含子孙节点之间相连接的边。
options.indirectbooleanfalse是否包含哪些间接连接的边,即连接到输入或输出边上的边。

使用

const edges = graph.getConnectedEdges(node) // 返回输入和输出边
const edges = graph.getConnectedEdges(node, { incoming: true, outgoing: true }) // 返回输入和输出边

const edges = graph.getConnectedEdges(node, { incoming: true }) // 返回输入边
const edges = graph.getConnectedEdges(node, { incoming: true, outgoing: false }) // 返回输入边

const edges = graph.getConnectedEdges(node, { outgoing: true }) // 返回输出边
const edges = graph.getConnectedEdges(node, { incoming:false, outgoing: true }) // 返回输出边

const edges = graph.getConnectedEdges(node, { deep: true }) // 返回输入和输出边,包含链接到所有子孙节点/边的输入和输出边
const edges = graph.getConnectedEdges(node, { deep: true, incoming: true }) // 返回输入边,包含链接到所有子孙节点/边的输入边
const edges = graph.getConnectedEdges(node, { deep: true, enclosed: true }) // 返回输入和输出边,同时包含子孙节点/边之间相连的边

const edges = graph.getConnectedEdges(node, { indirect: true }) // 返回输入和输出边,包含间接连接的边

getRootNodes()

getRootNodes(): Node[]

获取所有根节点,即没有输入边的节点。

isRootNode(...)

isRootNode(cell: Cell | string): boolean

返回指定的节点是否是跟节点。

参数

名称类型必选默认值描述
cellstring | Cell节点/边 ID 或节点/边。

getLeafNodes()

getLeafNodes(): Node[]

返回所有叶子节点,即没有输出边的节点。

isLeafNode(...)

isLeafNode(cell: Cell | string): boolean

参数

名称类型必选默认值描述
cellstring | Cell节点/边 ID 或节点/边。

getNeighbors(...)

getNeighbors(cell: Cell, options?: GetNeighborsOptions): Cell[]

获取邻居节点。

参数

名称类型必选默认值描述
cellCell节点/边。
options.incomingboolean-是否包含输入侧的邻居节点,默认包含输入和输出侧的节点,incomingoutgoing 两个选项中,当 incomingtrue 时只返回输入侧的节点。
options.outgoingboolean-是否包含输出侧的邻居节点,默认包含输入和输出侧的节点,incomingoutgoing 两个选项中,当 outgoingtrue 时只返回输出侧的节点。
options.deepbooleanfalse是否递归获取所有子节点/边,为 true 时将同时返回所有子孙节点/边的邻居节点。
options.indirectbooleanfalse是否包含哪些间接连接的邻居节点,即中间包含多条边(边与边连接)的邻居。

isNeighbor(...)

isNeighbor(cell1: Cell, cell2: Cell, options?: GetNeighborsOptions): boolean

返回 cell2 是否是 cell1 的邻居, 其中 options 选项与 getNeighbors(...) 方法的选项一致。

getPredecessors(...)

getPredecessors(cell: Cell, options?: GetPredecessorsOptions): Cell[]

返回节点的前序节点,即从根节点开始连接到指定节点的节点。

参数

名称类型必选默认值描述
cellCell节点/边。
options.breadthFirstbooleanfalse是否使用广度优先搜索算法,默认使用深度优先搜索算法。
options.deepbooleanfalse是否递归获取所有子节点/边,为 true 时将同时返回所有子孙节点/边的前序节点。
options.distancenumber | number[] | ((distance: number) => boolean)-距获取指定距离的前序节点,节点和节点之间相隔的边的数量为 1 个距离单位。

isPredecessor(...)

isPredecessor(cell1: Cell, cell2: Cell, options?: GetPredecessorsOptions): boolean

返回 cell2 是否是 cell1 的前序节点,其中 options 选项与 getPredecessors(...) 方法的选项一致。

参数

getSuccessors(...)

getSuccessors(cell: Cell, options?: GetPredecessorsOptions): Cell[]

获取所有后续节点,即从指定节点开始连接到叶子节点的节点。其中 options 选项与 getPredecessors(...) 方法的选项一致。

isSuccessor(...)

isSuccessor(cell1: Cell, cell2: Cell, options?: GetPredecessorsOptions): boolean

返回 cell2 是否是 cell1 的后续节点,其中 options 选项与 getPredecessors(...) 方法的选项一致。

getCommonAncestor(...)

getCommonAncestor(...cells: {Cell | Cell[])[]): Cell | null

获取指定节点的共同祖先节点。

getSubGraph(...)

getSubGraph(cells: Cell[], options?: GetSubgraphOptions): Cell[]

返回指定节点和边构成的子图。通过遍历指定的 cells 数组,当遇到边时,同时包含边的起始和终止节点;当遇到节点时,如果与节点相连的边的两端的节点都在 cells 数组中,则同时包含该条边。

参数

名称类型必选默认值描述
cellsCell[]节点/边数组。
options.deepbooleanfalse是否递归获取所有子节点/边。

cloneCells(...)

cloneCells(cells: Cell[]): { [oldCellId: string]: Cell }

克隆,返回旧节点/边 ID 和克隆后节点/边的键值对。

cloneSubGraph(...)

cloneSubGraph(cells: Cell[], options?: GetSubgraphOptions): { [oldCellId: string]: Cell }

获取子图并克隆。其中 options 选项与 getSubGraph(...) 方法的选项一致。

getNodesFromPoint(...)

getNodesFromPoint(x: number, y: number): Node[]
getNodesFromPoint(p: Point.PointLike): Node[]

返回指定位置的节点,即返回节点的矩形区域包含了指定点的节点。

getNodesInArea(...)

getNodesInArea(
  x: number,
  y: number,
  w: number,
  h: number,
  options?: Model.GetCellsInAreaOptions,
): Node[]
getNodesInArea(
  rect: Rectangle.RectangleLike,
  options?: Model.GetCellsInAreaOptions,
): Node[]

返回指定矩形区域的节点,当 options.stricttrue 时,要求节点的矩形区域完全包含指定的矩形,否则只需要相交即可。

getNodesUnderNode(...)

getNodesUnderNode(
  node: Node,
  options?: {
    by?: 'bbox' | Rectangle.KeyPoint
  },
): Node[]

返回与指定节点位置的节点,通过 options.by 选项来指定获取方式,包含:

  • nullbbox:返回与指定的节点矩形区域相交的节点
  • Rectangle.KeyPoint:返回包含矩形的某个关键点的节点,其中 Rectangle.KeyPoint 的取值为:

    • "center"
    • "origin"
    • "corner"
    • "topLeft"
    • "topCenter"
    • "topRight"
    • "bottomLeft"
    • "bottomCenter"
    • "bottomRight"
    • "leftMiddle"
    • "rightMiddle"

searchCell(...)

searchCell(cell: Cell, iterator: SearchIterator, options?: SearchOptions): this

从指定的节点/边开始进行遍历。

参数

名称类型必选默认值描述
cellCell节点/边。
iterator(cell: Cell, distance: number) => any遍历方法。
options.breadthFirstbooleanfalse是否使用广度优先搜索算法,默认使用深度优先搜索算法。
options.incomingboolean-是否遍历输入侧的邻居节点,默认遍历输入和输出侧的节点,incomingoutgoing 两个选项中,当 incomingtrue 时只遍历输入侧的节点。
options.outgoingboolean-是否遍历输出侧的邻居节点,默认遍历输入和输出侧的节点,incomingoutgoing 两个选项中,当 outgoingtrue 时只遍历输出侧的节点。
options.deepbooleanfalse是否递归遍历所有子节点/边,为 true 时将同时遍历所有子孙节点/边的邻居节点。
options.indirectbooleanfalse是否遍历哪些间接连接的邻居节点,即中间包含多条边(边与边连接)的邻居。

getShortestPath(...)

getShortestPath(
  source: Cell | string,
  target: Cell | string,
  options?: GetShortestPathOptions,
): string[]

获取节点之间的最短路径,返回最短路径上的节点 ID。

参数

名称类型必选默认值描述
sourceCell | string起始节点/边。
sourceCell | string终止节点/边。
options.directedbooleanfalse是否考虑方向性,为 true 时需要路径沿开始节点到终止节点的方向。
options.weight(u: string, v: string) => number(u, v) => 1距离权重算法,uv 为相邻的两个节点,默认距离为 1

getAllCellsBBox(...)

getAllCellsBBox(): Rectangle | null

返回画布上所有节点和边的矩形区域。

getCellsBBox(...)

getCellsBBox(cells: Cell[], options?: Cell.GetCellsBBoxOptions): Rectangle | null

返回指定节点和边构成的矩形区域。

参数

名称类型必选默认值描述
cellsCell[]节点和边数组。
options.deepbooleanfalse是否包含所有子孙节点和边。

toJSON(...)

toJSON(options?: ToJSONOptions): object

导出图中的节点和边,返回一个具有 { cells: [] } 结构的对象,其中 cells 数组按渲染顺序保存节点和边。

参数

名称类型必选默认值描述
options.deepdifffalse是否导出节点和边的差异数据(与节点和边的默认配置不同的部分)。

parseJSON(...)

将指定的数据转换为节点和边。

支持节点/边元数据数组,按照数组顺序返回创建的节点和边。

parseJSON(cells: (Node.Metadata | Edge.Metadata)[]): (Node | Edge)[]

或者提供一个包含 cellsnodesedges 的对象,按照 [...cells, ...nodes, ...edges] 顺序创建节点和边并返回。

parseJSON({
  cells?: (Node.Metadata | Edge.Metadata)[],
  nodes?: Node.Metadata[],
  edges?: Edge.Metadata[],
}): (Node | Edge)[]

fromJSON(...)

按照指定的 JSON 数据渲染节点和边。

支持节点/边元数据数组,按照数组顺序渲染节点和边。

fromJSON(data: (Node.Metadata | Edge.Metadata)[], options?: FromJSONOptions): this

或者提供一个包含 cellsnodesedges 的对象,按照 [...cells, ...nodes, ...edges] 顺序渲染。

fromJSON(
  data: {
    cells?: (Node.Metadata | Edge.Metadata)[],
    nodes?: Node.Metadata[],
    edges?: Edge.Metadata[],
  }, 
  options?: FromJSONOptions,
): this

options.slienttrue 时,不触发 cell:addednode:addededge:added 事件和画布重绘。

视图 View

isAsync()

isAsync(): boolean

返回画布是否是异步渲染模式。异步渲染不会阻塞 UI,对需要添加大量节点和边时的性能提升非常明显,异步画布的使用细节请参考 async 选项。

isFrozen()

isFrozen(): boolean

返回异步画布是否处于冻结状态。处于冻结状态的画布不会立即响应画布中节点和边的变更,直到调用 unfreeze(...) 方法来解除冻结并重新渲染画布。

freeze(...)

freeze(options?: FreezeOptions): this

冻结异步画布,处于冻结状态的画布不会立即响应画布中节点和边的变更,直到调用 unfreeze(...) 方法来解除冻结并重新渲染画布。

参数

名称类型必选默认值描述
options.keystring-冻结状态的名称,当指定名称与当前冻结状态的名称不一致时,则不能用指定的名称冻结画布。

unfreeze(...)

unfreeze(options?: UnfreezeOptions): this

解除异步画布的冻结状态,并触发画布重新渲染,使画布中的变更生效。

参数

名称类型必选默认值描述
options.keystring-冻结状态的名称。
options.batchSizenumber1000每次异步进程中处理的节点和边视图的数量。
options.viewport(this: Graph, args: { view: CellView; unmounted: boolean }) => boolean-返回指定的视图是否应该渲染到 DOM 中。
options.before(this: Graph, graph: Graph) => void-开始异步更新前调用的函数。
options.after(this: Graph, graph: Graph) => void-完成异步更新时调用的函数。
options.progress(this: Graph, args: { done: boolean; processed: number; total: number }) => void-每次异步进程的进度回调函数。

findView(...)

findView(ref: Cell | JQuery | Element): CellView | null

根据节点/边或元素查找对应的视图。

findViewByCell(...)

findViewByCell(cellId: string | number): CellView | null
findViewByCell(cell: Cell | null): CellView | null

根据节点/边 ID 或实例查找对应的视图。

findViewByElem(...)

findViewByElem(elem: string | JQuery | Element | undefined | null): CellView | null

根据元素选择器或元素对象查找对应的视图。

findViewsFromPoint(...)

findViewsFromPoint(x: number, y: number): CellView[]
findViewsFromPoint(p: Point.PointLike): CellView[]

返回节点/边的包围盒包含指定点的视图。

findViewsInArea(...)

findViewsInArea(
  x: number,
  y: number,
  width: number,
  height: number,
  options?: FindViewsInAreaOptions,
): CellView[]
findViewsInArea(
  rect: Rectangle.RectangleLike,
  options?: FindViewsInAreaOptions,
): CellView[]

返回节点/边的包围盒与指定矩形相交的视图,当 options.stricttrue 时需要节点/边的包围盒完全包含指定的矩形。

findViews(...)

findViews(ref: Point.PointLike | Rectangle.RectangleLike): CellView[]

返回节点/边的包围盒包含指定的点或与指定的矩形相交的视图。

isViewMounted(...)

isViewMounted(view: CellView): boolean

返回指定的视图是否已经渲染到 DOM 中。

getMountedViews()

getMountedViews(): View[]

返回已经渲染到 DOM 的视图。

getUnmountedViews()

getUnmountedViews(): View[]

返回还没有渲染到 DOM 的视图。

事务 Batch

事务指包含多个变更的操作的集合,

startBatch(...)

startBatch(name: string, data?: KeyValue): this

开始一个指定名称事务。开始和结束事务必须成对使用,一个事务结束前的所有变更都归属于该事务。

参数

名称类型必选默认值描述
namestring事务名称。
dataKeyValue额外的数据,供事件回调函数使用。

stopBatch(...)

stopBatch(name: string, data?: KeyValue): this

结束指定名称事务。事开始和结束事务必须成对使用,一个事务结束前的所有变更都归属于该事务。

参数

名称类型必选默认值描述
namestring事务名称。
dataKeyValue额外的数据,供事件回调函数使用。

用法

graph.startBatch('rename')

rect.prop('zIndex', 10)
rect.attr('label/text', 'hello')
rect.attr('label/fill', '#ff0000')

graph.stopBatch('rename')

batchUpdate(...)

batchUpdate<T>(name: string, execute: () => T, data?: KeyValue): T

执行一个成对的事务。

参数

名称类型必选默认值描述
namestring事务名称。
execute() => T事务执行的函数。
dataKeyValue额外的数据,供事件回调函数使用。

用法

graph.batchUpdate('rename', () => {
  rect.prop('zIndex', 10)
  rect.attr('label/text', 'hello')
  rect.attr('label/fill', '#ff0000')  
})

变换 Transform

matrix()

matrix(): DOMMatrix

获取画布的变换矩阵。

matrix(mat: DOMMatrix | Dom.MatrixLike | null): this

参数

名称类型必选默认值描述
matDOMMatrix | Dom.MatrixLike | null变换矩阵,参考 DomMatrix

resize(...)

resize(width?: number, height?: number): this

设置容器大小,自动根据是否开启 Scroller 来设置画布或设置 Scroller 的大小。如果需要根据浏览器窗口大小动态调整画布大小,请使用此方法。

参数

名称类型必选默认值描述
widthnumber画布宽度,缺省时宽度保持不变。
heightnumber画布高度,缺省时高度保持不变。

resizeGraph(...)

resizeGraph(width?: number, height?: number): this

设置画布大小。

参数

名称类型必选默认值描述
widthnumber画布宽度,缺省时宽度保持不变。
heightnumber画布高度,缺省时高度保持不变。

resizeScroller(...)

resizeScroller(width?: number, height?: number): this

设置 Scroller 大小,仅在启用 Scroller 后生效。

参数

名称类型必选默认值描述
widthnumber画布宽度,缺省时宽度保持不变。
heightnumber画布高度,缺省时高度保持不变。

scale(...)

scale(): {
  sx: number
  sy: number
}

获取画布的缩放比例。

scale(sx: number, sy?: number, cx?: number, cy?: number): this

设置画布的缩放比例。

参数

名称类型必选默认值描述
sxnumberX 轴方向缩放比例。
synumbersxY 轴方向缩放比例,缺省时使用 sx
cxnumber0缩放中心 x 坐标。
cynumber0缩放中心 y 坐标。

rotate(...)

rotate(): {
  angle: number
  cx?: number
  cy?: number
}

获取画布的旋转角度和旋转中心。

rotate(angle: number, cx?: number, cy?: number): this

旋转画布。

参数

名称类型必选默认值描述
anglenumber旋转角度。
cxnumber-旋转中心 x 坐标,默认使用画布中心。
cynumber-旋转中心 y 坐标,默认使用画布中心。

translate(...)

translate(): {
  tx: number
  ty: number
}

获取画布的平移量。

translate(tx: number, ty: number): this

平移画布。

参数

名称类型必选默认值描述
txnumberX 轴平移量。
tynumberY 轴平移量。

fitToContent(...)

fitToContent(
  gridWidth?: number,
  gridHeight?: number,
  padding?: NumberExt.SideOptions,
  options?: Transform.FitToContentOptions,
): Rectangle
fitToContent(options?: Transform.FitToContentFullOptions): Rectangle

通过平移和重置画布大小,使其适应画布内容,返回画布的矩形区域。

参数

名称类型必选默认值描述
options.gridWidthnumber-使宽度是 gridWidth 的整倍数。
options.gridHeightnumber-使高度是 gridHeight 的整倍数。
options.minWidthnumber-画布最小宽度。
options.minHeightnumber-画布最小高度。
options.maxWidthnumber-画布最大宽度。
options.maxHeightnumber-画布最大高度。
options.paddingnumber | Padding0边距。
options.contentAreaRectangle.RectangleLike-内容区域,默认获取画布内容区域。
options.useCellGeometrybooleanfalse是否使用节点/边的几何信息(Model)计算包围盒,默认使用浏览器 API 获取每个节点和边(View)的包围盒。
options.allowNewOrigin'negative' | 'positive' | 'any'-画布左上角位置选项。

scaleContentToFit(...)

scaleContentToFit(options?: Transform.ScaleContentToFitOptions): this

缩放画布,使内容充满画布视口。

参数

名称类型必选默认值描述
options.paddingnumber-边距。
options.contentAreaRectangle.RectangleLike-内容区域,默认获取画布内容区域。
options.viewportAreaRectangle.RectangleLike-视口区域,默认获取画布视口。
options.scaleGridnumber-修正缩放比例为 scaleGrid 的整倍数。
options.minScalenumber-最小缩放比例。
options.maxScalenumber-最大缩放比例。
options.minScaleXnumber-X 轴方向的最小缩放比例。
options.maxScaleXnumber-X 轴方向的最大缩放比例。
options.minScaleYnumber-Y 轴方向的最小缩放比例。
options.maxScaleYnumber-Y 轴方向的最大缩放比例。
options.preserveAspectRatiobooleanfalse是否保持长宽比。
options.useCellGeometrybooleanfalse是否使用节点/边的几何信息(Model)计算包围盒,默认使用浏览器 API 获取每个节点和边(View)的包围盒。

getContentArea(...)

getContentArea(options?: Transform.GetContentAreaOptions): Rectangle

获取画布内容的矩形区域,使用画布本地坐标表示。

参数

名称类型必选默认值描述
options.useCellGeometrybooleanfalse是否使用节点/边的几何信息(Model)来计算画布内容大小,默认使用浏览器 API 获取每个节点和边(View)的包围盒。

getContentBBox(...)

getContentBBox(options?: Transform.GetContentAreaOptions): Rectangle

获取画布内容的矩形区域,使用画布坐标表示。

参数

名称类型必选默认值描述
options.useCellGeometrybooleanfalse是否使用节点/边的几何信息(Model)来计算画布内容大小,默认使用浏览器 API 获取每个节点和边(View)的包围盒。

坐标系 Coordinate

pageToLocal(...)

pageToLocal(rect: Rectangle.RectangleLike): Rectangle
pageToLocal(x: number, y: number, width: number, height: number): Rectangle
pageToLocal(p: Point.PointLike): Point
pageToLocal(x: number, y: number): Point

将页面坐标转换为画布本地坐标。

画布本地坐标指相对于画布并考虑画布缩放、平移和旋转的坐标。节点和画布鼠标事件回调函数参数中的 xy 就是画布本地坐标。

页面坐标指鼠标事件的 pageXpageY 属性。这两个属性基于文档边缘,考虑页面水平和垂直方向滚动,例如,如果页面向右滚动 200px 并出现了滚动条,这部分在窗口之外,然后鼠标点击距离窗口左边 100px 的位置,pageX 所返回的值将是 300

localToPage(...)

localToPage(rect: Rectangle.RectangleLike): Rectangle
localToPage(x: number, y: number, width: number, height: number): Rectangle
localToPage(p: Point.PointLike): Point
localToPage(x: number, y: number): Point

将画布本地坐标转换为页面坐标。

画布本地坐标指相对于画布并考虑画布缩放、平移和旋转的坐标。节点和画布鼠标事件回调函数参数中的 xy 就是画布本地坐标。

页面坐标指鼠标事件的 pageXpageY 属性。这两个属性基于文档边缘,考虑页面水平和垂直方向滚动,例如,如果页面向右滚动 200px 并出现了滚动条,这部分在窗口之外,然后鼠标点击距离窗口左边 100px 的位置,pageX 所返回的值将是 300

clientToLocal(...)

clientToLocal(rect: Rectangle.RectangleLike): Rectangle
clientToLocal(x: number, y: number, width: number, height: number): Rectangle
clientToLocal(p: Point.PointLike): Point
clientToLocal(x: number, y: number): Point

将页面的客户端坐标转换画布本地坐标。

画布本地坐标指相对于画布并考虑画布缩放、平移和旋转的坐标。节点和画布鼠标事件回调函数参数中的 xy 就是画布本地坐标。

客户端坐标指鼠标事件的 clientXclientY 属性。例如,不论页面是否有水平滚动,当你点击客户端区域的左上角时,鼠标事件的 clientX 值都将为 0

localToClient(...)

localToClient(rect: Rectangle.RectangleLike): Rectangle
localToClient(x: number, y: number, width: number, height: number): Rectangle
localToClient(p: Point.PointLike): Point
localToClient(x: number, y: number): Point

将画布本地坐标转换为页面的客户端坐标。

画布本地坐标指相对于画布并考虑画布缩放、平移和旋转的坐标。节点和画布鼠标事件回调函数参数中的 xy 就是画布本地坐标。

客户端坐标指鼠标事件的 clientXclientY 属性。例如,不论页面是否有水平滚动,当你点击客户端区域的左上角时,鼠标事件的 clientX 值都将为 0

localToGraph(...)

localToGraph(rect: Rectangle.RectangleLike): Rectangle
localToGraph(x: number, y: number, width: number, height: number): Rectangle
localToGraphPoint(p: Point.PointLike): Point
localToGraphPoint(x: number, y: number): Point

将画布本地坐标转换为画布坐标。

画布本地坐标指相对于画布并考虑画布缩放、平移和旋转的坐标。节点和画布鼠标事件回调函数参数中的 xy 就是画布本地坐标。

画布坐标指相对于画布左上角的坐标,不考虑画布的缩放、平移和旋转。

graphToLocal(...)

graphToLocal(rect: Rectangle.RectangleLike): Rectangle
graphToLocal(x: number, y: number, width: number, height: number): Rectangle
graphToLocal(p: Point.PointLike): Point
graphToLocal(x: number, y: number): Point

将画布坐标转换为画布本地坐标。

画布本地坐标指相对于画布并考虑画布缩放、平移和旋转的坐标。节点和画布鼠标事件回调函数参数中的 xy 就是画布本地坐标。

画布坐标指相对于画布左上角的坐标,不考虑画布的缩放、平移和旋转。

snapToGrid(...)

snapToGrid(p: Point.PointLike): Point
snapToGrid(x: number, y: number): Point

将页面客户端坐标转换为画布本地坐标并对齐到画布网格。

网格 Grid

getGridSize()

getGridSize(): number

获取网格大小。

setGridSize()

setGridSize(gridSize: number): this

设置网格大小。

showGrid()

showGrid(): this

显示网格。

hideGrid()

hideGrid(): this

隐藏网格。

clearGrid()

clearGrid(): this

清除网格。

drawGrid(...)

drawGrid(options?: DrawGridOptions): this

重绘网格。

参数

名称类型必选默认值描述
options.typestring'dot'网格类型。详情请参考这里
options.argsobject-与网格类型对应的网格参数。

背景 Background

drawBackground(...)

drawBackground(options?: Options): this

重绘背景。

参数

名称类型必选默认值描述
options.colorstring-背景颜色。
options.imagestring-背景图片地址。
options.positionstring-背景图片位置。
options.sizestring-背景图片大小。
options.repeatstring-背景图片重复方式。
options.opacitystring-背景图片透明度。

updateBackground()

updateBackground(): this

更新背景。

clearBackground()

clearBackground(): this

清除背景。

剪切板 Clipboard

copy(...)

copy(cells: Cell[], options: CopyOptions = {}): this

复制节点/边。

参数

名称类型必选默认值描述
cellsCell[]被复制的节点/边。
options.deepboolean-是否递归复制所有子节点/边。
options.useLocalStorageboolean-是否将复制的节点/边保存在 localStorage 中。

cut(...)

cut(cells: Cell[], options: CopyOptions = {}): this

剪切节点/边。

参数

名称类型必选默认值描述
cellsCell[]被剪切的节点/边。
options.deepboolean-是否递归复制所有子节点/边。
options.useLocalStorageboolean-是否将复制的节点/边保存在 localStorage 中。

paste(...)

paste(options?: PasteOptions, graph?: Graph): Cell[]

粘贴,返回粘贴到画布的节点/边。

参数

名称类型必选默认值描述
options.useLocalStorageboolean-是否使用 localStorage 中的节点/边。
options.offsetnumber | { dx: number; dy: number }20粘贴到画布的节点/边的偏移量。
options.nodePropsNode.Properties-粘贴到画布的节点的额外属性。
options.edgePropsEdge.Properties-粘贴到画布的边的额外属性。
graphGraphthis粘贴的目标画布,默认粘贴到当前画布。

getCellsInClipboard()

getCellsInClipboard: Cell[]

获取剪切板中的节点/边。

cleanClipboard()

cleanClipboard(): this

清空剪切板。

isClipboardEmpty()

isClipboardEmpty(): boolean

返回剪切板是否为空。

isClipboardEnabled()

isClipboardEnabled(): boolean

返回是否启用了剪切板。

enableClipboard()

enableClipboard(): this

启用剪切板。

disableClipboard()

disableClipboard(): this

禁用剪切板。

toggleClipboard(...)

toggleClipboard(enabled?: boolean): this

切换剪切板的启用状态。

参数

名称类型必选默认值描述
enabledboolean-是否启用剪切板,缺省时切换剪切板的启用状态。

撤销/重做 Redo/Undo

undo(...)

undo(options?: KeyValue): this

撤销。options 将被传递到事件回调中。

undoAndCancel(...)

undoAndCancel(options?: KeyValue): this

撤销,并且不添加到重做队列中,所以这个被撤销的命令不能被重做。options 将被传递到事件回调中。

redo(...)

redo(options?: KeyValue): this

重做。options 将被传递到事件回调中。

canUndo()

canUndo(): boolean

是否可以撤销。

canRedo()

canRedo(): boolean

是否可以重做。

cleanHistory(...)

cleanHistory(options?: KeyValue): this

清空历史状态。options 将被传递到事件回调中。

isHistoryEnabled()

isHistoryEnabled(): boolean

是否启用了历史状态。

enableHistory()

enableHistory(): this

启用历史状态。

disableHistory()

disableHistory(): this

禁用历史状态。

toggleHistory(...)

toggleHistory(enabled?: boolean): this

切换历史的启用状态。

参数

名称类型必选默认值描述
enabledboolean-是否启用历史状态,缺省时切换历史的启用状态。

键盘 Keyboard

bindKey(...)

bindKey(
  keys: string | string[], 
  callback: (e: KeyboardEvent) => void, 
  action?: 'keypress' | 'keydown' | 'keyup',
): this

绑定键盘快捷键,请参考 Mousetrap 的使用文档。

参数

名称类型必选默认值描述
keysstring | string[]快捷键。
callback(e: KeyboardEvent) => void回调函数。
action'keypress' | 'keydown' | 'keyup'-触发时机。

unbindKey(...)

unbindKey(
  keys: string | string[], 
  action?: 'keypress' | 'keydown' | 'keyup',
): this

解绑键盘快捷键,请参考 Mousetrap 的使用文档。

参数

名称类型必选默认值描述
keysstring | string[]快捷键。
action'keypress' | 'keydown' | 'keyup'-触发时机。

isKeyboardEnabled()

isKeyboardEnabled(): boolean

获取是否启用了键盘事件。

enableKeyboard()

enableKeyboard(): this

启用键盘事件。

disableKeyboard()

disableKeyboard(): this

禁用键盘事件。

toggleKeyboard(...)

toggleKeyboard(enabled?: boolean): this

切换键盘事件的启用状态。

参数

名称类型必选默认值描述
enabledboolean-是否启用键盘事件,缺省时切换键盘事件的启用状态。

滚轮 Mousewheel

isMouseWheelEnabled()

isMouseWheelEnabled(): boolean

返回是否启用了鼠标滚轮来缩放画布。

enableMouseWheel()

enableMouseWheel(): this

启用鼠标滚轮缩放画布。