{
  "id": "tree-view",
  "type": "components",
  "status": "published",
  "name": {
    "zh": "树形控件",
    "en": "Tree View"
  },
  "aliases": [
    "树形列表",
    "文件树",
    "目录树",
    "树结构",
    "tree"
  ],
  "category": [
    "Data Display",
    "Navigation"
  ],
  "description": {
    "zh": "以嵌套分支展示层级结构的可展开列表，每层节点可折叠或展开，子节点缩进排布于父节点之下。适合文件目录、组织架构、分类体系等天然成树的数据；节点可单选或多选，展开状态与选中状态相互独立。",
    "en": "An expandable list that shows hierarchy as nested branches: each node folds or opens and its children indent underneath. Fits file directories, org charts and taxonomies. Nodes may be single- or multi-select, and expanded state stays independent of selection."
  },
  "use_when": [
    {
      "zh": "数据天然分层，如目录、组织架构、分类树",
      "en": "Data is naturally hierarchical — directories, org charts, taxonomies"
    },
    {
      "zh": "需要折叠分支以管理大量同级节点",
      "en": "Branches must fold to manage a large number of siblings"
    },
    {
      "zh": "层级关系本身是信息的一部分",
      "en": "The nesting itself is part of the information"
    }
  ],
  "avoid_when": [
    {
      "zh": "只有两层且每层几项，用 accordion 或分组列表",
      "en": "Two shallow levels with few items — accordion or grouped list is lighter"
    },
    {
      "zh": "层级是导航框架而非内容，用 sidebar 或 menu",
      "en": "Hierarchy is site chrome rather than content — use a sidebar or menu"
    },
    {
      "zh": "扁平长列表更适合，用 table 或 list",
      "en": "A flat long list serves better — use a table or list"
    }
  ],
  "tags": [
    "data-display",
    "navigation",
    "hierarchy"
  ],
  "api": [
    "role=\"tree\"",
    "role=\"treeitem\"",
    "aria-expanded"
  ],
  "variants": [
    {
      "id": "single-select",
      "name": {
        "zh": "单选树",
        "en": "Single select"
      },
      "note": {
        "zh": "同时只有一个节点被选中，常配合详情面板",
        "en": "One node selected at a time, often feeding a detail pane"
      }
    },
    {
      "id": "multi-select",
      "name": {
        "zh": "多选树",
        "en": "Multi select"
      },
      "note": {
        "zh": "可勾选多个节点，父节点支持半选态",
        "en": "Nodes checkable in batches, parents exposing an indeterminate state"
      }
    },
    {
      "id": "file-tree",
      "name": {
        "zh": "文件树",
        "en": "File tree"
      },
      "note": {
        "zh": "带类型图标的目录树，最常见的产品形态",
        "en": "Directory tree with type icons — the familiar product form"
      }
    }
  ],
  "anatomy": [
    "树容器（Tree）",
    "树节点（Treeitem）",
    "展开指示（Twisty）",
    "子层级（Group）"
  ],
  "framework_names": [
    {
      "framework": "ARIA APG",
      "name": "Tree View",
      "url": "https://www.w3.org/WAI/ARIA/apg/patterns/treeview/"
    },
    {
      "framework": "Radix Primitives",
      "name": "Collapsible",
      "url": "https://www.radix-ui.com/primitives/docs/components/collapsible"
    },
    {
      "framework": "MUI",
      "name": "TreeView",
      "url": "https://mui.com/material-ui/react-tree-view/"
    }
  ],
  "playground": {
    "task": {
      "zh": "展开与折叠若干分支，用方向键在节点间移动并选中一个深层节点。",
      "en": "Expand and collapse branches, move with arrow keys and select a deep node."
    },
    "checks": [
      {
        "zh": "展开状态与选中状态相互独立",
        "en": "Expanded state and selected state are independent"
      },
      {
        "zh": "键盘可在父子与兄弟节点间连续移动",
        "en": "Keyboard focus walks parents, children and siblings in order"
      }
    ]
  },
  "applicable_styles": [
    "brutalism",
    "editorial",
    "neumorphism",
    "minimalism",
    "flat-design",
    "swiss-style",
    "neobrutalism",
    "art-deco"
  ],
  "related": [
    {
      "id": "accordion",
      "relation": "alternative_to"
    },
    {
      "id": "sidebar",
      "relation": "used_with"
    },
    {
      "id": "menu",
      "relation": "similar_to"
    }
  ],
  "confusable": [
    {
      "id": "accordion",
      "note": {
        "zh": "accordion 是并列分区的开合，tree-view 表达任意深度的父子层级",
        "en": "Accordion opens sibling sections; tree-view expresses parent-child nesting at any depth"
      }
    },
    {
      "id": "menu",
      "note": {
        "zh": "menu 用于命令与导航动作，tree-view 用于浏览并选择层级数据",
        "en": "Menu issues commands and navigation; tree-view browses and selects hierarchical data"
      }
    }
  ],
  "disambiguation": {
    "zh": "「树」有时也指思维导图或组织架构图；本词条专指可展开、可选择的列表式树形控件。",
    "en": "Tree may also mean a mind map or org chart; this entry covers the expandable, selectable list control."
  },
  "demo": {
    "component": "tree-view",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "sources": [
    {
      "name": "ARIA APG — Tree View",
      "url": "https://www.w3.org/WAI/ARIA/apg/patterns/treeview/"
    },
    {
      "name": "WAI-ARIA — tree role",
      "url": "https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/tree_role"
    },
    {
      "name": "Material Design — Lists",
      "url": "https://m3.material.io/components/lists/overview"
    }
  ],
  "implementation": {
    "css": [
      "padding-left",
      "border-left",
      "transform"
    ],
    "notes": {
      "zh": "子层级用递归缩进（padding-left 或 margin-left）表达深度，也可用竖向参考线辅助阅读。展开指示是小三角或加减号，旋转或切换图标表达状态；折叠时隐藏子树但保留 DOM 语义。键盘遵循 roving tabindex，方向键在可见节点间移动。",
      "en": "Show depth with recursive indent (padding-left or margin-left), optionally with guide rules. The twisty is a small triangle or plus/minus that rotates or swaps with state; collapsed subtrees hide visually while keeping tree semantics. Use a roving tabindex and let arrows walk visible nodes."
    }
  },
  "prompts": {
    "basic": {
      "zh": "创建一个树形控件，展示可展开折叠的层级节点，并支持选中某个节点。",
      "en": "Create a tree view of expandable hierarchical nodes with node selection."
    },
    "design": {
      "zh": "设计树形控件。要求：子节点缩进对齐父节点；展开指示清晰且状态可辨；选中行有高亮；层级过深时缩进收敛；空分支有说明；深浅色主题一致。",
      "en": "Design a tree view. Requirements: children indent under parents; the twisty is legible across states; the selected row highlights; indent stays readable when nesting goes deep; empty branches explain themselves; consistent light and dark themes."
    },
    "implementation": {
      "zh": "用 React + Tailwind 实现树形控件：数据为嵌套节点数组，递归渲染 role=\"tree\" / role=\"treeitem\"；节点带 aria-expanded，容器 aria-multiselectable 视需求而定；roving tabindex + 方向键（上/下/左/右）控制焦点，Enter 或 Space 选中。",
      "en": "React + Tailwind tree view: render a nested node array recursively into role=\"tree\" and role=\"treeitem\"; nodes carry aria-expanded and the container takes aria-multiselectable as needed; a roving tabindex with arrow keys (up/down/left/right) drives focus and Enter or Space selects."
    },
    "agent": {
      "zh": "在当前项目中实现树形控件（Tree View）组件。\n先检查现有列表、折叠与 Design Token，优先复用缩进、图标与高亮样式。\n用途：文件目录、组织架构、分类体系。\n要求：\n- 嵌套节点可展开折叠，展开态与选中态独立\n- role=tree / treeitem，aria-expanded 正确标注\n- 键盘可在节点间连续移动并选中\n- 尊重 prefers-reduced-motion，深浅色一致\n- 不新增依赖\n完成后运行项目现有检查，并列出修改的文件。",
      "en": "Implement a Tree View component in the current project.\nInspect existing lists, collapsibles and design tokens first and reuse indent, icon and highlight styles.\nUsage: file directories, org charts and taxonomies.\nRequirements:\n- Nested nodes expand and collapse; expanded state is independent of selection\n- role=tree / treeitem with correct aria-expanded\n- Keyboard focus walks nodes continuously and can select\n- Respect prefers-reduced-motion; consistent light and dark themes\n- No new dependencies\nRun the existing project checks when done and list the modified files."
    }
  }
}