API

react-okr-tree 的完整 API 表：props、字段映射、回调、ref 方法、渲染定制、画布缩放与组合组件。

以下七张表由 packages/react-okr-tree/shared/api.ts 单一来源渲染——库侧的防漂移测试（tests/api-surface.spec.tsx）断言各表与真实实现（props / 回调 / ref 方法）一致。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` 只响应引用变化。与 `nodeKey` / `direction` / `onlyBothTree` 不同，它每次渲染即时读取，运行时切换即生效、无需重挂载。React 下的能力边界见 requirements R2 / D7	boolean	—	true
virtual	1.16.0 新增（创建期生效）。虚拟滚动：同层可见兄弟数 ≥ 阈值（50）的行只渲染视口内窗口，用等尺寸占位块保持布局与连接线逐像素等价。要求数字型 `labelWidth`（horizontal 布局还要求 `labelHeight`），auto 尺寸下达标行退回全量渲染并给出开发期警告；`scrollToNode` 与键盘漫游对窗口外目标先揭示再定位。运行时变更不生效，需绑 `key` 重挂载	boolean	—	false
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 }`

OkrTreeViewport（画布缩放）

React 版与源项目同名组件（1.16.0 对齐）。<OkrTreeViewport> 包裹一棵树，提供缩放、平移、适应窗口与导出图片；children 放树，renderToolbar 自定义工具栏。缩放与偏移可受控（zoom + onZoomChange / offset + onOffsetChange），未传时组件内部维护。

名称	类型 / 签名	说明
minZoom	prop，number，默认 0.2	最小缩放
maxZoom	prop，number，默认 4	最大缩放
zoomStep	prop，number，默认 1.2	每次 `zoomIn()` / `zoomOut()` / 滚轮一格的缩放系数（乘除）
zoom	prop，number，默认 undefined	受控缩放；未传时内部维护
onZoomChange	event，(zoom: number) => void	缩放变化回调，配合 `zoom` 受控
offset	prop，ViewportOffset，默认 undefined	受控平移偏移（`{ x, y }`）；未传时内部维护
onOffsetChange	event，(offset: ViewportOffset) => void	偏移变化回调，配合 `offset` 受控
wheelBehavior	prop，'ctrl-zoom' \| 'zoom' \| 'scroll'，默认 'ctrl-zoom'	滚轮行为：按住 Ctrl/⌘ 才缩放 / 始终缩放 / 交给页面滚动
toolbar	prop，boolean，默认 false	显示内置工具栏；传入 `renderToolbar` 时无需开启
renderToolbar	prop，(scope: ViewportToolbarScope) => ReactNode	自定义工具栏；scope 为 `{ zoom, zoomIn, zoomOut, reset, fit }`
children	prop，ReactNode	画布内容，通常放 `<OkrTree />` 或 `<OkrTreeGroup />`
className / style	prop，string / CSSProperties	容器附加类名与内联样式
zoomIn()	method	按 `zoomStep` 放大一次
zoomOut()	method	按 `zoomStep` 缩小一次
reset()	method	恢复初始缩放与偏移
fitToScreen(padding = 20)	method，padding?: number	缩放到内容完整可见并居中，四周留 `padding`
centerNode(data)	method，data: TreeNodeData，=> Promise<boolean>	滚动并平移使目标节点居中；目标不在已渲染窗口时先揭示
exportImage(options = {})	method，=> Promise<string>	导出为 PNG/SVG DataURL；`type` / `scale` / `background` / `toPng` / `toSvg` 见 `ExportImageOptions`（依赖可选 peer `html-to-image`）
getZoom()	method，=> number	当前缩放（受控值或内部值）
getOffset()	method，=> ViewportOffset	当前偏移的副本

组合组件与键盘导航

OkrTreeGroup 让组内多棵 OKR 树的根节点水平坐标一致（替代源项目文档里「业务层手动量 DOM」）；OkrTreeViewport 的画布 API 见上一张独立表。键盘导航为所有树内置。

名称	类型	说明
OkrTreeGroup / align	prop，boolean，默认 true	false 时各树独立排布
OkrTreeGroup / refresh()	method	手动重新测量（字体加载完成、外部样式变化等；组件已自动响应成员挂载/更新与尺寸变化）
OkrTreeGroup / children	—	放置若干 `<OkrTree onlyBothTree />`
键盘导航	—	Tab 进入，↑/↓ 在可见节点间移动，→ 展开或进入子节点，← 收起或回到父节点，Enter/Space 选中（showCheckbox 下 Space 切换勾选），Home/End 首尾；OKR 根节点 ← 进入左子树，左树节点镜像。节点带 `role=treeitem` 与 `aria-level/expanded/selected/checked/disabled/setsize/posinset`，焦点环用 `--okr-focus-color` / `--okr-focus-width` 定制