Tree

Tree 用于展示文件目录、组织结构、分类层级等嵌套数据。组件提供数据驱动的高层 Tree、可完全自定义渲染的 TreeRoot / TreeItem，以及面向大数据量的 TreeVirtualizer。

import { Tree, TreeItem, TreeRoot, TreeVirtualizer } from '@skyroc/web-ui';

何时使用

• 需要展示父子层级结构，如目录、菜单、分类、权限树。
• 需要在层级节点上进行单选或多选。
• 需要自定义节点内容，如图标、状态、徽标或操作区。
• 数据量较大且展开后节点很多时，使用 TreeVirtualizer。

基础用法

通过 items 传入树数据。每个节点至少需要 value 和 label，有子节点时使用 children。

<Tree items={items} defaultExpanded={['components']} defaultValue="button" />

多选

设置 multiple 后，value 和 defaultValue 使用字符串数组。默认 selectionBehavior="toggle"，点击已选节点会取消选择。

<Tree multiple items={items} value={value} onValueChange={nextValue => setValue(nextValue as string[])} />

自定义渲染

通过 renderItem 自定义节点内容。回调会收到当前节点、展开状态、选中状态、半选状态以及树级操作方法。

<Tree
  items={items}
  renderItem={({ item, isExpanded, hasChildren }) => (
    <>
      {hasChildren ? <FolderIcon open={isExpanded} /> : <FileIcon />}
      <span>{item.data.label}</span>
    </>
  )}
/>

虚拟滚动

TreeVirtualizer 适合展开后节点数量较多的场景。需要设置 height，并通过 itemSize 提供预估行高。

<TreeVirtualizer height={300} itemSize={36} items={items} />

选择传播

Tree 支持父子节点选择联动：

<Tree multiple allowParentSelect propagateSelect bubbleSelect items={items} />

展开行为

defaultExpanded 设置非受控初始展开项，expanded + onExpandedChange 用于受控展开。toggleBehavior="single" 会让同层路径保持单展开。

<Tree expanded={expanded} toggleBehavior="single" onExpandedChange={setExpanded} />

API

Tree

高层数据驱动组件。继承 TreeRoot 的状态能力，并自动渲染 TreeItem。

TreeRoot

底层根组件，负责状态、上下文和无序列表语义，节点渲染完全交给 children 函数。

TreeItem

底层节点组件，必须放在 TreeRoot 或 TreeVirtualizer 上下文中使用。

TreeVirtualizer

虚拟滚动树组件。继承 Tree 状态能力，并使用 @tanstack/react-virtual 只渲染可视区域节点。

类型