树形列表 · TreeList

树形列表用于表格与列表场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

树形列表 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
树形列表 · 包含图标 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
树形列表 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
树形列表 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
树形列表 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
树形列表 · 样式变化 / 样式 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Tree List

An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.

使用建议

Provide meaningful labels and icons for each node to make the hierarchy easy to scan.
Pre-expand important branches so users see key content immediately.
Leaf rows reserve space for a chevron column whenever the tree has any expandable item to line up under; only a fully flat tree (no expandable items at all) renders its rows flush. Rely on this rather than nudging indentation with custom CSS.
避免：Nest more than 4–5 levels deep; flatten the structure or use a different pattern.
避免：Use a tree for flat, non-hierarchical data; use a List instead.

主题 API

{
  "targets": [
    {
      "className": "astryx-tree-list",
      "visualProps": [
        "density",
        "variant"
      ]
    },
    {
      "className": "astryx-tree-list-item",
      "visualProps": [
        "density"
      ],
      "states": [
        "selected",
        "disabled"
      ]
    },
    {
      "className": "astryx-tree-list-chevron",
      "states": [
        "state"
      ]
    },
    {
      "className": "astryx-tree-list-item-label",
      "states": [
        "selected"
      ]
    },
    {
      "className": "astryx-tree-list-guide"
    }
  ],
  "vars": [
    {
      "name": "--tree-list-indent",
      "description": "每级缩进步长。每个嵌套层级的行按此距离缩进，引导线随之对齐。在 `tree-list` 目标上设置以调整该度量（例如用 `var(--spacing-5)` 获得更宽的缩进）。",
      "default": "var(--spacing-4)"
    },
    {
      "name": "--tree-list-row-gap",
      "description": "相邻行之间的垂直间距。默认 `2px`（var(--spacing-0-5)）提供细微的分隔；在 `tree-list` 目标上设置以加宽或关闭间距。连接引导线会自动跨越该间距（线保持连续）且不会超出最后一行，因此无需调整引导线高度。",
      "default": "var(--spacing-0-5)"
    }
  ]
}

Tree List

树列表容器。接受 items 数据和渲染配置。展开状态在内部管理。

属性	类型	默认值	说明
items *	TreeListItemData[]		递归树项数据。每项有 id、label、可选 children 数组和可选 isExpanded 布尔值用于设置初始状态。
density	'compact' \| 'balanced' \| 'spacious'	'balanced'	项目的间距密度。
variant	'lineGuides' \| 'noGuides'	'lineGuides'	层级引导线的视觉呈现。lineGuides 显示连接线；noGuides 隐藏连接线并保留缩进。与 density 正交。
header	ReactNode		标题内容，通过 aria-labelledby 与树关联。
xstyle	StyleXStyles		用于布局自定义的 StyleX 样式。必须是 stylex.create() 值。

组件结构

Tree list: Container that presents the hierarchical tree.
Header: Caller-provided content that visibly names the tree.
Item: Painted row for one node in the hierarchy.
Chevron: Expand and collapse control rendered for an Item with children.
Chevron glyph: Directional symbol rendered by Icon inside a Chevron.
Item label: Primary content that identifies an Item.
Item description: Secondary text rendered below an Item label.
Start content: Caller-provided content rendered before an Item label.
End content: Caller-provided content rendered after an Item label.
Guide: Connector line that shows parent-child relationships.

完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

npm install @heroicons/react@2.2.0