CLI 将组件源(及其内部依赖项)复制到您的项目中并安装任何所需的 npm 包。
npx boardui@latest add tree-view使用共享 UI 包或自定义导入别名? 配置您的安装路径 在运行 CLI 之前。复制粘贴示例使用默认导入。
受控状态与数据驱动
使用以下属性在自己的状态中管理展开和选择 expandedKeys 和 selectedKeys。使用 TreeViewCollection 以递归渲染嵌套数据。每个项都需要唯一且稳定的 id.
分支展开和折叠时具有平滑的高度、淡入淡出及模糊过渡。退出的行会立即从键盘导航中移除,减少动态效果设置会禁用动画。
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 来创建仅执行操作的树。
<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 用于提供空状态提示。
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 并设置适当的区域语言;展开图标、缩进和水平按键会自动遵循方向。