API
Props / Events / Methods / Slots 完整参考，由 shared/api.ts 单一来源生成（README 只保留分组概览）
Attributes
与 vue-okr-tree 完全对齐；align-root 起为 Vue 3 版新增。
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| data | 展示数据（数组，支持多根） | array | — | — (必填) |
| direction | 树的展开方向 | string | horizontal / vertical | vertical |
| onlyBothTree | 飞书 OKR 模式：子树在根节点左右两边展开，该模式只有在 direction 为 horizontal 时有效，且必须提供 leftData 数据 | boolean | — | false |
| leftData | 展示左子树的数据，仅在 onlyBothTree 模式启用 | array | — | — |
| label-width | 节点的宽度，默认为自动宽度。number 类型单位 px；string 类型直接作为节点的 style.width | string / number | — | auto |
| label-height | 节点的高度，默认为自动高度。number 类型单位 px；string 类型直接作为节点的 style.height | string / number | — | auto |
| label-class-name | 节点 className 的回调方法，也可以使用字符串为所有节点设置固定 className。函数参数为内部 Node 实例（源数据在 node.data） | Function(node) / string | — | — |
| current-lable-class-name | 当前选中节点的样式（保留原拼写） | Function(node) / string | — | — |
| show-collapsable | 节点是否可被展开（显示 +/- 圆形按钮）。为 false 时组件强制全部展开 | boolean | — | false |
| accordion | Vue 3 版新增。手风琴模式：用户展开某节点时自动收起其同级兄弟。与 el-tree 语义一致，只作用于交互展开（点击 +/- 按钮、点击节点内容、键盘操作）；expandNode 等程序化方法与受控 expanded-keys 不受互斥限制 | boolean | — | false |
| expand-on-click-node | Vue 3 版新增。点击节点内容时切换该节点的展开 / 收起（默认 false 保持原版行为）。叶子节点点击只选中不切换；选中态与 node-click 照常触发。OKR 模式根节点点击内容只切换右侧子树 | boolean | — | false |
| show-checkbox | Vue 3 版新增（1.9.0）。复选框选择模式：节点内容前渲染复选框，父子联动半选态（check-strictly 可关闭）。键盘 Space 切换勾选、Enter 选中。OKR 模式左右两树勾选独立维护，方法按 key 对两树同时生效 | boolean | — | false |
| check-strictly | Vue 3 版新增（1.9.0）。父子不联动：勾选只作用于自身，无半选传播（运行时切换后新交互按新模式执行） | boolean | — | false |
| default-checked-keys | Vue 3 版新增（1.9.0）。初始勾选的节点 key 数组（必须设置 node-key）。创建期生效；运行时内容变更会先清空再按新列表重新应用（宿主只是换了一个等值数组引用时不重放，不会抹掉用户改过的勾选）；data 重建后不恢复（与 default-expanded-keys 一致） | array | — | — |
| draggable | Vue 3 版新增（1.10.0）。拖拽调整层级：HTML5 DnD，节点卡片可拖到目标节点的 prev / inner / next（水平模式按纵向 25%/50%/25% 分区，垂直模式按横向）。移动同步修改源数据 children，inner 时目标自动展开。硬性禁止放到自身或自己的子树内；OKR 模式跨左右树默认禁止 | boolean | — | false |
| allow-drag | Vue 3 版新增（1.10.0）。拖拽规则钩子：返回 false 禁止拖动该节点（disabled 节点始终不可拖） | Function(node) | — | — |
| allow-drop | Vue 3 版新增（1.10.0）。放置规则钩子：返回 false 禁止该放置位置；OKR 模式跨左右树默认禁止，返回 true 可放开 | Function(draggingNode, dropNode, type) | type: 'prev' / 'inner' / 'next' | — |
| connector | Vue 3 版新增（1.11.0）。连接线渲染模式：css（默认，伪元素像素几何）/ svg（覆盖层 <svg> 路径）。svg 模式布局与 css 模式完全一致，随展开/收起、animate 过渡、尺寸变化自动重绘无残影；可与画布缩放、OKR 模式组合 | string | css / svg | css |
| connector-shape | Vue 3 版新增（1.11.0）。svg 模式的路径形状（仅 connector="svg" 时生效）：curve 贝塞尔曲线 / orthogonal 直角折线 / straight 直线 | string | curve / orthogonal / straight | curve |
| unstyled | Vue 3 版新增（1.13.0）。去掉卡片外观（背景 / 边框 / 圆角 / 阴影），只保留布局与连接线，供 Tailwind 或自有设计系统接管。内边距、字号与文字色不受影响——改 padding 会移动节点盒并牵动连接线几何，需要调整请用 --okr-node-* 变量或 label-class-name | boolean | — | false |
| show-node-num | 折叠时在圆形按钮内显示子节点数（只计未被 filter 隐藏的可见子节点） | boolean | — | false |
| default-expand-all | 默认展开全部，仅在 show-collapsable 为 true 时有意义 | boolean | — | false |
| render-content | 树节点内容区的渲染 Function。h 由组件从 vue 导入后传入；node 为内部 Node 实例（源数据在 node.data，文本在 node.label），与 element-ui 的 (h, { data }) 不同 | Function(h, node) | — | — |
| node-btn-content | 展开按钮内容渲染函数，参数约定同上 | Function(h, node) | — | — |
| node-component | Vue 3 版新增。节点内容组件，以 { node, data } 为 props 渲染。优先级：#default 插槽 > node-component > render-content | Component | — | — |
| props | 配置选项，具体看下表 | object | — | — |
| node-key | 每个树节点用来作为唯一标识的属性，整棵树应该是唯一的 | string | — | — |
| default-expanded-keys | 默认展开的节点的 key 数组（必须设置 node-key）。OKR 模式下对左右两棵树同时生效 | array | — | — |
| current-node-key | 初始选中节点的 key（需 node-key） | string / number | — | — |
| filter-node-method | 对树节点进行筛选时执行的方法，返回 true 表示节点可以显示，返回 false 隐藏。调用 filter('') 时同样会执行，需对空值返回 true 以恢复全部显示 | Function(value, data, node) | — | — |
| animate | 是否开启节点展开的过渡动画。系统开启「减弱动态效果」（prefers-reduced-motion: reduce）时自动按关闭处理 | boolean | — | false |
| animate-name | 过渡动画名称 | string | okr-fade-in-linear / okr-fade-in / okr-zoom-in-center / okr-zoom-in-top / okr-zoom-in-bottom / okr-zoom-in-left | okr-zoom-in-center |
| animate-duration | 过渡动画时长（ms）。原版声明但未生效，Vue 3 版已修复 | number | — | 200 |
| align-root | Vue 3 版新增。OKR 模式下自动按左右子树对齐根节点（纯 CSS），展开/收起不改变根节点位置；设为 false 恢复原始行为 | boolean | — | true |
| theme | Vue 3 版新增。内置主题：default / feishu / dark / auto / minimal / colorful，或自定义名字（自行编写 .okr-theme-{name} 变量，名字不在内置清单里会输出开发期警告）。全部外观取值可通过 --okr-* CSS 变量覆盖 | string | default / feishu / dark / auto / minimal / colorful | default |
| expanded-keys | Vue 3 版新增。受控展开态（支持 v-model:expanded-keys，需 node-key）：传入后列表内节点展开、其余收起；用户点击 +/- 或调用展开/收起方法后触发 update:expandedKeys。未传时为非受控（原版行为） | array | — | — |
| current-key | Vue 3 版新增。受控选中态（支持 v-model:current-key，需 node-key）：null 表示无选中；点击节点或调用 setCurrentKey / setCurrentNode 后触发 update:currentKey | string / number / null | — | — |
| lazy | Vue 3 版新增（1.4.0）。懒加载子节点：初始 data 中没有 children（或为空数组）的节点视为未加载，首次展开时调用 load | boolean | — | false |
| load | Vue 3 版新增（1.4.0）。懒加载取数函数。resolve(children) 后子节点同步写入源数据 children 并展开；reject() 或抛错时节点回到折叠态、可重试。node.isLeftChild 可区分 OKR 左树节点 | Function(node, resolve, reject?) | — | — |
| deep-watch | Vue 3 版新增（1.5.0，创建期生效）。data 深度侦听开关：默认 true（原地变更触发增量更新）；false 只响应 data 引用变化，超大数据量且不依赖原地变更时降低 watch 开销 | boolean | — | true |
| virtual | Vue 3 版新增（1.16.0，创建期生效）。虚拟滚动：同层可见兄弟数 ≥ 50 的行只渲染视口内窗口，用等尺寸占位块保持布局与连接线逐像素等价，aria 语义按全量可见列表输出。要求数字型 label-width（horizontal 布局还要求 label-height），auto 尺寸下达标行退回全量渲染并给出开发期警告；scrollToNode 与键盘漫游对窗口外目标先揭示再定位。运行时变更不生效（创建期快照） | boolean | — | false |
Props（props 属性的字段映射配置）
通过 props 属性传入的字段映射配置。
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| label | 指定节点文本为节点对象的某个属性值，或由函数返回 | string / function(data, node) | label |
| children | 指定子树为节点对象的某个属性值 | string | children |
| disabled | 指定禁用字段（Vue 3 版实现真实禁用：禁用节点带 is-disabled 类，点击不选中、不触发 node-click） | string / function(data, node) | disabled |
| isLeaf | 指定叶子字段（Vue 3 版新增）：lazy 模式下未加载节点的 isLeaf 取该字段，标记为叶子的节点不显示展开按钮、不触发 load | string / function(data, node) | — |
Events
node 均为内部 Node 实例，nodeComponent 为递归节点组件实例。
| 事件名称 | 说明 | 回调参数 |
|---|---|---|
| node-click | 节点被点击时的回调（同时设置当前选中态） | (data, node, nodeComponent) |
| node-expand | 节点被展开时触发的事件 | (data, node, nodeComponent) |
| node-collapse | 节点被关闭时触发的事件 | (data, node, nodeComponent) |
| node-contextmenu | 当某一节点被鼠标右键点击时会触发该事件。仅当外部绑定了该事件时才阻止浏览器默认右键菜单 | (event, data, node, nodeComponent) |
| update:expandedKeys | Vue 3 版新增。受控展开态变化时触发（仅传入 expanded-keys 时） | (keys: TreeKey[]) |
| update:currentKey | Vue 3 版新增。受控选中态变化时触发（仅传入 current-key 时） | (key: TreeKey | null) |
| check | Vue 3 版新增（1.9.0）。复选框被点击时触发（仅 show-checkbox；程序化 setCheckedKeys 不触发） | (data, { checkedNodes, checkedKeys, halfCheckedNodes, halfCheckedKeys }) |
| check-change | Vue 3 版新增（1.9.0）。节点勾选状态变化时触发（仅 show-checkbox；每个受影响节点各触发一次，含联动与 setCheckedKeys 批量变更） | (data, checked, indeterminate) |
| node-drag-start | Vue 3 版新增（1.10.0）。节点开始拖拽时触发（仅 draggable） | (node, event) |
| node-drag-enter | Vue 3 版新增（1.10.0）。拖拽进入某一节点时触发 | (draggingNode, dropNode, event) |
| node-drag-leave | Vue 3 版新增（1.10.0）。拖拽离开某一节点时触发 | (draggingNode, dropNode, event) |
| node-drag-over | Vue 3 版新增（1.10.0）。拖拽悬停在某一节点的有效放置区内时触发 | (draggingNode, dropNode, event) |
| node-drag-end | Vue 3 版新增（1.10.0）。拖拽结束时触发；未完成放置时 dropNode / dropType 为 null | (draggingNode, dropNode | null, dropType | null, event) |
| node-drop | Vue 3 版新增（1.10.0）。完成放置时触发（源数据已在 moveNode 中同步） | (draggingNode, dropNode, dropType, event) |
Methods（通过 ref 调用）
通过组件 ref 调用。增删类方法会同步修改传入的源数据（与 vue-okr-tree 一致）。
| 方法名 | 说明 | 参数 |
|---|---|---|
| filter | 对树节点进行筛选操作；onlyBothTree 模式下同时过滤左右子树。未设置 filter-node-method 时抛错 | (value) 在 filter-node-method 中作为第一个参数 |
| updateKeyChildren | 通过 key 设置节点的子元素，使用此方法必须设置 node-key 属性（缺失抛错） | (key, data) 1. 节点的 key 2. 子节点数据 |
| getNode | 根据 data / key / Node 实例获取内部 Node。OKR 模式下右树优先，右树不存在时回退到左树 | (data) 要获得 node 的 key、data 对象或 Node 实例 |
| setCurrentNode | 通过 node 设置某个节点的当前选中状态，必须设置 node-key（缺失抛错） | (node) 待被选节点的 Node 实例 |
| setCurrentKey | 通过 key 设置某个节点的当前选中状态，必须设置 node-key（缺失抛错） | (key) 待被选节点的 key，若为 null 则取消当前高亮 |
| getCurrentKey | 获取当前被选中节点的 key，若没有节点被选中则返回 null。必须设置 node-key（缺失抛错） | — |
| getCurrentNode | 获取当前被选中节点的 data，若没有节点被选中则返回 null | — |
| remove | 删除 Tree 中的一个节点，使用此方法必须设置 node-key（未设置时静默无效）。会同步删除源数据中的对应项 | (data) 要删除的节点的 data、key 或 Node 实例 |
| append | 为 Tree 中的一个节点追加一个子节点。会同步写入源数据的 children | (data, parentNode) 1. 要追加的子节点的 data 2. 父节点的 data、key 或 Node 实例（省略则追加为根） |
| insertBefore | 为 Tree 的一个节点的前面增加一个节点。会同步写入源数据 | (data, refNode) 1. 要增加的节点的 data 2. 参考节点的 data、key 或 Node 实例 |
| insertAfter | 为 Tree 的一个节点的后面增加一个节点。会同步写入源数据 | (data, refNode) 1. 要增加的节点的 data 2. 参考节点的 data、key 或 Node 实例 |
| expandAll | Vue 3 版新增。展开全部节点（OKR 模式含左右两树）；lazy 模式下未加载节点先触发加载、完成后再展开 | — |
| collapseAll | Vue 3 版新增。收起全部节点 | — |
| expandNode | Vue 3 版新增。展开指定节点，默认连同祖先一起展开；OKR 根节点会同时展开左右两侧；lazy 下先加载再展开。返回 Node 或 null | (data, expandParent = true) data 为 key、data 对象或 Node 实例 |
| collapseNode | Vue 3 版新增。收起指定节点；OKR 根节点会同时收起左右两侧 | (data) |
| scrollToNode | Vue 3 版新增。滚动到指定节点：默认先展开其全部祖先使其可见，再 scrollIntoView（居中、平滑）。返回 Promise<boolean>；lazy 下等待路径上的节点加载完成后再滚动 | (data, options?) options 为 ScrollIntoViewOptions，另含 expand（默认 true） |
| getNodeEl | Vue 3 版新增（1.4.0）。按 Node / key / data 获取节点对应的 DOM 元素（OkrTreeViewport 的 centerNode 也基于它定位） | (data) |
| getCheckedKeys | Vue 3 版新增（1.9.0）。获取勾选节点 key 列表（需 node-key；OKR 模式左右两树合并去重） | (leafOnly = false) leafOnly 为 true 时只计叶子节点 |
| getCheckedNodes | Vue 3 版新增（1.9.0）。获取勾选节点 Node 实例列表 | (leafOnly = false) |
| setCheckedKeys | Vue 3 版新增（1.9.0）。以 key 列表整体设置勾选态（先清空再勾选；非 checkStrictly 时带父子联动，OKR 模式左右同 key 同时生效） | (keys, leafOnly = false) |
| getHalfCheckedKeys | Vue 3 版新增（1.9.0）。获取半选节点 key 列表（子树部分选中的父节点） | — |
| getHalfCheckedNodes | Vue 3 版新增（1.9.0）。获取半选节点 Node 实例列表 | — |
| isChecked | Vue 3 版新增（1.9.0）。判断节点当前是否被勾选 | (data) key、data 对象或 Node 实例 |
| moveNode | Vue 3 版新增（1.10.0）。移动节点到目标节点的 prev / inner / next，同步修改源数据并保持视图一致；inner 时目标自动展开。硬性禁止放到自身或自己的子树内。成功返回 true | (data, target, type) 均支持 key / data 对象 / Node 实例 |
| getVisibleNodes | Vue 3 版新增（1.12.0）。返回当前真正可见的节点实例（含 OKR 左树）：自身通过过滤且各级祖先均已展开到它。折叠的子树仍挂载在 DOM 中，因此结果不等于 DOM 里的节点数 | — |
| getNodePath | Vue 3 版新增（1.12.0）。返回从顶层节点到目标节点的链路（含目标自身），未命中返回空数组。OKR 左树节点的链路留在左树内（顶层为根节点的左侧镜像，与右树根同 key），不跨接到右树根 | (data) key、data 对象或 Node 实例 |
| getNodeKey | 取节点的 key：读 data[node-key]，未配置 node-key 时回退到内部 WeakMap 生成的 id | (node) Node 实例 |
| store / root | 内部 TreeStore 实例与根节点。供直接遍历 nodesMap、取 root 子树等高级用法，属于逃生舱，跨版本不保证稳定 | — |
Slots
Vue 3 版新增的插槽。#default 与 render-content、#expand-btn 与 node-btn-content 二者任选其一，插槽优先。
| 插槽名 | 说明 | 作用域参数 |
|---|---|---|
| default | 节点内容 | { node, data }，node 为内部 Node 实例 |
| expand-btn | 展开按钮内容；show-node-num 开启时折叠态的数字优先于该插槽 | { node, data, expanded, side, loading }，side 为 right（常规/右子树）或 left（OKR 左子树），loading 为懒加载进行中 |
| empty | data 为空数组时在容器内渲染 | — |
OkrTreeGroup 与键盘导航
Vue 3 版新增。OkrTreeGroup 包裹多棵 OKR 模式的树，使组内根节点水平坐标一致（原版需在业务层手动测量 DOM）；需成员树开启 align-root（默认）。键盘导航为所有树内置。
| 名称 | 类型 | 说明 |
|---|---|---|
| align（prop） | boolean，默认 true | 是否对齐；为 false 时各树独立排布 |
| default（slot） | — | 放置若干 <vue-okr-tree only-both-tree> |
| refresh()（method） | — | 手动重新测量（字体加载完成、外部样式变化等场景；组件已自动响应成员挂载/更新与尺寸变化） |
| 键盘导航 | — | Tab 进入，↑/↓ 在可见节点间移动，→ 展开或进入子节点，← 收起或回到父节点，Enter 选中，Home/End 首尾；show-checkbox 下 Space 切换勾选而非选中；OKR 根节点 ← 进入左子树，左树节点镜像。节点带 role=treeitem / aria-expanded / aria-selected / aria-level / aria-checked（仅 show-checkbox 时输出，含 mixed）/ aria-setsize / aria-posinset，焦点环可用 --okr-focus-color / --okr-focus-width 定制 |
OkrTreeViewport 的 API
<OkrTreeViewport> 的 props / 方法见画布缩放一节。