Scroller

5 min read

配置

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
  pageWidth?: number
  pageHeight?: number
  pageVisible?: boolean
  pageBreak?: boolean
  autoResize?: boolean
  resizeOptions?: TransformManager.FitToContentFullOptions | ((this: Scroller, scroller: Scroller) => TransformManager.FitToContentFullOptions)
  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'

padding

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

minVisibleWidth

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

minVisibleHeight

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

pageVisible

是否分页,默认为 false

pageBreak

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

pageWidth

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

pageHeight

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

autoResize

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

autoResizeOptions

自动扩展画布的选项,支持如下选项。

interface {
  minWidth?: number  // 画布最小宽度
  minHeight?: number // 画布最小高度
  maxWidth?: number  // 画布最大宽度
  maxHeight?: number // 画布最大高度
  border?: number    // 距离画布边缘多少位置时触发自动扩展画布,例如设置为 `20` 表示当节点移动到距离画布边缘 `20px` 内时触发自动扩展画布。
}

方法

scrollToPoint(...)

scrollToPoint(x?: number, y?: number, options?: ScrollOptions): this

xy 指定的点(相对于画布)滚动到视口中心,如果只指定了其中一个方向,则只滚动对应的方向。

该方法将尽量滚动画布,使指定的点位于视口中心,这意味着滚动后指定的点不一定位于视口中心,如指定的点位于画布的角落。

参数

名称类型必选默认值描述
xnumber相对一画布的 x 轴坐标。
ynumber相对一画布的 y 轴坐标。
options.animationobjectJQuery 动画选项。

例如

graph.scrollToPoint(100, 200)  // 滚动到 [100, 200]
graph.scrollToPoint(100)       // 滚动到 [100, null]
graph.scrollToPoint(null, 200) // 滚动到 [null, 200]

// 支持动画
graph.scrollToPoint(100, 200,  { animation: { duration: 400 }})
graph.scrollToPoint(100, null, { animation: { duration: 200, easing: 'linear' }})
graph.scrollToPoint(null, 200, { animation: { duration: 600 }})

scrollToContent(...)

scrollToContent(options?: ScrollOptions): this

滚动画布,使画布的内容中心位于画布的视口中心。

该方法将尽量滚动画布,使画布的内容中心位于画布的视口中心,这意味着滚动后内容中心不一定位于视口中心。

参数

参数

名称类型必选默认值描述
options.animationobjectJQuery 动画选项。

例如

graph.scrollToContent()
graph.scrollToContent({ animation: { duration: 600 }})

scrollToCell(...)

scrollToCell(cell: Cell, options?: ScrollOptions): this

滚动画布,使节点/边的中心位于画布的视口中心。

该方法将尽量滚动画布,使节点/边的中心位于视口中心,这意味着滚动后节点/边的中心不一定位于视口中心,如指定的节点/边位于画布的角落。

参数

名称类型必选默认值描述
cellCell节点/边。
options.animationobjectJQuery 动画选项。

transitionToPoint(...)

transitionToPoint(p: Point.PointLike, options?: TransitionOptions): this
transitionToPoint(x: number, y: number, options?: TransitionOptions): this

使用动画平移画布,将画布上指定点(相对于画布的坐标)与视口中心对齐。

参数

名称类型必选默认值描述
xnumber相对于画布的 x 坐标。
ynumber相对于画布的 y 坐标。
options.scalenumber目标缩放比例,设置后同时伴随着缩放动画。
options.durationstring动画持续的时长,如 '500ms''2s'。默认为 '1s'
options.delaystring动画延迟多长时间后开始,默认为 0
options.timingstring插值方法名,默认为 'ease'。支持的方法名参考这里
options.onTransitionEnd(this: Scroller, e: TransitionEvent) => void动画结束时的回调。

例如

// 平移画布,将点 { x: 100, y: 80 } 移动到视口中心
graph.transitionToPoint(100, 80)

// 平移和缩放画布,将点 { x: 100, y: 80 } 移动到视口中心,同时将画布放大 2 倍。
graph.transitionToPoint(100, 80, { scale: 2 })

transitionToRect(...)

transitionToRect(rect: Rectangle.RectangleLike, options?: TransitionToRectOptions): this

使用动画缩放和平移画布,使指定的矩形(相对于画布的坐标)充满视口。

参数

名称类型必选默认值描述
rectRectangle.RectangleLike目标矩形区域。
options.minScalenumber画布的最小缩放比例。
options.maxScalenumber画布的最大缩放比例。
options.scaleGridnumber修正缩放比例为 scaleGrid 的整倍数。
options.centerPoint.PointLike同时将指定的点移动到视口中心。
options.visibilitynumber矩形区域覆盖视口的比例,取值范围 [0, 1],默认为 1,表示完全覆盖。如,取值为 0.8 时表示矩形覆盖 80% 视口区域。
options.durationstring动画持续的时长,如 '500ms''2s'。默认为 '1s'
options.delaystring动画延迟多长时间后开始,默认为 0
options.timingstring插值方法名,默认为 'ease'。支持的方法名参考这里
options.onTransitionEnd(this: Scroller, e: TransitionEvent) => void动画结束时的回调。

例如

graph.transitionToRect({
  x: 100,
  y: 100,
  width: 200,
  height: 200,
}, {
    visibility: 0.9, // 矩形覆盖 90% 视口区域
    maxScale: 3,     // 画布最大缩放比例为 3
})

// 使 cell1, cell2, cell3 三个节点的包围盒 BBox 完全位于视口,并将 cell1 移动到视口中心
const rect = graph.getCellsBBox([cell1, cell2, cell3]);
graph.transitionToRect(rect, {
    duration: '500ms',
    center: cell1.getBBox().center()
});

getScrollbarPosition()

getScrollbarPosition(): {
  left: number
  top: number
}

获取滚动条位置。

setScrollbarPosition(...)

setScrollbarPosition(left?: number, top?: number, options?: ScrollOptions): this

设置滚动条位置。

参数

名称类型必选默认值描述
leftnumber水平滚动条的位置,缺省时表示水平方向不滚动。
topnumber垂直滚动条的位置,缺省时表示垂直方向不滚动。
options.animationobjectJQuery 动画配置。

例如

graph.setScrollbarPosition(100)
graph.setScrollbarPosition(100, null)
graph.setScrollbarPosition(null, 200)
graph.setScrollbarPosition(100, 200)

// 使用动画
graph.setScrollbarPosition(100, null, { animation: { duration: 200, easing: 'linear' }})
graph.setScrollbarPosition(null, 200, { animation: { duration: 600 }})
graph.setScrollbarPosition(100, 200,  { animation: { duration: 400 }})

isPannable()

isPannable(): boolean

返回画布是否可被平移。

enablePanning()

enablePanning(): this

启用画布平移。

disablePanning()

disablePanning(): this

禁用画布平移。

togglePanning()

togglePanning(pannable?: boolean): this

切换或设置画布平移。

enableAutoResize()

enableAutoResize(): this

开启自动扩充/缩小画布

disableAutoResize()

disableAutoResize(): this

关闭自动扩充/缩小画布

update()

update(): this

更新画布

lockScroller()

lockScroller(): this

禁止滚动。

unlockScroller()

unlockScroller(): this

启用滚动。