---
title: 开发文档
order: 3
category: atom
---

## 1. 组件基本信息

- **组件名称（英文）**：Hierarchical Summary List
- **建议导出组件名**：PisellHierarchicalSummaryList
- **组件编号**：pcp_dd_hierarchicalSummaryList_V1.0
- **组件类型**：Pro Components
- **组件分类**：Data Display
- **组件位置**：`packages/materials/src/components/pisellHierarchicalSummaryList`
- **设计稿节点**：Figma `fileKey=pM8Ho6d7kCMv9vIBvFHUlj`，`nodeId=14162:10727`

## 2. 组件需求点罗列

### 2.1 核心功能

- [ ] 支持无限层级递归渲染（items.children）
- [ ] 每行结构：左侧 label（可含元信息） + 右侧 value（可含 extra） + 有子级时展示展开/收起箭头
- [ ] 展开/收起：点击整行与点击箭头行为一致
- [ ] 展开态：支持受控（expandedKeys）与非受控（defaultExpandedKeys/defaultExpandedLevel）
- [ ] 支持手风琴模式（accordion，可选）
- [ ] 支持最大渲染层级 / 最大可展开层级

### 2.2 可读性规则

- [ ] 右侧 value 列固定右对齐，纵向对齐便于扫读
- [ ] label 可换行；value 不换行（保持对齐）

### 2.3 元信息与扩展

- [ ] 可选展示 `N items`（文案允许自定义，支持 ReactNode）
- [ ] 可选展示 info/help icon，支持 tooltip 内容（ReactNode）
- [ ] 支持右侧 value 后附加轻量操作（tag/pill/button 等）

### 2.4 样式与配置

- [ ] 按层级（level）独立配置：背景/边框/圆角/阴影/padding/gap
- [ ] 按层级独立配置文本样式：字号/字重/颜色（label/value）
- [ ] 按层级独立配置 icon 样式：info icon、箭头 icon（size/color）
- [ ] 按层级控制缩进 indent（以及是否显示 “·” 分隔符）
- [ ] 支持层级内分割线（开关 + 样式）

### 2.5 聚合

- [ ] 支持父级 value **外部直接传入**（item.value）
- [ ] 支持父级 value **内置聚合**（aggregate 配置：sum 等）

> 说明：设计文档提到“一行多列栅格”能力，本版本不支持（已确认）。

## 3. 组件描述

`PisellHierarchicalSummaryList` 是一个结构型“层级汇总列表”组件，专注于**层级展示 + 展开交互 + 聚合展示**能力，不绑定金额/订单/支付等业务语义。适用于费用构成、统计汇总、规则来源解释等场景。

## 4. 组件 API 设计

### 4.1 数据结构

```
interface PisellHierarchicalSummaryListItem {
  label: ReactNode;                 // 最小字段（必填）
  value?: ReactNode;                // 可选（ReactNode）
  children?: PisellHierarchicalSummaryListItem[];

  key?: React.Key;                  // 建议传入，保证展开态稳定
  hidden?: boolean;
  order?: number;

  itemsCount?: ReactNode;           // 例如 "N items" / "N 条"
  infoTooltip?: ReactNode;          // tooltip 内容
  extra?: ReactNode;                // value 后轻量操作

  rowStyle?: CSSProperties;
  rowClassName?: string;
}
```

### 4.2 Props

```
interface PisellHierarchicalSummaryListProps {
  items: PisellHierarchicalSummaryListItem[];

  // 展开态（受控/非受控）
  expandedKeys?: React.Key[];
  defaultExpandedKeys?: React.Key[];
  defaultExpandedLevel?: number; // 默认 0
  onExpandedKeysChange?: (keys: React.Key[]) => void;
  accordion?: boolean; // 默认 false

  // 层级限制
  maxRenderLevel?: number;
  maxExpandLevel?: number;

  // 样式与布局
  indent?: number; // 默认 16（作用于 L2+，可被 levelConfig 覆盖）
  rowGap?: number; // 默认 8
  levelConfig?: Record<number, PisellHierarchicalSummaryListLevelConfig>;

  // 自定义渲染与 key
  renderLabel?: (item, ctx) => ReactNode;
  renderValue?: (item, ctx) => ReactNode;
  getKey?: (item, ctx) => React.Key;

  // 聚合
  aggregate?: {
    mode?: 'none' | 'sum';
    getNumberValue?: (item) => number | null | undefined;
    format?: (sum, ctx) => ReactNode;
  };

  className?: string;
  style?: CSSProperties;
}
```

### 4.3 LevelConfig（按层级配置）

```
interface PisellHierarchicalSummaryListLevelConfig {
  indent?: number;
  showDotSeparator?: boolean;
  divider?: { show?: boolean; color?: string; style?: 'solid' | 'dashed' | 'dotted' };

  rowStyle?: CSSProperties;
  rowClassName?: string;

  labelTextStyle?: { fontSize?: number | string; fontWeight?: number | string; color?: string };
  valueTextStyle?: { fontSize?: number | string; fontWeight?: number | string; color?: string };

  infoIconStyle?: { size?: number; color?: string };
  expandIconStyle?: { size?: number; color?: string };
}
```

## 5. 组件模块拆解

### 5.1 目录结构（计划）

```
pisellHierarchicalSummaryList/
├── index.tsx
├── PisellHierarchicalSummaryList.tsx
├── PisellHierarchicalSummaryList.less
├── PisellHierarchicalSummaryList.test.tsx
├── types.ts
├── hooks/
│   ├── index.ts
│   └── useExpandedKeys.ts
├── components/
│   ├── index.tsx
│   └── Row.tsx
└── docs/
    ├── pisellHierarchicalSummaryList.md
    ├── pisellHierarchicalSummaryList.$tab-design.md
    ├── pisellHierarchicalSummaryList.$tab-dev.md
    └── pisellHierarchicalSummaryList.$tab-test.md
```

### 5.2 组件结构图

```
PisellHierarchicalSummaryList
└── Row (level=1)
    ├── Left: label + (itemsCount) + (info icon + tooltip)
    └── Right: value + (extra) + (expand icon when hasChildren)
        └── children (recursive, level+1, indented)
```

## 6. 组件实现方案

### 6.1 关键点

- **key 策略**：优先使用 `item.key`；未提供则由 `getKey` 或“层级路径”生成，确保 expandedKeys 稳定可复现。
- **展开态管理**：封装一个 `useExpandedKeys`，同时支持受控与非受控；`defaultExpandedLevel` 在初始化阶段计算并合并到默认展开 keys。
- **手风琴模式**：在同一父级下切换展开时，收起兄弟节点（基于 pathKeys 判断同级）。
- **聚合**：
  - 若 `item.value` 已提供：直接渲染；
  - 若未提供且 `aggregate.mode==='sum'`：对 children 使用 `getNumberValue` 提取 number 后求和，`format` 负责展示（例如 `$${sum}`）。
- **排版**：Left 允许换行；Right（value/extra）不换行，整体 `justify-content: space-between`，value 右对齐。

### 6.2 视觉基线（来自 Figma 节点）

- 容器 padding：20
- 行间距（gap）：8
- 典型缩进：16（L2+）
- 文本：16px/24px（Bold/Medium/Regular）
- 颜色：标题 #1B1B1B，蓝色值 #1570EF，灰 #667085

## 7. 通用性与可扩展性

- **value/label 均支持 ReactNode**：可承载复杂组合展示，不限制业务语义。
- **层级配置 levelConfig**：可用于 L1 强调（背景/字重/颜色），L2/L3 弱化（灰色、bullet 等）。
- **renderLabel/renderValue/extra**：为业务方保留最大扩展空间。

