--- title: "缩放画布 ZoomCanvas" description: "缩放画布 ZoomCanvas" language: "zh" canonical: "https://g6.antv.antgroup.com/zh/manual/behavior/ZoomCanvas/" version: "5.1.1" --- ## 概述 ZoomCanvas 是 G6 中用于实现画布缩放功能的内置交互，支持通过鼠标滚轮或键盘快捷键调整画布缩放比例。这是图可视化中最常用的交互之一，能帮助用户查看图的整体结构和局部细节。 ## 使用场景 这一交互主要用于： - 浏览大规模图数据，在整体与细节之间自由切换 - 聚焦到特定区域进行详细分析 ## 在线体验 ```ts import { createGraph } from '/demo-runtime.ts'; createGraph( { data: { nodes: [{ id: 'node-1' }] }, layout: { type: 'force' }, behaviors: [ { type: 'zoom-canvas', key: 'zoom-canvas', }, ], node: { style: { fill: '#873bf4' } }, edge: { style: { stroke: '#8b9baf' } }, plugins: [{ type: 'grid-line', size: 30 }], }, { width: 600, height: 300 }, (gui, graph) => { const options = { key: 'zoom-canvas', type: 'zoom-canvas', animation: true, enable: true, sensitivity: 1, trigger: 'Use wheel by default', }; const optionFolder = gui.addFolder('ZoomCanvas Options'); optionFolder.add(options, 'type').disable(true); optionFolder.add(options, 'animation'); optionFolder.add(options, 'enable'); optionFolder.add(options, 'sensitivity', 0, 10, 1); optionFolder.add(options, 'trigger', { 'Use wheel by default': [], 'Control+Wheel': ['Control'], 'zoomIn:Ctrl+1 zoomOut:Ctrl+2 reset:Ctrl+0': { zoomIn: ['Control', '1'], zoomOut: ['Control', '2'], reset: ['Control', '0'], }, }); optionFolder.onChange(({ property, value }) => { graph.updateBehavior({ key: 'zoom-canvas', [property]: value, }); graph.render(); }); }, ); ``` ## 基本用法 在图配置中添加这一交互： **1. 快速配置（静态）** 使用字符串形式直接声明，这种方式简洁但仅支持默认配置，且配置后不可动态修改： ```javascript const graph = new Graph({ // 其他配置... behaviors: ['zoom-canvas'], }); ``` **2. 对象配置（推荐）** 使用对象形式进行配置，支持自定义参数，且可以在运行时动态更新配置： ```javascript const graph = new Graph({ // 其他配置... behaviors: [ { type: 'zoom-canvas', key: 'zoom-canvas-1', // 为交互指定标识符，方便动态更新 sensitivity: 1.5, // 设置灵敏度 }, ], }); ``` ## 配置项 | 配置项 | 说明 | 类型 | 默认值 | 必选 | | -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------- | ---- | | type | 交互类型名称 | string | `zoom-canvas` | ✓ | | animation | 缩放动画效果设置 | [ViewportAnimationEffectTiming](/zh/manual/graph/option/#viewportanimationeffecttiming) | `{ duration: 200 }` | | | enable | 是否启用该交互 | boolean \| ((event: Event) => boolean) | true | | | origin | 缩放中心点(视口坐标) | [Point](/zh/api/viewport/#point) | - | | | onFinish | 缩放完成时的回调函数 | () => void | - | | | preventDefault | 是否阻止浏览器默认事件 | boolean | true | | | sensitivity | 缩放灵敏度，值越大缩放速度越快 | number | 1 | | | trigger | 触发缩放的方式，支持滚轮和键盘快捷键，[配置项](#trigger) | string[] \| object | - | | ### Trigger `trigger`有两种使用方式，分别适用于不同场景： #### 方式一：与滚轮结合的修饰键 当你希望只有在按下某些键的同时滚动滚轮才触发缩放时，可以这样配置： ```javascript { trigger: ['Control']; // 按住 Control 键同时滚动鼠标滚轮才能缩放 } ``` 常见的修饰键有： - `Control` - `Shift` - `Alt` > 不知道键盘按键对应什么值？请参考 [MDN Key Values](https://developer.mozilla.org/zh-CN/docs/Web/API/UI_Events/Keyboard_event_key_values)。 #### 方式二：纯键盘快捷键 当你希望完全使用键盘控制缩放操作时，可以设置组合键： ```javascript { trigger: { zoomIn: ['Control', '+'], // 放大快捷键 zoomOut: ['Control', '-'], // 缩小快捷键 reset: ['Control', '0'] // 重置缩放比例快捷键 } } ``` ## 代码示例 ### 基础缩放功能 ```javascript const graph = new Graph({ container: 'container', width: 800, height: 600, behaviors: ['zoom-canvas'], }); ``` ### 自定义缩放中心 ```javascript const graph = new Graph({ // 其他配置... behaviors: [ function () { return { type: 'zoom-canvas', origin: this.getCanvasCenter(), // 以视口中心为原点进行缩放 }; }, ], }); ``` ### 自定义缩放灵敏度 ```javascript const graph = new Graph({ // 其他配置... behaviors: [ { type: 'zoom-canvas', sensitivity: 0.8, // 降低灵敏度，缩放变化更平缓 }, ], }); ``` ### 使用Shift+滚轮进行缩放 ```javascript const graph = new Graph({ // 其他配置... behaviors: [ { type: 'zoom-canvas', trigger: ['Shift'], // 按住 Shift 键同时滚动才能缩放 }, ], }); ``` ### 使用键盘快捷键控制缩放 ```javascript const graph = new Graph({ // 其他配置... behaviors: [ { type: 'zoom-canvas', trigger: { zoomIn: ['Control', '='], // Ctrl + = 放大 zoomOut: ['Control', '-'], // Ctrl + - 缩小 reset: ['Control', '0'], // Ctrl + 0 重置 }, }, ], }); ``` ### 支持移动端双指缩放 ```javascript const graph = new Graph({ // 其他配置... behaviors: [ { type: 'zoom-canvas', // PC 端其他配置... }, function () { return { type: 'zoom-canvas', trigger: ['pinch'], sensitivity: 0.8, // 降低灵敏度，缩放变化更平缓 origin: this.getCanvasCenter(), // 以视口中心为原点进行缩放 }; }, ], }); ``` ## 常见问题 ### 1. 画布缩放超出了预期范围怎么办？ 为避免缩放过大或过小，可以设置缩放限制： ```javascript const graph = new Graph({ // 其他配置... zoomRange: [0.5, 3], // 允许缩小到50%和放大到300% behaviors: ['zoom-canvas'], }); ``` ### 2. 如何与其他交互结合使用？ 缩放与拖拽是常见的组合，实现完整的导航体验： ```javascript const graph = new Graph({ // 其他配置... behaviors: ['drag-canvas', 'zoom-canvas'], }); ``` ### 3. 触控板双指操作下，与 scroll-canvas 同时使用时的冲突 在触控板上，双指滑动（用于滚动）和双指捏合（用于缩放）手势通常都会被解析为 `wheel` 事件。 由于 `zoom-canvas` 和 `scroll-canvas` 默认都会响应 `wheel` 事件，当它们同时使用时会产生冲突，例如一个手势会同时触发滚动和缩放。 你可以通过检查 `event.ctrlKey` 属性来解决这个问题。在多数平台上，捏合手势会使 `event.ctrlKey` 为 `true`，而滑动则不会。这允许你有条件地仅为捏合手势启用 `zoom-canvas`。 ```ts import { Graph } from '@antv/g6'; const graph = new Graph({ container: 'container', layout: { type: 'grid', }, data: { nodes: [{ id: 'node1' }, { id: 'node2' }, { id: 'node3' }], }, behaviors: [ 'scroll-canvas', { key: 'custom-zoom-canvas', type: 'zoom-canvas', enable: (event) => { return event.ctrlKey; // ctrlKey 为 true 时，是双指捏合或扩张操作，false 时是双指滑动操作 }, }, ], }); graph.render(); ``` ## 实际案例 ```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: ['zoom-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; } ```