常见问题

为什么页面是空白的？

依次检查：

1. 是否调用了 await sdk.loadData()。
2. Vue 中是否使用 OrgTreeProvider 包裹 OrgTree。
3. 数据是否包含唯一的 parentId: null 根节点。
4. fieldMap 是否与真实字段一致。
5. 容器是否已在 DOM 中挂载。
6. 浏览器控制台是否有接口或布局错误。

为什么节点重叠？

最常见原因是 layout.nodeSize 与自定义卡片真实尺寸不同。边框、padding 也会影响尺寸，建议卡片使用：

box-sizing: border-box;

并直接使用 node.width 和 node.height 设置样式。

为什么动态节点都有展开按钮？

动态模式无法看到完整后代关系。未配置 layout.isLeaf 时，默认所有节点都可能有孩子。

isLeaf: node => node.childCount === 0

推荐由接口返回 isLeaf 或 childCount。

为什么调用 setDirection() 后布局不对？

setDirection() 只更新方向和派发事件，不立即重算坐标：

sdk.setDirection('right')
await sdk.loadData()

为什么 highlight 没有自动改变卡片？

Core 的 highlight 和 visible 是业务状态字段，默认卡片不解释它们。在自定义 Vue 组件中注入 ORG_TREE_STATUS_KEY，或由业务响应式状态控制样式。

为什么权重分层在横向树里无效？

fieldMap.weight 只由 down 布局算法使用。right 方向按普通父子深度排列。

可以直接传嵌套 children 数据吗？

不可以。公开输入是平铺数组，父子关系通过 id/parentId 建立。业务自带的 children 字段会被原样保留，但不会作为布局输入。

可以有多个根节点吗？

当前布局面向单棵树。listToTree() 只选择第一个根候选，多根数据会导致其余分支不参与结果。请在接口层创建一个虚拟根节点或拆成多个实例。

收起后再次展开会重新请求吗？

动态模式会再次调用 api.loadChildren(nodeId)。SDK 会按 ID 合并去重，但不会阻止网络请求。接口成本较高时，在业务 API 层增加缓存。

如何搜索并定位节点？

Core 不维护文本搜索索引。先查询业务数据，再定位 DOM：

document
  .getElementById(`org-tree-node-${nodeId}`)
  ?.scrollIntoView({ block: 'center', inline: 'center' })

动态模式需要先展开目标节点的祖先路径。

能在 Nuxt/SSR 中使用吗？

只能在客户端挂载 Vue 或 Standalone 渲染层。使用 ClientOnly 或等价机制，避免在服务端访问 DOM。

为什么局部容器里画布高度超出？

当前 DomCanvas 的视口高度使用 100vh，适合全屏组织树。嵌入弹窗或局部面板时，需要在业务布局中约束外层溢出，或后续扩展画布高度配置。

pnpm test 为什么失败？

仓库当前没有配置测试框架，各包的 test script 仍是占位命令。提交代码至少运行受影响文件的 ESLint、相关构建和真实 demo；涉及核心算法时应补充可执行的最小验证用例。

包为什么安装不到？

三个 @org-tree/* 包目前尚未发布到公共 npm Registry。请从仓库执行 pnpm install 并通过 workspace 运行。发布完成前，不要把 pnpm add 当成现成的安装方式。