Keyboard

This section mainly introduces the Keyboard plugin. By reading, you will learn:

How to bind keyboard shortcuts on the canvas

Usage

Enable keyboard shortcuts via the Keyboard plugin:

import { Graph, Keyboard } from '@antv/x6'

const graph = new Graph({
  background: {
    color: '#F2F7FA',
  },
})
graph.use(
  new Keyboard({
    enabled: true,
  }),
)

Demo

Configuration

Property Name	Type	Default Value	Description
global	boolean	`false`	Whether to use global keyboard events. When set to `true`, keyboard events are bound to `document`; otherwise they are bound to the canvas container. When bound to the canvas container, it must be focused to trigger keyboard events.
format	`(this: Graph, key: string) => string`	-	Format the key string when binding or unbinding keyboard events.
guard	`(this: Graph, e: KeyboardEvent) => boolean`	-	Determine whether a keyboard event should be processed. If it returns `false`, the corresponding keyboard event is ignored.

The format and guard configurations are used as follows:

graph.use(
  new Keyboard({
    enabled: true,
    format(key) {
      return key.replace(/\s/g, '').replace('cmd', 'command')
    },
  }),
)
// The statement below is equivalent to graph.bindKey('command', (e) => { })
graph.bindKey('cmd', (e) => {})

graph.use(
  new Keyboard({
    enabled: true,
    guard(this: Graph, e: KeyboardEvent) {
      if (e.altKey) {
        // Ignore all keyboard events when the alt key is pressed
        return false
      }
      return true
    },
  }),
)

API

graph.bindKey(...)

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

Bind keyboard shortcuts.

graph.unbindKey(...)

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

Unbind keyboard shortcuts.

graph.clearKeys()

clearKeys(): this

Clear all keyboard shortcuts.

graph.triggerKey()

triggerKey(
  keys: string,
  action?: 'keypress' | 'keydown' | 'keyup',
): this

Manually trigger keyboard shortcuts.

graph.isKeyboardEnabled()

isKeyboardEnabled(): boolean

Returns whether keyboard events are enabled.

graph.enableKeyboard()

enableKeyboard(): this

Enable keyboard events.

graph.disableKeyboard()

disableKeyboard(): this

Disable keyboard events.

graph.toggleKeyboard(...)

toggleKeyboard(enabled?: boolean): this

Toggle the enabled state of keyboard events. The parameters are as follows:

Name	Type	Required	Default Value	Description
enabled	boolean		-	Whether to enable keyboard events; if omitted, toggles the current enabled state.