Ordo UI
组件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——

源码

packages/ui/src/components/tree-view.tsx
"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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

通用树:role=tree/treeitem、roving tabindex、方向键/Home/End、受控/非受控展开、禁用节点;exec-tree 是执行领域预设,不复用本件。