logoCreated with Sketch.

X6

Scroller

阅读时间约 5 分钟

配置

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 边距。默认根据 minVisibleWidth 和 minVisibleHeight 自动计算得到，保证画布滚动时，在宽度和高度方向至少有 minVisibleWidth 和 minVisibleHeight 大小的画布可见。

minVisibleWidth

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

minVisibleHeight

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

pageVisible

是否分页，默认为 false。

pageBreak

是否显示分页符，默认为 false。

pageWidth

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

pageHeight

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

autoResize

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

autoResizeOptions

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

interface {
  minWidth?: number  // 画布最小宽度
  minHeight?: number // 画布最小高度
  maxWidth?: number  // 画布最大宽度
  maxHeight?: number // 画布最大高度
  border?: number    // 距离画布边缘多少位置时触发自动扩展画布，例如设置为 `20` 表示当节点移动到距离画布边缘 `20px` 内时触发自动扩展画布。
  direction?: ('top' | 'right' | 'bottom' | 'left') | ('top' | 'right' | 'bottom' | 'left')[] // 画布可扩展的方向，默认四个方向都可扩展
}

方法

scrollToPoint(...)

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

将 x 和 y 指定的点（相对于画布）滚动到视口中心，如果只指定了其中一个方向，则只滚动对应的方向。

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

参数

名称类型必选默认值描述
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

关闭自动扩充/缩小画布

lockScroller()

lockScroller(): this

禁止滚动。

unlockScroller()

unlockScroller(): this

启用滚动。