指南
画布缩放 OkrTreeViewport
OkrTreeViewport 的 props、ref 方法、滚轮/拖拽/触控交互契约与 PNG / SVG 导出
大树在固定视口里放不下时,用 <OkrTreeViewport> 包裹树即可获得缩放与平移能力——它只做外层变换,不侵入树本体,也不改变树的任何 API。
画布组件 OkrTreeViewport(1.4.0 新增)
<okr-tree-viewport> 包裹树即可获得缩放与平移能力(不侵入树本体):滚轮缩放以指针为中心、按住拖拽平移、双击复位、触控双指捏合。 默认 wheel-behavior="ctrl-zoom"——按住 Ctrl / ⌘ + 滚轮缩放,避免劫持页面滚动;设为 zoom 始终缩放、scroll 从不缩放。
显示代码
Props
| prop | 说明 | 默认值 |
|---|---|---|
min-zoom / max-zoom | 缩放范围 | 0.2 / 4 |
zoom-step | 每次 zoomIn / zoomOut / 滚轮一格的缩放系数(乘除) | 1.2 |
zoom | 受控缩放(v-model:zoom),未传时内部维护 | — |
offset | 受控平移偏移 { x, y }(v-model:offset),未传时内部维护 | — |
wheel-behavior | 滚轮行为:ctrl-zoom(默认,按住 Ctrl/⌘ 才缩放,不劫持页面滚动)/ zoom(始终缩放)/ scroll(从不缩放) | ctrl-zoom |
toolbar | 是否显示默认工具栏;传入 #toolbar 插槽时无需开启 | false |
方法(通过 ref 调用)
| 方法 | 说明 |
|---|---|
zoomIn() / zoomOut() | 以视口中心为锚放大 / 缩小(受 min/max 钳制) |
reset() | 复位到缩放 1、偏移 0(双击画布同样触发) |
fitToScreen(padding?) | 适应窗口:内容完整可见并居中,默认四周留 20px |
centerNode(key) | 先展开目标节点的祖先,再把视口中心对准该节点 |
getZoom() | 读当前缩放系数(受控模式下即 v-model:zoom 的值) |
getOffset() | 读当前平移偏移 { x, y } |
exportImage(options?) | 导出画布内容为 PNG / SVG 并触发下载,返回 dataURL |
交互契约
- 滚轮缩放以指针为中心:缩放前后指针下的内容点保持不变,所以放大哪里就看哪里;
wheel-behavior三档控制是否劫持页面滚动(默认ctrl-zoom,按住 Ctrl / ⌘ 才缩放)。 - 按住拖拽平移:位移超过 3px 才判定为平移(
PAN_THRESHOLD),单击节点不会被误当成拖动;并且平移结束后吞掉随后的一次click,避免拖完顺手触发了node-click。 - 双击复位:等价于
reset();工具栏区域内的双击不触发复位(已stop)。 - 触控:双指捏合缩放,单指拖动平移(走 Pointer Events,鼠标与触摸同一套逻辑)。
- 只监听
button === 0的鼠标按下,右键拖拽不会平移。
工具栏
传入 #toolbar 插槽时不需要开 toolbar prop;不传插槽、只开 toolbar 则渲染内置工具栏。插槽作用域:
| 参数 | 类型 | 说明 |
|---|---|---|
zoom | number | 当前缩放系数(响应式) |
zoomIn() | () => void | 按 zoom-step 放大 |
zoomOut() | () => void | 按 zoom-step 缩小 |
reset() | () => void | 复位缩放与偏移 |
fit() | () => void | 适应窗口(即 fitToScreen()) |
导出
exportImage 基于 html-to-image:以可选 peerDependency 声明(^1.11.0,不进 dependencies),用到导出能力时自行 npm i html-to-image;默认按需 import('html-to-image'),未安装时抛出带安装指引的错误。在打包器下动态导入裸包名不可靠时,可通过 options.toPng / toSvg 直接传入渲染函数(签名与 html-to-image 一致)。选项:type('png' | 'svg',默认 png)、scale(像素密度,默认 2)、background(背景色)。
与 OkrTreeGroup 组合
<OkrTreeGroup> 可以放在 <OkrTreeViewport> 内组合使用;树的方法 getNodeEl(key) 返回节点 DOM 元素,供外部定位。