TreeView 树视图
浏览并选择具有父子层级的节点，同时支持展开和收起分支。
使用概览
适合使用
- 文件目录、组织结构或分类体系需要保留层级关系时。
不建议使用
- 项目之间没有父子关系，或层级过深需要专门导航页面时。
真实示例
文件目录树
默认展开源码目录并显示其中的文件节点。
正在加载示例…
安装
本地候选警告Registry 地址仅指向当前本地文档站；npm 包也只用于本地候选验证，尚未公开发布。
pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/tree-view.json基础用法
导入
import { TreeView } from "@richardqiu/quartz/tree-view";JSX
<TreeView aria-label="文件目录" nodes={[{ id: "src", label: "src", children: [{ id: "app", label: "app.tsx" }] }]} defaultExpandedIds={["src"]} expandLabel={(node, expanded) => `${expanded ? "收起" : "展开"}${node.label}`} />状态与控制摘要
默认
键盘焦点可见
已选择
加载中
已禁用
label · textactive · booleanAPI 参考
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
nodes | readonly TreeNode<Value>[] | 必填 | 提供具有唯一标识、标签与可选子节点的层级数据。 |
selectionMode | "single" | "multiple" | "single" | 决定树中选择一个节点还是多个节点。 |
组合结构
- 01
TreeView
键盘约定
- 方向键遍历可见层级，Home 与 End 移到边界，Enter 选择，左右键折叠或展开。
可访问性契约
- 漫游焦点遵循 WAI-ARIA tree 模式。
- 每个节点必须具有稳定、唯一且非空的 ID。