树形视图

使用可展开分支、平滑的模糊过渡和键盘导航浏览嵌套文件夹与结构化内容。

安装

你可以使用我们的 CLI 或手动添加树形视图:

已支持深色模式,此 组件 会自动使用 BoardUI 的语义设计变量。 设置主题切换.

CLI 将组件源(及其内部依赖项)复制到您的项目中并安装任何所需的 npm 包。

npx boardui@latest add tree-view

使用共享 UI 包或自定义导入别名? 配置您的安装路径 在运行 CLI 之前。复制粘贴示例使用默认导入。

受控状态与数据驱动

使用以下属性在自己的状态中管理展开和选择 expandedKeys 和 selectedKeys。使用 TreeViewCollection 以递归渲染嵌套数据。每个项都需要唯一且稳定的 id.

分支展开和折叠时具有平滑的高度、淡入淡出及模糊过渡。退出的行会立即从键盘导航中移除,减少动态效果设置会禁用动画。

Workspace

Selected: logo

import { useState } from "react";import type { Key, Selection } from "react-aria-components";import { TreeView, TreeViewCollection, TreeViewItem } from "@/components/base/tree-view/tree-view"; interface FileNode { id: string; name: string; children?: FileNode[];} const files: FileNode[] = [ { id: "design", name: "Design", children: [ { id: "logo", name: "Logo.svg" }, { id: "colors", name: "Colors.fig" }, ] }, { id: "notes", name: "Project notes.md" },]; function renderFile(item: FileNode) { return ( <TreeViewItem id={item.id} label={item.name}> <TreeViewCollection items={item.children ?? []}>{renderFile}</TreeViewCollection> </TreeViewItem> );} export function Example() { const [expandedKeys, setExpandedKeys] = useState<Set<Key>>(new Set(["design"])); const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set(["logo"])); return ( <TreeView aria-label="Workspace files" items={files} expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys} selectedKeys={selectedKeys} onSelectionChange={setSelectedKeys} > {renderFile} </TreeView> );}

多选

套装 selectionMode="multiple" 以独立切换各项。按住 Shift 可使用键盘选择范围。默认是单选;使用 selectionMode="none" 与 onAction 来创建仅执行操作的树。

2 items selected

<TreeView aria-label="Documents to share" selectionMode="multiple" defaultExpandedKeys={["documents"]} defaultSelectedKeys={["overview", "guidelines"]}> <TreeViewItem id="documents" label="Documents" trailingContent="3 files"> <TreeViewItem id="overview" label="Overview.md" /> <TreeViewItem id="guidelines" label="Guidelines.md" /> <TreeViewItem id="changelog" label="Changelog.md" /> </TreeViewItem></TreeView>

尺寸、图标与状态

使用 size="sm" 用于紧凑行,以及 showGuides={false} 以隐藏引导线。分支会自动显示文件夹图标;将 Remix Icon 组件传入 图标 或 expandedIcon 来自定义它们。禁用项阻止交互,而 renderEmptyState 用于提供空状态提示。

No matching files.
import { RiFolder3Line } from "@remixicon/react"; <TreeView aria-label="Repository files" size="sm" showGuides={false}> <TreeViewItem id="index" label="index.tsx" /> <TreeViewItem id="private" label="Private files" isDisabled trailingContent="Restricted" /> <TreeViewItem id="archive" label="Archive" icon={RiFolder3Line} trailingContent="Empty" /></TreeView> <TreeView aria-label="Search results" renderEmptyState={() => "No matching files."}> {[]}</TreeView>

从右向左

使用以下组件设置区域语言 DirectionProvider。缩进、引导线、展开图标和水平键盘导航均遵循阅读方向。

import { DirectionProvider } from "@/components/foundations/direction/direction";import { TreeView, TreeViewItem } from "@/components/base/tree-view/tree-view"; <DirectionProvider locale="ar"> <TreeView aria-label="ملفات المشروع" defaultExpandedKeys={["project"]}> <TreeViewItem id="project" label="المشروع"> <TreeViewItem id="design" label="التصميم"> <TreeViewItem id="logo" label="الشعار.svg" /> </TreeViewItem> <TreeViewItem id="notes" label="الملاحظات.md" /> </TreeViewItem> </TreeView></DirectionProvider>

键盘导航

按 Tab 进入树,使用上、下箭头在可见项间移动。右箭头展开分支或移至第一个子项;左箭头折叠分支或返回父项。Home 和 End 跳至第一个和最后一个可见项。输入标签可查找对应项,按空格键进行选择。

为每个树提供 aria-label 或 aria-labelledby。将 RTL 区域包裹在 BoardUI 的 DirectionProvider 并设置适当的区域语言;展开图标、缩进和水平按键会自动遵循方向。