指南

画布缩放 OkrTreeViewport

OkrTreeViewport 的 props、ref 方法、滚轮/拖拽/触控交互契约与 PNG / SVG 导出

大树在固定视口里放不下时,用 <OkrTreeViewport> 包裹树即可获得缩放与平移能力——它只做外层变换,不侵入树本体,也不改变树的任何 API。

画布组件 OkrTreeViewport(1.4.0 新增)

<okr-tree-viewport> 包裹树即可获得缩放与平移能力(不侵入树本体):滚轮缩放以指针为中心、按住拖拽平移、双击复位、触控双指捏合。 默认 wheel-behavior="ctrl-zoom"——按住 Ctrl / ⌘ + 滚轮缩放,避免劫持页面滚动;设为 zoom 始终缩放、scroll 从不缩放。

100%
工具栏通过 #toolbar 作用域插槽自定义(作用域含 zoom / zoomIn / zoomOut / reset / fit);导出基于 html-to-image(默认动态 import,也可通过 exportImage({ toPng }) 传入渲染函数,本用例即后者)。 centerNode(key) 可先展开祖先再把视口中心对准指定节点。
<template>
  <okr-tree-viewport ref="vp" toolbar :wheel-behavior="wheelMode">
    <vue-okr-tree :data="orgData" node-key="id" direction="horizontal" show-collapsable />
    <template #toolbar="{ zoom, zoomIn, zoomOut, reset, fit }">
      <button @click="zoomOut()">−</button>
      <span>{{ Math.round(zoom * 100) }}%</span>
      <button @click="zoomIn()">+</button>
      <button @click="reset()">重置</button>
      <button @click="fit()">适应窗口</button>
      <button @click="exportPng()">导出 PNG</button>
    </template>
  </okr-tree-viewport>
</template>

<script setup>
import { ref } from 'vue'
import { toPng } from 'html-to-image'
import { OkrTreeViewport, VueOkrTree } from 'vue3-okr-tree'

const vp = ref(null)
const wheelMode = ref('ctrl-zoom') // ctrl-zoom(默认)/ zoom / scroll
const orgData = ref([{ id: 1, label: 'xxx科技有有限公司', children: [/* ... */] }])

function exportPng() {
  // 传入 toPng 可免去动态 import 依赖;不传则按需 import('html-to-image')
  vp.value.exportImage({ type: 'png', scale: 2, background: '#fff', toPng })
}
</script>
显示代码

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 则渲染内置工具栏。插槽作用域:

参数类型说明
zoomnumber当前缩放系数(响应式)
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 元素,供外部定位。

Copyright © 2026