---
nav:
  title: 组件
  order: 1
group:
  title: Data Display
  order: 1
title: PisellHierarchicalSummaryList
order: 1
category: atom
---

## 1. 组件简介

**PisellHierarchicalSummaryList** 是一个「层级汇总列表」结构组件，用于统一「父级汇总 +
子级明细」的展示形态。每一行由「左侧标题区域」和「右侧数值区域」构成，支持多层级无限嵌套、展开/收起交互、父级聚合展示以及按层级精细化样式控制。

**典型场景：**

- 费用/统计类汇总展示：总金额 + 明细拆分
- 可解释性明细：结果值下钻查看规则/来源
- 分组信息与聚合：分组标题 + 分组内条目

## 2. 基本用法

### 2.1 最简单的层级展示

```tsx
import React from 'react';
import type { PisellHierarchicalSummaryListItem } from '@pisell/materials';
import { PisellHierarchicalSummaryList } from '@pisell/materials';

const items: PisellHierarchicalSummaryListItem[] = [
  {
    key: 'total',
    label: 'Total',
    value: '$65',
    children: [
      { key: 'product', label: 'Product', value: '$40' },
      { key: 'shipping', label: 'Shipping', value: '$15' },
      { key: 'tax', label: 'Tax', value: '$10' },
    ],
  },
];

export default () => {
  return (
    <PisellHierarchicalSummaryList
      items={items}
      defaultExpandedLevel={2}
    />
  );
};
```

### 2.2 带 N items 与提示信息

```tsx
import React from 'react';
import type { PisellHierarchicalSummaryListItem } from '@pisell/materials';
import { PisellHierarchicalSummaryList } from '@pisell/materials';

const items: PisellHierarchicalSummaryListItem[] = [
  {
    key: 'usage',
    label: 'Usage',
    value: '$120',
    children: [
      {
        key: 'messages',
        label: 'Messages',
        itemsCount: '3 items',
        value: '$60',
      },
      {
        key: 'storage',
        label: 'Storage',
        infoTooltip: 'Includes image and file storage.',
        value: '$40',
      },
      {
        key: 'others',
        label: 'Others',
        itemsCount: '2 items',
        value: '$20',
      },
    ],
  },
];

export default () => {
  return (
    <PisellHierarchicalSummaryList
      items={items}
      defaultExpandedLevel={2}
    />
  );
};
```

## 3. 高级用法

### 3.1 父级聚合展示（内置 sum）

当父级未显式传入 `value` 时，可以通过 `aggregate` 配置启用内置求和逻辑，将子级数值聚合到父级 value 区域中。

```tsx
import React from 'react';
import type { PisellHierarchicalSummaryListItem } from '@pisell/materials';
import {
  PisellHierarchicalSummaryList,
  type PisellHierarchicalSummaryListProps,
} from '@pisell/materials';

const items: PisellHierarchicalSummaryListItem[] = [
  {
    key: 'root',
    label: 'Order total',
    children: [
      { key: 'line-1', label: 'Items', value: 40 },
      { key: 'line-2', label: 'Shipping', value: 15 },
      { key: 'line-3', label: 'Tax', value: 10 },
    ],
  },
];

const aggregate: PisellHierarchicalSummaryListProps['aggregate'] = {
  mode: 'sum',
  getNumberValue: (item) =>
    typeof item.value === 'number' ? item.value : null,
  format: (sum) => `$${sum}`,
};

export default () => {
  return (
    <PisellHierarchicalSummaryList
      items={items}
      defaultExpandedLevel={2}
      aggregate={aggregate}
    />
  );
};
```

### 3.2 手风琴 + 层级样式配置

通过 `accordion`、`levelConfig` 可以实现同级只展开一个，同时为不同层级设置差异化背景、字号和颜色。

```tsx
import React from 'react';
import type {
  PisellHierarchicalSummaryListItem,
  PisellHierarchicalSummaryListLevelConfig,
} from '@pisell/materials';
import { PisellHierarchicalSummaryList } from '@pisell/materials';

const items: PisellHierarchicalSummaryListItem[] = [
  {
    key: 'fees',
    label: 'Fees',
    children: [
      {
        key: 'processing',
        label: 'Processing',
        itemsCount: '2 items',
        value: '$30',
        children: [
          { key: 'card', label: 'Card processing', value: '$20' },
          { key: 'wallet', label: 'Wallet processing', value: '$10' },
        ],
      },
      {
        key: 'platform',
        label: 'Platform',
        value: '$15',
      },
    ],
  },
];

const levelConfig: Record<number, PisellHierarchicalSummaryListLevelConfig> = {
  1: {
    rowStyle: { background: '#F5F5F5', padding: '8px 12px', borderRadius: 8 },
    labelTextStyle: { fontWeight: 700 },
  },
  2: {
    rowStyle: { padding: '4px 8px' },
    showDotSeparator: true,
  },
};

export default () => {
  return (
    <PisellHierarchicalSummaryList
      items={items}
      defaultExpandedLevel={2}
      accordion
      levelConfig={levelConfig}
    />
  );
};
```

### 3.3 自定义渲染 label / value

通过 `renderLabel` / `renderValue` 可以根据层级或聚合上下文进行更灵活的渲染，例如在顶层追加「N items」说明、对聚合值增加「Total」前缀等。

```tsx
import React from 'react';
import type {
  PisellHierarchicalSummaryListItem,
  PisellHierarchicalSummaryListProps,
} from '@pisell/materials';
import { PisellHierarchicalSummaryList } from '@pisell/materials';

const items: PisellHierarchicalSummaryListItem[] = [
  {
    key: 'summary',
    label: 'Summary',
    children: [
      { key: 'part-1', label: 'Part A', value: 20 },
      { key: 'part-2', label: 'Part B', value: 30 },
    ],
  },
];

const aggregate: PisellHierarchicalSummaryListProps['aggregate'] = {
  mode: 'sum',
  getNumberValue: (item) =>
    typeof item.value === 'number' ? item.value : null,
  format: (sum, { level }) =>
    level === 1 ? `Total $${sum}` : `$${sum}`,
};

const renderLabel: PisellHierarchicalSummaryListProps['renderLabel'] = (
  item,
  ctx,
) => {
  if (ctx.level === 1) {
    return <strong>{item.label}</strong>;
  }
  return item.label;
};

const renderValue: PisellHierarchicalSummaryListProps['renderValue'] = (
  item,
  ctx,
) => {
  if (ctx.aggregatedValue !== undefined) {
    return ctx.aggregatedValue;
  }
  return item.value ?? '—';
};

export default () => {
  return (
    <PisellHierarchicalSummaryList
      items={items}
      defaultExpandedLevel={2}
      aggregate={aggregate}
      renderLabel={renderLabel}
      renderValue={renderValue}
    />
  );
};
```

## 4. API

### 4.1 PisellHierarchicalSummaryListItem

- **label** `ReactNode`（必填）：行标题，最小字段。
- **value** `ReactNode`：右侧数值区域内容，支持 number/string/组合展示。
- **children** `PisellHierarchicalSummaryListItem[]`：子级数据，支持无限层级。
- **key** `React.Key`：稳定 key，建议显式传入保证展开态稳定。
- **hidden** `boolean`：是否隐藏该项。
- **order** `number`：排序权重，值越小越靠前。
- **itemsCount** `ReactNode`：N items 提示文案。
- **infoTooltip** `ReactNode`：Info icon 的 tooltip 内容。
- **extra** `ReactNode`：右侧 value 后的轻量操作区域。
- **rowStyle** `CSSProperties`：覆盖当前行样式。
- **rowClassName** `string`：覆盖当前行类名。

### 4.2 PisellHierarchicalSummaryListProps（关键字段）

- **items** `PisellHierarchicalSummaryListItem[]`：数据源。
- **expandedKeys** `React.Key[]`：受控展开项 keys。
- **defaultExpandedKeys** `React.Key[]`：默认展开项 keys（非受控）。
- **defaultExpandedLevel** `number`：默认展开层级，从 0 开始（0 表示仅显示顶层）。
- **onExpandedKeysChange** `(keys: React.Key[]) => void`：展开项变化回调。
- **accordion** `boolean`：手风琴模式，同一父级下仅保留一个展开项。
- **maxRenderLevel** `number`：最大渲染层级，超过层级不再渲染 children。
- **maxExpandLevel** `number`：最大可展开层级，超过层级不显示展开箭头。
- **indent** `number`：L2+ 层级缩进（px），可被 `levelConfig` 覆盖。
- **rowGap** `number`：行间距（px）。
- **levelConfig** `Record<number, PisellHierarchicalSummaryListLevelConfig>`：按层级配置样式与功能开关。
- **aggregate** `PisellHierarchicalSummaryListAggregateConfig`：聚合配置（如 sum）。
- **renderLabel** `(item, ctx) => ReactNode`：自定义 label 渲染。
- **renderValue** `(item, ctx) => ReactNode`：自定义 value 渲染。
- **className** `string`：根节点类名。
- **style** `CSSProperties`：根节点样式。

> 更多详细类型定义可在 `packages/materials/src/components/pisellHierarchicalSummaryList/types.ts` 中查看。 

