组件Navigation
TreeView
@mox-hub/ui 组件 · Navigation · canonical
tree-view@mox-hub/uiNavigationcanonicalsrc/components/tree-view.tsx变体演示tree-view
src
components
button.tsx
dialog.tsx
index.ts
package.json
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| nodes* | TreeNode[] | — | — |
| expandedIds* | string[] | — | — |
| defaultExpandedIds* | string[] | — | — |
| onExpandedChange* | (ids: string[]) => void | — | — |
| selectedId* | string | — | — |
| onSelect* | (node: TreeNode) => void | — | — |
| labels* | Partial<TreeViewLabels> | — | — |
| className* | string | — | — |
源码
"use client"
import {
useEffect,
useId,
useMemo,
useRef,
useState,
type KeyboardEvent as ReactKeyboardEvent,
type ReactNode,
} from "react"
import { ChevronDown, ChevronRight } from "lucide-react"
import { cn } from "../lib/utils"
import { RawButton } from "./raw/raw-button"
/**
* TreeView —— 通用树(原子层;治理方案 B13)。
*
* 文件树 / 权限树 / 分类树的共同骨架:递归渲染、展开收起、单选、禁用。
* 纯展示 + 受控/非受控双模:
* - `expandedIds` 传入即受控(状态归调用方),否则用 `defaultExpandedIds` 内部自持;
* - `selectedId` 只决定高亮与初始 roving 落点,点击/Enter 通过 `onSelect` 上报,
* 组件不私存选中态(单一真相源在消费方)。
*
* 键盘模型(APG tree view,修复审计对 exec-tree「每个 treeitem 都 tabIndex=0」的批评):
* - 整棵树只有一个 Tab 入口:roving tabindex(当前项 0,其余 -1);
* - ↑ / ↓ 在可见节点间移动;Home / End 到首 / 末可见节点;
* - → 展开折叠的父节点;已展开时进入第一个子节点;
* - ← 收起展开的父节点;否则回到父节点;
* - Enter / Space 选中当前节点(禁用节点不响应)。
* 禁用节点仍在方向键序列中(可聚焦、可越过),但不响应选中与展开/收起。
*
* 指针交互:点击行选中;点击行首折叠钮(或键盘 →/←)展开收起。折叠钮在 Tab 序列外
* (`tabIndex=-1`),避免树内出现第二个 tab 风暴;树的唯一 Tab 入口始终是 treeitem 本身。
*/
export interface TreeNode {
id: string
label: string
icon?: ReactNode
children?: TreeNode[]
disabled?: boolean
}
export interface TreeViewLabels {
/** 树整体无障碍名(默认「树」) */
tree: string
/** 展开钮可访问名(默认「展开 {label}」) */
expand: (label: string) => string
/** 收起钮可访问名(默认「收起 {label}」) */
collapse: (label: string) => string
}
export interface TreeViewProps {
nodes: TreeNode[]
/** 受控展开集合;传入后组件不再内部改态,只经 onExpandedChange 上报 */
expandedIds?: string[]
/** 非受控初始展开集合 */
defaultExpandedIds?: string[]
onExpandedChange?: (ids: string[]) => void
selectedId?: string
onSelect?: (node: TreeNode) => void
labels?: Partial<TreeViewLabels>
className?: string
}
const DEFAULT_LABELS: TreeViewLabels = {
tree: "树",
expand: (label) => `展开 ${label}`,
collapse: (label) => `收起 ${label}`,
}
function hasChildren(node: TreeNode): boolean {
return !!node.children && node.children.length > 0
}
/** 可见节点扁平序:展开态下的深度优先,供 roving tabindex 回退与首项推导 */
function collectVisibleIds(
nodes: TreeNode[],
expandedIds: Set<string>,
out: string[] = []
): string[] {
for (const node of nodes) {
out.push(node.id)
if (hasChildren(node) && expandedIds.has(node.id)) {
collectVisibleIds(node.children as TreeNode[], expandedIds, out)
}
}
return out
}
/** id → 节点索引:键盘 ArrowRight/Left 需要按 id 找回节点以调用受控回调 */
function indexNodes(
nodes: TreeNode[],
map: Map<string, TreeNode> = new Map()
): Map<string, TreeNode> {
for (const node of nodes) {
map.set(node.id, node)
if (node.children) indexNodes(node.children, map)
}
return map
}
/** 子 id → 父 id;受控折叠隐藏焦点节点时,用它找最近的可见祖先。 */
function indexParentIds(
nodes: TreeNode[],
map: Map<string, string> = new Map()
): Map<string, string> {
for (const node of nodes) {
for (const child of node.children ?? []) {
map.set(child.id, node.id)
}
if (node.children) indexParentIds(node.children, map)
}
return map
}
interface TreeNodeRowProps {
node: TreeNode
depth: number
expandedIds: Set<string>
selectedId?: string
tabbableId: string | null
labels: TreeViewLabels
selectable: boolean
onToggle: (node: TreeNode) => void
onSelect: (node: TreeNode) => void
onFocusNode: (id: string) => void
}
function TreeNodeRow({
node,
depth,
expandedIds,
selectedId,
tabbableId,
labels,
selectable,
onToggle,
onSelect,
onFocusNode,
}: TreeNodeRowProps) {
const groupId = useId()
const branch = hasChildren(node)
const expanded = branch && expandedIds.has(node.id)
const selected = selectedId === node.id
return (
<div
role="treeitem"
aria-label={node.label}
aria-level={depth + 1}
aria-expanded={branch ? expanded : undefined}
aria-selected={selectable ? selected : undefined}
aria-disabled={node.disabled || undefined}
aria-controls={expanded ? groupId : undefined}
tabIndex={tabbableId === node.id ? 0 : -1}
data-node-id={node.id}
data-depth={depth}
onFocus={(event) => {
// focus 会从子 treeitem / 行内按钮冒泡上来,只认本体聚焦
if (event.target === event.currentTarget) onFocusNode(node.id)
}}
onKeyDown={(event) => {
// 行内折叠钮自带按钮语义,选中只认 treeitem 本体
if (event.target !== event.currentTarget) return
if (event.key === "Enter" || event.key === " ") {
event.preventDefault()
if (!node.disabled) onSelect(node)
}
}}
className="group/tree-item min-w-0 outline-none"
>
<div
className={cn(
"flex h-control-sm min-w-0 cursor-pointer items-center gap-1 rounded-md pe-2 ps-1 text-sm text-foreground transition-colors pointer-coarse:min-h-11",
"hover:bg-muted hover:text-foreground",
"group-focus-visible/tree-item:outline-2 group-focus-visible/tree-item:outline-offset-1 group-focus-visible/tree-item:outline-accent-blue",
selected && "bg-accent text-accent-foreground",
node.disabled && "cursor-not-allowed opacity-50"
)}
onClick={(event) => {
if (node.disabled) return
const item = event.currentTarget.closest<HTMLElement>(
'[role="treeitem"]'
)
item?.focus()
onSelect(node)
}}
>
{branch ? (
<RawButton
type="button"
tabIndex={-1}
disabled={node.disabled}
aria-label={
expanded ? labels.collapse(node.label) : labels.expand(node.label)
}
onClick={(event) => {
event.stopPropagation()
const item = event.currentTarget.closest<HTMLElement>(
'[role="treeitem"]'
)
onToggle(node)
item?.focus()
}}
className="inline-flex size-5 shrink-0 items-center justify-center rounded-sm text-muted-foreground outline-none hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50 disabled:pointer-events-none pointer-coarse:size-11"
>
{expanded ? (
<ChevronDown aria-hidden="true" className="size-3.5" />
) : (
<ChevronRight
aria-hidden="true"
className="size-3.5 rtl:-scale-x-100"
/>
)}
</RawButton>
) : (
<span className="size-5 shrink-0 pointer-coarse:size-11" aria-hidden="true" />
)}
{node.icon ? (
<span
aria-hidden="true"
className="flex size-4 shrink-0 items-center justify-center text-muted-foreground [&>svg]:size-4"
>
{node.icon}
</span>
) : null}
<span className="min-w-0 truncate" title={node.label}>
{node.label}
</span>
</div>
{expanded ? (
<div role="group" id={groupId} className="ps-4">
{(node.children as TreeNode[]).map((child) => (
<TreeNodeRow
key={child.id}
node={child}
depth={depth + 1}
expandedIds={expandedIds}
selectedId={selectedId}
tabbableId={tabbableId}
labels={labels}
selectable={selectable}
onToggle={onToggle}
onSelect={onSelect}
onFocusNode={onFocusNode}
/>
))}
</div>
) : null}
</div>
)
}
function TreeView({
nodes,
expandedIds,
defaultExpandedIds,
onExpandedChange,
selectedId,
onSelect,
labels,
className,
}: TreeViewProps) {
const L: TreeViewLabels = { ...DEFAULT_LABELS, ...labels }
const controlled = expandedIds !== undefined
const [innerExpandedIds, setInnerExpandedIds] = useState<string[]>(
defaultExpandedIds ?? []
)
const expandedList = controlled ? expandedIds : innerExpandedIds
const expandedSet = useMemo(() => new Set(expandedList), [expandedList])
const nodeMap = useMemo(() => indexNodes(nodes), [nodes])
const parentMap = useMemo(() => indexParentIds(nodes), [nodes])
const visibleIds = useMemo(
() => collectVisibleIds(nodes, expandedSet),
[nodes, expandedSet]
)
const treeRef = useRef<HTMLDivElement>(null)
// 树内只有一个可 Tab 的 treeitem:最近聚焦项 → 选中项 → 首个可见项。
// 派生而非 effect 同步,折叠导致聚焦项不可见时会自动回退,不会留下孤立的 tabIndex=0。
const [focusedId, setFocusedId] = useState<string | null>(null)
const tabbableId =
focusedId && visibleIds.includes(focusedId)
? focusedId
: selectedId && visibleIds.includes(selectedId)
? selectedId
: (visibleIds[0] ?? null)
// #39:受控折叠可能把当前焦点节点整段卸载。若焦点已丢回 body(或仍在树内),
// 把焦点恢复到最近的可见祖先;用户在树外主动移焦时不抢焦点。
useEffect(() => {
if (!focusedId || visibleIds.includes(focusedId)) return
const active = document.activeElement
if (active !== document.body && !treeRef.current?.contains(active)) return
let ancestor = parentMap.get(focusedId)
while (ancestor && !visibleIds.includes(ancestor)) {
ancestor = parentMap.get(ancestor)
}
const targetId = ancestor ?? visibleIds[0]
if (!targetId) return
const target = Array.from(
treeRef.current?.querySelectorAll<HTMLElement>('[role="treeitem"]') ?? []
).find((element) => element.dataset.nodeId === targetId)
// focus 会触发 treeitem 的 onFocus → onFocusNode(targetId),无需在 effect 内再 setState。
target?.focus()
}, [focusedId, visibleIds, parentMap])
const toggleNode = (node: TreeNode) => {
if (node.disabled) return
const next = expandedSet.has(node.id)
? expandedList.filter((id) => id !== node.id)
: [...expandedList, node.id]
if (!controlled) setInnerExpandedIds(next)
onExpandedChange?.(next)
}
const selectNode = (node: TreeNode) => {
if (node.disabled) return
onSelect?.(node)
}
const handleTreeKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
const target = event.target as HTMLElement
const current = target.closest<HTMLElement>('[role="treeitem"]')
// 只在 treeitem 本体聚焦时接管;行内按钮保留自己的键盘语义
if (!current || target !== current) return
if (event.key === "Enter" || event.key === " ") return
const items = Array.from(
event.currentTarget.querySelectorAll<HTMLElement>('[role="treeitem"]')
)
const index = items.indexOf(current)
if (index === -1) return
const focusAt = (nextIndex: number) => {
const next = items[nextIndex]
if (!next) return
next.focus()
setFocusedId(next.dataset.nodeId ?? null)
}
const expanded = current.getAttribute("aria-expanded")
const disabled = current.getAttribute("aria-disabled") === "true"
const node = nodeMap.get(current.dataset.nodeId ?? "")
if (event.key === "ArrowDown") {
event.preventDefault()
focusAt(index + 1)
} else if (event.key === "ArrowUp") {
event.preventDefault()
focusAt(index - 1)
} else if (event.key === "Home") {
event.preventDefault()
focusAt(0)
} else if (event.key === "End") {
event.preventDefault()
focusAt(items.length - 1)
} else if (event.key === "ArrowRight") {
event.preventDefault()
if (!node) return
if (expanded === "false") {
// 禁用节点不接受展开,但焦点导航仍可继续
if (!disabled) toggleNode(node)
} else if (expanded === "true") {
const firstChild = items[index + 1]
if (firstChild && current.contains(firstChild)) focusAt(index + 1)
}
} else if (event.key === "ArrowLeft") {
event.preventDefault()
if (!node) return
if (expanded === "true") {
if (!disabled) toggleNode(node)
} else {
const parent = current.parentElement?.closest<HTMLElement>(
'[role="treeitem"]'
)
if (parent) {
parent.focus()
setFocusedId(parent.dataset.nodeId ?? null)
}
}
}
}
return (
<div
ref={treeRef}
role="tree"
aria-label={L.tree}
data-slot="tree-view"
className={cn("min-w-0 text-sm", className)}
onKeyDown={handleTreeKeyDown}
>
{nodes.map((node) => (
<TreeNodeRow
key={node.id}
node={node}
depth={0}
expandedIds={expandedSet}
selectedId={selectedId}
tabbableId={tabbableId}
labels={L}
selectable={onSelect !== undefined}
onToggle={toggleNode}
onSelect={selectNode}
onFocusNode={setFocusedId}
/>
))}
</div>
)
}
export { TreeView }
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
通用树:role=tree/treeitem、roving tabindex、方向键/Home/End、受控/非受控展开、禁用节点;exec-tree 是执行领域预设,不复用本件。