ScrollCanvas

Overview

ScrollCanvas is a built-in behavior in G6 used to implement the canvas scrolling feature, supporting panning the canvas using the mouse wheel or keyboard arrow keys. This interaction is particularly useful for browsing larger charts, allowing users to explore different areas of the chart without changing the zoom level.

Use Cases

This behavior is mainly used for:

• Browsing large chart content that exceeds the visible area
• Exploring different parts of the graph while maintaining the current zoom level
• Precisely adjusting the view position, especially when precise scrolling is needed in one-dimensional directions

Online Experience

import { createGraph } from '/demo-runtime.ts';

createGraph(
  {
    data: { nodes: [{ id: 'node-1' }] },
    layout: { type: 'force' },
    behaviors: [
      {
        type: 'scroll-canvas',
        key: 'scroll-canvas',
      },
    ],
    node: { style: { fill: '#873bf4' } },
    edge: { style: { stroke: '#8b9baf' } },
    plugins: [{ type: 'grid-line', size: 30 }],
  },
  { width: 600, height: 300 },
  (gui, graph) => {
    const options = {
      key: 'scroll-canvas',
      type: 'scroll-canvas',
      direction: 'No limit',
      enable: true,
      sensitivity: 1,
      trigger: 'Use wheel by default',
    };
    const optionFolder = gui.addFolder('ZoomCanvas Options');
    optionFolder.add(options, 'type').disable(true);
    optionFolder.add(options, 'direction', {
      'No limit': '',
      'Only allow horizontal scrolling': 'x',
      'Only allow vertical scrolling': 'y',
    });
    optionFolder.add(options, 'enable');
    optionFolder.add(options, 'sensitivity', 0, 10, 1);
    optionFolder.add(options, 'trigger', {
      'Use wheel by default': [],
      'Shift+Arrow Key': {
        up: ['Shift', 'ArrowUp'],
        down: ['Shift', 'ArrowDown'],
        left: ['Shift', 'ArrowLeft'],
        right: ['Shift', 'ArrowRight'],
      },
    });
    optionFolder.onChange(({ property, value }) => {
      graph.updateBehavior({
        key: 'scroll-canvas',
        [property]: value,
      });
      graph.render();
    });
  },
);

import { Graph } from '@antv/g6';
import GUI from 'lil-gui';

export function addPanel(renderPanel: (gui: GUI) => void) {
  const gui = new GUI({ container: document.body });
  gui.title('Control');
  Object.assign(gui.domElement.style, { position: 'absolute', top: '0', right: '0', zIndex: '10' });
  renderPanel(gui);
  addEventListener('pagehide', () => gui.destroy(), { once: true });
}

export async function createGraph(
  options: ConstructorParameters<typeof Graph>[0],
  size: { width?: number; height?: number } = {},
  renderPanel?: (gui: GUI, graph: Graph) => void,
) {
  const container = document.createElement('div');
  Object.assign(container.style, {
    width: '100%',
    maxWidth: `${size.width || 600}px`,
    height: `${size.height || 400}px`,
  });
  document.getElementById('container')!.append(container);
  const graph = new Graph({ ...size, ...options, width: container.clientWidth, container, autoResize: true });
  addEventListener('pagehide', () => graph.destroy(), { once: true });
  await graph.render();
  if (renderPanel) addPanel((gui) => renderPanel(gui, graph));
  return container;
}

Basic Usage

Add this behavior in the graph configuration:

1. Quick Configuration (Static)

Declare directly using a string form. This method is simple but only supports default configuration and cannot be dynamically modified after configuration:

const graph = new Graph({
  // Other configurations...
  behaviors: ['scroll-canvas'],
});

2. Object Configuration (Recommended)

Configure using an object form, supporting custom parameters, and can dynamically update the configuration at runtime:

const graph = new Graph({
  // Other configurations...
  behaviors: [
    {
      type: 'scroll-canvas',
      key: 'scroll-canvas-1', // Specify an identifier for the behavior for dynamic updates
      sensitivity: 1.5, // Set sensitivity
      direction: 'y', // Allow only vertical scrolling
    },
  ],
});

Configuration Options

Direction

direction is used to limit the scrolling direction:

• Not set or set to undefined: Allow scrolling in any direction
• Set to 'x': Allow only horizontal scrolling
• Set to 'y': Allow only vertical scrolling

This is useful in specific visualization scenarios, such as in timeline charts where only horizontal scrolling may be needed.

Range

range is used to control the scrollable range of the canvas:

• Set to a single number: Use the same value for all four directions
• Set to an array: Specify the range for [top, right, bottom, left] directions respectively

For example:

range: 2; // Can scroll 2 viewport distances in any direction
range: [1, 2, 1, 2]; // Can scroll 1 viewport up and down, 2 viewports left and right

The value range for each direction is [0, Infinity], where 0 means no scrolling, and Infinity means unlimited scrolling.

Trigger

trigger allows you to configure keyboard arrow keys to control canvas scrolling:

{
  trigger: {
    up: ['ArrowUp'],     // Shortcut key for scrolling up
    down: ['ArrowDown'], // Shortcut key for scrolling down
    left: ['ArrowLeft'], // Shortcut key for scrolling left
    right: ['ArrowRight'] // Shortcut key for scrolling right
  }
}

You can also configure combination keys:

{
  trigger: {
    up: ['Control', 'ArrowUp'],     // Ctrl + Up Arrow
    down: ['Control', 'ArrowDown'], // Ctrl + Down Arrow
    left: ['Control', 'ArrowLeft'], // Ctrl + Left Arrow
    right: ['Control', 'ArrowRight'] // Ctrl + Right Arrow
  }
}

Code Examples

Basic Scrolling Functionality

const graph = new Graph({
  container: 'container',
  width: 800,
  height: 600,
  behaviors: ['scroll-canvas'],
});

Allow Only Horizontal Scrolling

const graph = new Graph({
  // Other configurations...
  behaviors: [
    {
      type: 'scroll-canvas',
      direction: 'x', // Allow only horizontal scrolling
    },
  ],
});

Custom Scrolling Sensitivity and Range

const graph = new Graph({
  // Other configurations...
  behaviors: [
    {
      type: 'scroll-canvas',
      sensitivity: 1.8, // Increase scrolling sensitivity
      range: [0.5, 2, 0.5, 2], // Smaller limits up and down, larger limits left and right
    },
  ],
});

Control Scrolling with Keyboard Arrow Keys

const graph = new Graph({
  // Other configurations...
  behaviors: [
    {
      type: 'scroll-canvas',
      trigger: {
        up: ['ArrowUp'],
        down: ['ArrowDown'],
        left: ['ArrowLeft'],
        right: ['ArrowRight'],
      },
    },
  ],
});

FAQ

1. What is the difference between ScrollCanvas and ZoomCanvas?

• ScrollCanvas is used to pan the canvas without changing the zoom level
• ZoomCanvas is used to zoom the canvas, changing the view’s zoom level

They are often used together to provide complete canvas navigation functionality:

const graph = new Graph({
  // Other configurations...
  behaviors: ['drag-canvas', 'zoom-canvas', 'scroll-canvas'],
});

Practical Example

import { Graph } from '@antv/g6';

const graph = new Graph({
  container: 'container',
  layout: {
    type: 'grid',
  },
  data: {
    nodes: [{ id: 'node1' }, { id: 'node2' }, { id: 'node3' }, { id: 'node4' }, { id: 'node5' }],
    edges: [
      { source: 'node1', target: 'node2' },
      { source: 'node1', target: 'node3' },
      { source: 'node1', target: 'node4' },
      { source: 'node2', target: 'node3' },
      { source: 'node3', target: 'node4' },
      { source: 'node4', target: 'node5' },
    ],
  },
  behaviors: ['scroll-canvas'],
});

graph.render();

import { Graph } from '@antv/g6';
import GUI from 'lil-gui';

export function addPanel(renderPanel: (gui: GUI) => void) {
  const gui = new GUI({ container: document.body });
  gui.title('Control');
  Object.assign(gui.domElement.style, { position: 'absolute', top: '0', right: '0', zIndex: '10' });
  renderPanel(gui);
  addEventListener('pagehide', () => gui.destroy(), { once: true });
}

export async function createGraph(
  options: ConstructorParameters<typeof Graph>[0],
  size: { width?: number; height?: number } = {},
  renderPanel?: (gui: GUI, graph: Graph) => void,
) {
  const container = document.createElement('div');
  Object.assign(container.style, {
    width: '100%',
    maxWidth: `${size.width || 600}px`,
    height: `${size.height || 400}px`,
  });
  document.getElementById('container')!.append(container);
  const graph = new Graph({ ...size, ...options, width: container.clientWidth, container, autoResize: true });
  addEventListener('pagehide', () => graph.destroy(), { once: true });
  await graph.render();
  if (renderPanel) addPanel((gui) => renderPanel(gui, graph));
  return container;
}