点选/框选 Selection

阅读时间约 6 分钟

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

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()
}

演示

  • 点击选中节点。
  • 启用多选,按住 Ctrl/Command 后点击节点多选。
  • 启用移动,拖动选框移动节点。
  • 启用框选,在画布空白位置按下鼠标左键,拖动选框来框选节点。
  • 启用严格框选模式(strict),观察对框选的影响。
  • 选择与框选配合使用的修饰键,如 alt 键,按住 alt 键并画布空白位置按下鼠标左键,拖动选框来框选节点。
  • 应用自定义样式名(my-selection),选中节点的选框颜色被自定义。
  • 应用自定义过滤器(排除 circle 节点),圆形节点不能被选中。
  • 应用自定义附加内容(显示选中节点个数),选择两个及以上的节点,触发显示自定义内容。

选项

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

className

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

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

multiple

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

multipleSelectionModifiers

修饰键('alt''ctrl''meta''shift'),设置修饰键后需按下修饰键才能触发点选多选。默认值是 ['ctrl', 'meta']

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

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

rubberband

是否启用框选,默认为 false。开启框选时,默认只能框选节点,如果需要自定义框选节点或者边,可以配置 rubberNoderubberEdge 属性。

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

movable

following

在多选情况下,选中的节点是否跟随鼠标实时移动,默认为 true。下图是设置为 false 下的表现:

following

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.shape === 'rect'
    },
  },
})

showNodeSelectionBox

是否显示节点的选择框,默认为 false,建议使用下面的样式定制方法去定制自己的选择框样式。

showEdgeSelectionBox

是否显示边的选择框,默认为 false,建议使用下面的样式定制方法去定制自己的选择框样式。

useCellGeometry

是否使用几何计算的方式计算节点包围盒,默认为 false,如果设置为 trueselectionBox 只会包含节点本身(不会包含连接桩)。

pointerEvents

如果打开 showNodeSelectionBox 时,会在节点上方盖一层元素,导致节点的事件无法响应,此时可以配置 pointerEvents: none 来解决,默认值是 auto

样式定制

上面介绍了通过 className 选项来定制样式,另外也可以通过覆盖以下几个 CSS 样式定义来定制,默认的样式定义参考这里

  • x6-widget-selection
  • x6-widget-selection-rubberband
  • x6-widget-selection-selected
  • x6-widget-selection-box
  • x6-widget-selection-inner
  • x6-widget-selection-content

事件

cell:selected

节点/边被选中时触发。

graph.on('cell:selected', (args: { 
  cell: Cell
  options: Model.SetOptions 
}) => { 
  // code here
})

node:selected

节点被选中时触发。

graph.on('node:selected', (args: { 
  cell: Cell
  node: Node 
  options: Model.SetOptions 
}) => { 
  // code here
})

edge:selected

边被选中时触发。

graph.on('edge:selected', (args: { 
  cell: Cell
  edge: Edge
  options: Model.SetOptions 
}) => { 
  // code here
})

cell:unselected

节点/边被取消选中时触发。

graph.on('cell:unselected', (args: { 
  cell: Cell
  options: Model.SetOptions 
}) => { 
  // code here
})

node:unselected

节点被取消选中时触发。

graph.on('node:unselected', (args: { 
  cell: Cell
  node: Node 
  options: Model.SetOptions 
}) => { 
  // code here
})

edge:unselected

边被取消选中时触发。

graph.on('edge:unselected', (args: { 
  cell: Cell
  edge: Edge
  options: Model.SetOptions 
}) => { 
  // code here
})

selection:changed

选中的节点/边发生改变(增删)时触发。

graph.on('selection:changed', (args: {
  added: Cell[]     // 新增被选中的节点/边
  removed: Cell[]   // 被取消选中的节点/边
  selected: Cell[]  // 被选中的节点/边
  options: Model.SetOptions
}) => {
  // code here
})

API

graph.select(...)

select(cells: Cell | string | (Cell | string)[]): this 

选中指定的节点/边。需要注意的是,该方法不会取消选中当前选中的节点/边,而是将指定的节点/边追加到选区中。如果同时需要取消选中当前选中的节点/边,请使用 resetSelection(...) 方法。

graph.unselect(...)

unselect(cells: Cell | string | (Cell | string)[]): this 

取消选中指定的节点/边。

graph.isSelected(...)

isSelected(cell: Cell | string): boolean

返回指定的节点/边是否被选中。

graph.resetSelection(...)

resetSelection(cells?: Cell | string | (Cell | string)[]): this

先清空选区,然后选中提供的节点/边。

graph.getSelectedCells()

getSelectedCells(): Cell[]

获取选中的节点/边。

graph.cleanSelection()

cleanSelection(): this

清空选区。

graph.isSelectionEmpty()

cleanSelection(): boolean

返回选区是否为空。

graph.isSelectionEnabled()

isSelectionEnabled(): boolean

是否启用选择能力。

graph.enableSelection()

enableSelection(): this

启用选择能力。

graph.disableSelection()

disableSelection(): this

禁用选择能力。

graph.toggleSelection(...)

toggleSelection(enabled?: boolean): this

切换选择的启用状态。

参数

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

graph.isMultipleSelection()

isMultipleSelection(): boolean

是否启用了多选。

graph.enableMultipleSelection()

enableMultipleSelection(): this

启用多选。

graph.disableMultipleSelection()

disableMultipleSelection(): this

禁用多选。

graph.toggleMultipleSelection(...)

toggleMultipleSelection(multiple?: boolean): this

切换多选的启用状态。

参数

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

graph.isSelectionMovable()

isSelectionMovable(): boolean

返回选中的节点/边是否可以被移动。

graph.enableSelectionMovable()

enableSelectionMovable(): this

启用选中的节点/边的移动。

graph.disableSelectionMovable()

disableSelectionMovable(): this

禁用选中节点/边的移动。

graph.toggleSelectionMovable(...)

toggleSelectionMovable(enabled?: boolean): this

切换选中节点/边是否可以被移动。

参数

名称类型必选默认值描述
enabledboolean-是否启用选中的节点/边的移动,缺省时切换启用状态。

graph.isRubberbandEnabled()

isRubberbandEnabled(): boolean

返回是否启用了框选。

graph.enableRubberband()

enableRubberband(): this

启用框选。

graph.disableRubberband()

disableRubberband(): this

禁用框选。

graph.toggleRubberband(...)

toggleRubberband(enabled?: boolean): this

切换框选的启用状态。

参数

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

graph.isStrictRubberband()

isStrictRubberband(): boolean

返回是否启用了严格框选。启用严格框选后,只有节点/边被选框完全包围时才会选中节点/边。

graph.enableStrictRubberband()

enableStrictRubberband(): this

启用严格框选。启用严格框选后,只有节点/边被选框完全包围时才会选中节点/边。

graph.disableStrictRubberband()

disableStrictRubberband(): this

禁用严格框选。禁用严格框选后,只需要选框与节点/边的包围盒相交即可选中节点/边。

graph.toggleStrictRubberband(...)

toggleStrictRubberband(enabled?: boolean): this

切换严格框选的启用状态。

参数

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

graph.setSelectionFilter(...)

setSelectionFilter(
  filter?:
   | null
   | (string | { id: string })[]
   | ((this: Graph, cell: Cell) => boolean)
): this

设置选择的过滤条件,满足过滤条件的节点/边将不能被选中。

  • filternullundefined 时,不过滤节点/边。
  • filter(string | { id: string })[] 时,表示具有这些 ID 的节点/边不能被选中
  • filter(this: Graph, cell: Cell) => boolean 时,返回 false 时节点/边不能被选中。

graph.setRubberbandModifiers(...)

setRubberbandModifiers(modifiers?: string | ModifierKey[] | null): this

设置框选的修饰键,只有同时按下修饰键时才能触发框选。

graph.setSelectionDisplayContent(...)

setSelectionDisplayContent(
  content?: 
   | null
   | false
   | string
   | ((this: Graph, selection: Selection, contentElement: HTMLElement) => string)
): this

设置选中节点/边的附加显示内容。

  • contentnullundefinedfalse 时,不显示附加内容
  • contentstring 时,显示一段文本。
  • content(this: Graph, selection: Selection, contentElement: HTMLElement) => string 时,动态返回显示的内容。