# 树形列表 · TreeList

- 页面: https://jiguang132.com/zh/resources/astryx/docs/tree-list
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

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

## 安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **树形列表 · 综合展示 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

```json
{
  "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.


## 完整示例的额外依赖

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

```bash
npm install @heroicons/react@2.2.0
```

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt