--- title: "ScrollCanvas" description: "ScrollCanvas" language: "en" canonical: "https://g6.antv.antgroup.com/en/manual/behavior/ScrollCanvas/" version: "5.1.1" --- ## 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 ```ts 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(); }); }, ); ``` ## 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: ```javascript 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: ```javascript 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 | Option | Description | Type | Default | Required | | -------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | -------- | | type | Behavior type name | string | `scroll-canvas` | ✓ | | enable | Whether to enable this behavior | boolean \| ((event: [WheelEvent](https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent) \| [KeyboardEvent](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent)) => boolean) | true | | | direction | Allowed scrolling direction, [configuration options](#direction) | `'x'` \| `'y'` \| `undefined` | `undefined` (no direction limit) | | | range | Scrollable viewport range (in viewport size units), [configuration options](#range) | number \| number[] | 1 | | | sensitivity | Scrolling sensitivity, the larger the value, the faster the scrolling | number | 1 | | | trigger | Keyboard shortcuts to trigger scrolling, [configuration options](#trigger) | object | - | | | onFinish | Callback function when scrolling is finished | () => void | - | | | preventDefault | Whether to prevent the browser's default event | boolean | true | | ### 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: ```javascript 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: ```javascript { 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: ```javascript { 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 ```javascript const graph = new Graph({ container: 'container', width: 800, height: 600, behaviors: ['scroll-canvas'], }); ``` ### Allow Only Horizontal Scrolling ```javascript const graph = new Graph({ // Other configurations... behaviors: [ { type: 'scroll-canvas', direction: 'x', // Allow only horizontal scrolling }, ], }); ``` ### Custom Scrolling Sensitivity and Range ```javascript 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 ```javascript 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: ```javascript const graph = new Graph({ // Other configurations... behaviors: ['drag-canvas', 'zoom-canvas', 'scroll-canvas'], }); ``` ### Practical Example ```ts 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(); ``` ### demo-runtime.ts ```ts 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[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; } ```