API
API
react-okr-tree 的完整 API 表：42 个 props、字段映射、14 个回调、28 个 ref 方法、渲染定制与组合组件。
以下六张表由 packages/react-okr-tree/shared/api.ts 单一来源渲染——库侧的防漂移测试（tests/api-surface.spec.tsx）断言 Methods 表与真实的 OkrTreeHandle 一致，README 的 API 段落读的也是同一份数据。
命名规则是机械转换：kebab-case → camelCase、事件 → onXxx 回调、插槽 → render props、v-model:x → x + onXxxChange。currentLableClassName 与 showCollapsable 两处原版拼写错误刻意保留。完整差异见从 vue3-okr-tree 迁移。
Attributes
与 vue3-okr-tree 逐项对齐（含原版拼写）；className / style / children 为 React 侧新增。
| prop | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| data | 展示数据（数组，支持多根） | array | — | — (必填) |
| direction | 树的展开方向 | string | horizontal / vertical | vertical |
| onlyBothTree | 飞书 OKR 模式：子树在根节点左右两边展开。只在 direction="horizontal" 时有效，且必须提供 leftData | boolean | — | false |
| leftData | 左子树的数据，仅在 onlyBothTree 模式启用 | array | — | — |
| labelWidth | 节点宽度。number 单位 px；string 直接作为 style.width | string / number | — | auto |
| labelHeight | 节点高度。number 单位 px；string 直接作为 style.height | string / number | — | auto |
| labelClassName | 节点 className 的回调或固定串。入参是内部 TreeNode 实例（源数据在 node.data） | Function(node) / string | — | — |
| currentLableClassName | 当前选中节点的 className（保留原版拼写） | Function(node) / string | — | — |
| showCollapsable | 节点是否可展开/折叠（显示 +/- 圆盘）。为 false 时组件强制全部展开（原版行为） | boolean | — | false |
| accordion | 手风琴：用户展开某节点时自动收起同级兄弟。只作用于交互展开（按钮、点卡片、键盘）；expandNode 与受控 expandedKeys 不受互斥限制 | boolean | — | false |
| expandOnClickNode | 点击卡片内容切换展开。叶子只选中不切换；OKR 根节点只切右侧子树 | boolean | — | false |
| showCheckbox | 复选框模式：卡片前渲染勾选框，父子联动半选态（checkStrictly 可关闭）。OKR 左右两树勾选独立维护，方法按 key 对两树同时生效 | boolean | — | false |
| checkStrictly | 父子不联动：勾选只作用于自身，无半选传播 | boolean | — | false |
| defaultCheckedKeys | 初始勾选的 key 数组（需 nodeKey）。运行时变更 = 先清空再按新列表应用；data 重建后不恢复 | array | — | — |
| draggable | 拖拽换父级（HTML5 DnD）：可放到目标节点的 prev / inner / next。移动会同步修改源数据 children，inner 时目标自动展开。禁止放进自身或其子树；OKR 跨左右树默认禁止 | boolean | — | false |
| allowDrag | 返回 false 禁止拖动该节点（disabled 节点恒不可拖） | Function(node) | — | — |
| allowDrop | 返回 false 禁止该放置位置；跨左右树默认禁止，明确返回 true 可放开 | Function(draggingNode, dropNode, type) | type: 'prev' / 'inner' / 'next' | — |
| connector | 连接线渲染模式。svg 只替换线条渲染，布局与 css 模式完全一致，随展开收起与尺寸变化自动重绘 | string | css / svg | css |
| connectorShape | svg 模式的路径形状（仅 connector="svg" 生效） | string | curve / orthogonal / straight | curve |
| unstyled | 去掉卡片外观（背景/边框/圆角/阴影，含 hover），保留布局与连接线。刻意不动 padding / 字号 / 文字色——改 padding 会移动节点盒、牵动连接线几何 | boolean | — | false |
| showNodeNum | 折叠时在圆盘内显示子节点数（只计未被 filter 隐藏的可见子节点） | boolean | — | false |
| defaultExpandAll | 默认全部展开（仅在 showCollapsable 为 true 时有意义） | boolean | — | false |
| renderContent | 节点内容区渲染函数。React 版不传 h（D1），返回 ReactNode；入参 node 为内部 TreeNode（源数据在 node.data，文本在 node.label） | Function(node) | — | — |
| nodeBtnContent | 展开按钮内容渲染函数，参数约定同上 | Function(node) | — | — |
| nodeComponent | 节点内容组件，以 { node, data } 为 props。优先级 renderNode > nodeComponent > renderContent | ComponentType | — | — |
| props | 字段映射配置，见下表 | object | — | 见下表 |
| nodeKey | 节点唯一标识字段名（整棵树应唯一） | string | — | — |
| defaultExpandedKeys | 默认展开的 key 数组（需 nodeKey）；OKR 下左右两树同时生效 | array | — | — |
| currentNodeKey | 初始选中节点的 key（需 nodeKey，单向） | string / number | — | — |
| filterNodeMethod | 节点筛选方法，返回 false 隐藏。filter('') 时同样执行，需对空值返回 true 才能恢复全部显示 | Function(value, data, node) | — | — |
| animate | 展开过渡动画。系统开启「减弱动态效果」时自动按关闭处理 | boolean | — | false |
| animateName | 动画名 | 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 |
| animateDuration | 动画时长 ms | number | — | 200 |
| alignRoot | OKR 模式下按左右子树自动对齐根节点（纯 CSS），展开/收起不改变根位置；false 回退原版行为 | boolean | — | true |
| theme | 内置主题或自定义名字（自定义需自写 .okr-theme-{name} 变量）。所有外观取值均可用 --okr-* 覆盖 | string | default / feishu / dark / auto / minimal / colorful | default |
| expandedKeys + onExpandedKeysChange | 受控展开态（需 nodeKey）：列表内展开、其余收起。未传 expandedKeys 时为非受控（默认行为）。只传值不传回调 = 锁定不可交互改 | array / Function(keys) | — | — |
| currentKey + onCurrentKeyChange | 受控选中态（需 nodeKey），null 表示无选中 | string / number / null / Function(key) | — | — |
| lazy | 懒加载：初始 data 中没有 children（或为空数组）的节点视为未加载，首次展开时调 load | boolean | — | false |
| load | 懒加载取数函数。resolve(children) 后子节点写入源数据 children 并展开；reject() 或抛错回到折叠态、可重试。node.isLeftChild 可区分 OKR 左树 | Function(node, resolve, reject?) | — | — |
| deepWatch | data 深度侦听开关（创建期生效）：true 时每次渲染做结构脏检查以接住原地变更；false 只响应引用变化。React 下的能力边界见 requirements R2 / D7 | boolean | — | true |
| className / style | 透传到 .org-chart-container 根容器 | string / CSSProperties | — | — |
| children | 传函数时等价 renderNode（对应源项目 #default 插槽） | ReactNode | Function(scope) | — | — |
props（字段映射配置）
通过 props prop 传入。
| 字段 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| label | 节点文本：属性名或函数 | string / function(data, node) | label |
| children | 子节点属性名 | string | children |
| disabled | 禁用字段（真实生效：is-disabled、不选中、不触发 onNodeClick、不可拖） | string / function(data, node) | disabled |
| isLeaf | 叶子字段：lazy 下未加载节点据此判定，标记为叶子则不显示按钮、不触发 load | string / function(data, node) | — |
Events（回调 props）
node 均为内部 TreeNode 实例。源项目回调的第三参 nodeComponent（组件实例）在 React 无对应概念，已移除（D2）；DOM 定位用 handle.getNodeEl()。
| 回调 | 说明 | 参数 |
|---|---|---|
| onNodeClick | 节点被点击（同时设置选中态） | (data, node) |
| onNodeExpand | 节点展开 | (data, node) |
| onNodeCollapse | 节点收起 | (data, node) |
| onNodeContextMenu | 节点右键。仅当传入本回调时才阻止浏览器默认菜单。事件参数是 React 合成事件，原生事件取 event.nativeEvent（D11） | (event, data, node) |
| onExpandedKeysChange | 受控展开态变化时触发（仅传入 expandedKeys 时） | (keys) |
| onCurrentKeyChange | 受控选中态变化时触发（仅传入 currentKey 时） | (key | null) |
| onCheck | 复选框被点击时触发（仅 showCheckbox；程序化 setCheckedKeys 不触发） | (data, { checkedNodes, checkedKeys, halfCheckedNodes, halfCheckedKeys }) |
| onCheckChange | 节点勾选态变化时触发（仅 showCheckbox；每个受影响节点各一次，含联动与 setCheckedKeys 批量变更） | (data, checked, indeterminate) |
| onNodeDragStart | 开始拖拽（仅 draggable） | (node, event) |
| onNodeDragEnter | 拖拽进入某节点 | (draggingNode, dropNode, event) |
| onNodeDragLeave | 拖拽离开某节点 | (draggingNode, dropNode, event) |
| onNodeDragOver | 悬停在有效放置区内 | (draggingNode, dropNode, event) |
| onNodeDragEnd | 拖拽结束；未完成放置时后两参为 null | (draggingNode, dropNode | null, dropType | null, event) |
| onNodeDrop | 完成放置（源数据已在 moveNode 中同步） | (draggingNode, dropNode, dropType, event) |
Methods（通过 ref 调用）
通过 ref 拿到 OkrTreeHandle 调用。增删类方法会同步修改传入的源数据（与源项目一致）。入参普遍接受 key / data 对象 / TreeNode 实例三种形态。
| 方法 | 说明 | 参数 |
|---|---|---|
| filter | 触发过滤；onlyBothTree 下同时过滤左右子树。未设置 filterNodeMethod 时抛错 | (value) |
| updateKeyChildren | 用新数据替换 key 节点的全部子节点（需 nodeKey，缺失抛错） | (key, data) |
| getNode | 获取内部 Node。OKR 下右树优先，未命中回退左树；未设 nodeKey 时按 data 对象查不到 | (data) |
| getNodeEl | 取节点对应的 DOM 元素；未渲染/不可见时为 null | (data) |
| getNodeKey | 取节点用于列表 key 的值（nodeKey 字段或内部 $treeNodeId） | (node) |
| setCurrentNode | 按 Node 实例设置选中（需 nodeKey，缺失抛错） | (node) |
| setCurrentKey | 按 key 设置选中（需 nodeKey，缺失抛错）；传 null 取消高亮 | (key | null) |
| getCurrentKey | 当前选中 key；无选中返回 null（需 nodeKey，缺失抛错） | — |
| getCurrentNode | 当前选中节点的 data；无选中返回 null | — |
| remove | 删除节点。必须设 nodeKey，未设置时静默无效。会同步删除源数据中的对应项 | (data) |
| append | 追加子节点（省略 parent 则挂为根）。会同步写入源数据 children | (data, parentNode?) |
| insertBefore | 在参考节点前插入。同上会回写源数据 | (data, refNode) |
| insertAfter | 在参考节点后插入。同上 | (data, refNode) |
| expandAll | 展开全部（含左右两树）；lazy 下未加载节点先加载再展开 | — |
| collapseAll | 收起全部（含左右两树） | — |
| expandNode | 展开指定节点，默认连同祖先；OKR 根节点同时展开两侧；lazy 下先加载。返回 Node 或 null | (data, expandParent = true) |
| collapseNode | 收起指定节点；OKR 根节点同时收起两侧 | (data) |
| scrollToNode | 滚动到节点：默认先展开全部祖先、等待路径上的懒加载完成，再 scrollIntoView（居中，减弱动效时不用平滑）。返回是否完成 | (data, options?) options 为 ScrollIntoViewOptions + expand（默认 true） |
| getCheckedNodes | 勾选的 Node 实例列表（左右两树） | (leafOnly = false) |
| getCheckedKeys | 勾选的 key 列表（需 nodeKey；左右合并去重） | (leafOnly = false) |
| setCheckedKeys | 整体设置勾选（先清空；非 strictly 时带父子联动；OKR 左右同 key 同时生效） | (keys, leafOnly = false) |
| getHalfCheckedNodes | 半选节点实例列表 | — |
| getHalfCheckedKeys | 半选节点 key 列表（需 nodeKey；左右合并去重） | — |
| isChecked | 节点当前是否勾选；未找到为 false | (data) |
| moveNode | 移动到目标的 prev / inner / next，同步源数据；inner 时目标自动展开。禁止放进自身或其子树。成功返回 true | (data, target, type) |
| getVisibleNodes | 当前真正可见的节点（含 OKR 左树）：自身通过过滤且各级祖先已展开到它。折叠子树仍挂载在 DOM 中，所以不等于 DOM 里的节点数 | — |
| getNodePath | 顶层到目标的链路（含目标）。左树节点的链路留在左树内，不跨接到右树根；未命中返回空数组 | (data) |
| refreshData | React 版新增（D7）：源数据被原地改动而宿主没重渲染时，显式触发增量更新（等价 Vue 的 deep watch） | — |
| store / root | 数据仓库与虚拟根实例（源项目同样暴露，高级用法） | — |
渲染定制（对应源项目插槽）
源项目的具名插槽在 React 里是 render props，作用域参数形状保持一致。renderNode 与 renderContent 二选其一即可，插槽优先。
| prop | 对应源项目插槽 | 作用域参数 |
|---|---|---|
| renderNode（或 children 传函数） | #default | { node, data }，node 为内部 TreeNode |
| renderExpandBtn | #expand-btn | { node, data, expanded, side, loading }；side 为 right（常规/右子树）或 left（OKR 左子树）。showNodeNum 的折叠数字优先于它 |
| empty | #empty | data 为空数组时渲染在容器内 |
| renderToolbar（OkrTreeViewport） | #toolbar | { zoom, zoomIn, zoomOut, reset, fit } |
组合组件与键盘导航
OkrTreeGroup 让组内多棵 OKR 树的根节点水平坐标一致（替代源项目文档里「业务层手动量 DOM」）；OkrTreeViewport 提供画布缩放/平移/导出。键盘导航为所有树内置。
| 名称 | 类型 | 说明 |
|---|---|---|
| OkrTreeGroup / align | prop，boolean，默认 true | false 时各树独立排布 |
| OkrTreeGroup / refresh() | method | 手动重新测量（字体加载完成、外部样式变化等；组件已自动响应成员挂载/更新与尺寸变化） |
| OkrTreeGroup / children | — | 放置若干 <OkrTree onlyBothTree /> |
| OkrTreeViewport props | minZoom / maxZoom / zoomStep / zoom + onZoomChange / offset + onOffsetChange / wheelBehavior / toolbar / renderToolbar | 缩放范围与受控值；wheelBehavior：ctrl-zoom（默认，不劫持页面滚动）/ zoom / scroll |
| OkrTreeViewport methods | zoomIn / zoomOut / reset / fitToScreen(padding?) / centerNode / exportImage / getZoom / getOffset | 双击复位；fitToScreen 默认四周留 20px；centerNode 先展开祖先再对准视口中心 |
| exportImage(options) | method | { type: 'png' | 'svg', scale = 2, background, toPng?, toSvg? }。依赖可选 peer html-to-image；打包器下动态导入不可靠时用 toPng / toSvg 直接传入渲染函数 |
| 键盘导航 | — | Tab 进入，↑/↓ 在可见节点间移动，→ 展开或进入子节点，← 收起或回到父节点，Enter/Space 选中（showCheckbox 下 Space 切换勾选），Home/End 首尾；OKR 根节点 ← 进入左子树，左树节点镜像。节点带 role=treeitem 与 aria-level/expanded/selected/checked/disabled/setsize/posinset，焦点环用 --okr-focus-color / --okr-focus-width 定制 |
相关页面
- 数据类型与
OkrTree<T>泛型：泛型与类型推导 - 变更检测与源数据回写的机制：数据变更与源数据回写
- 受控语义与 ref 方法的使用建议：受控与非受控
- 外观相关 prop（
theme/unstyled/connector/ 动画）：主题与样式定制