Skip to content

Commit 1c15015

Browse files
lxfu1lxfu1
authored
docs: add waterfall component documentation (#3002)
1 parent 9cf6941 commit 1c15015

10 files changed

Lines changed: 159 additions & 24 deletions

File tree

‎packages/plots/src/core/constants/index.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -245,6 +245,11 @@ export const CONFIG_SHAPE = [
245245
type: 'line',
246246
extend_keys: EXTEND_KEYS,
247247
},
248+
{
249+
key: 'connector',
250+
type: 'connector',
251+
extend_keys: [],
252+
},
248253
{
249254
key: 'point',
250255
type: 'point',

‎packages/plots/src/core/plots/waterfall/adaptor.ts‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { flow, transformOptions, fieldAdapter } from '../../utils';
1+
import { flow, transformOptions, fieldAdapter, isObject, set } from '../../utils';
22
import { mark } from '../../adaptor';
33
import { START_KEY, END_KEY, WATERFALL_VALUE } from './constants';
44
import type { Adaptor } from '../../types';
@@ -69,5 +69,28 @@ export function adaptor(params: Params) {
6969
return params;
7070
};
7171

72-
return flow(transformData, link, mark, transformOptions)(params);
72+
/**
73+
* @description 连接线
74+
*/
75+
const connectorTransform = (params: Params) => {
76+
const { options } = params;
77+
const { data = [], connector } = options;
78+
if (!connector) return params;
79+
set(options, 'connector', {
80+
xField: connector.reverse ? ['x2', 'x1'] : ['x1', 'x2'],
81+
yField: connector.reverse ? ['y2', 'y1'] : ['y1', 'y2'],
82+
data: [
83+
{
84+
x1: data[0].x,
85+
y1: data[0][END_KEY],
86+
x2: data[data.length - 1].x,
87+
y2: data[data.length - 1][END_KEY],
88+
},
89+
],
90+
...(isObject(connector) ? connector : {}),
91+
})
92+
return params;
93+
};
94+
95+
return flow(transformData, link, mark, connectorTransform, transformOptions)(params);
7396
}

‎packages/plots/src/core/plots/waterfall/type.ts‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,10 @@
11
import type { Options, AttrStyle } from '../../types/common';
22

3-
export type WaterfallOptions = Omit<Options, 'xField' | 'children'> & {
3+
export type WaterfallOptions = Omit<Options, 'children'> & {
44
/**
55
* @title 连线样式
66
*/
77
linkStyle?: AttrStyle;
8-
/**
9-
* @title x轴字段
10-
*/
11-
xField?: string | string[];
128
children?: Array<WaterfallOptions & { zIndex?: number }>;
9+
connector?: Partial<Options> & { reverse?: boolean };
1310
};

‎packages/plots/src/core/types/common.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import type {
1010
LegendComponent,
1111
} from '@antv/g2';
1212

13-
export type Primitive = number | string | boolean | Date;
13+
export type Primitive = number | string | boolean | Date | string[];
1414

1515
export type FunctionEncodeSpec = (value: any, index?: number, array?: any[]) => Primitive;
1616

‎site/docs/components/plots/area.zh.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ order: 2
1010

1111
## 简介
1212

13-
面积图用于展示数据的连续变化趋势，适用于时间序列分析、数据对比等场景。
13+
面积图（Area）是一种以折线图为基础，将折线与坐标轴之间的区域用颜色或纹理填充的统计图表。它通过面积大小直观展示数据的变化趋势、累计总量及部分与整体的关系，兼具折线图的趋势表达与柱状图的面积对比优势。
1414

1515
## 代码演示
1616

‎site/docs/components/plots/waterfall.zh.md‎

Lines changed: 54 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,63 @@ link: /examples#statistics-waterfall
77
order: 14
88
---
99

10-
## 特有
10+
## 简介
1111

12-
### linkStyle
12+
瀑布图（Waterfall）又称桥接图或飞瀑图，是一种用于展示数据从初始值到最终值的演变过程及各因素影响的可视化图表。其核心特征包括：
1313

14-
<description>**required** _attrStyle_</description>
14+
- 阶梯式布局：以柱状图为基础，通过垂直条形的增减叠加，呈现数据的累积变化。
15+
- 因果关系可视化：
16+
- 初始值与最终值用完整柱形表示（通常居左、右两端）。
17+
- 中间柱形表示各因素的影响（正值向上延伸，负值向下延伸）。
18+
- 流向隐喻：形似瀑布的水流方向，直观展示数据 “增长 - 衰减” 的动态过程。
1519

16-
连线样式
20+
## 代码演示
1721

18-
### xField
22+
更多示例详见[Waterfall](/examples#statistics-waterfall)
1923

20-
<description>**required** _string | string[]_</description>
24+
### 基础用法
2125

22-
x 轴字段
26+
<Playground path="/statistics/waterfall/demo/basic.js" rid="waterfall-basic"></playground>
27+
28+
### 连接线标记
29+
30+
<Playground path="/statistics/waterfall/demo/connector.js" rid="waterfall-connector"></playground>
31+
32+
### 反向链接线标记
33+
34+
<Playground path="/statistics/waterfall/demo/reverse.js" rid="waterfall-reverse"></playground>
35+
36+
## 配置项
37+
38+
### 概览
39+
40+
|配置项|说明|类型|默认值|
41+
|-----|---|----|-----|
42+
| data | [数据](/options/plots/data/overview) | Array | [] |
43+
| xField | 横轴字段 | string | - |
44+
| yField | 纵轴字段 | string | - |
45+
| colorField | 和 seriesField 类似，不过会加上颜色通道，详见[color](/options/plots/color) | string（可选） | - |
46+
| linkStyle | 连接线样式，配置项详见[配置线的样式](/options/plots/style#配置线的样式) | object（可选） | - |
47+
| connector | 连接线标记，配置和 [Line](/components/plots/line) 类似，默认处理了 `xField`、`yField`、`data`，可通过 `reverse` 字段让连线绘制方向颠倒，通过 `style` 指定[配置线的样式](/options/plots/style#配置线的样式)。 | object(可选) | - |
48+
| title | 用于指定图表的标题内容，详见[标题](/options/plots/title) | object（可选） | - |
49+
| axis | 用于建立数据与视觉位置的映射关系，详见[坐标轴](/options/plots/axis) | object（可选） | - |
50+
| legend | 图表的辅助元素，使用颜色、大小、形状区分不同的数据类型，用于图表中数据的筛选，详见[图例](/options/plots/legend) | object（可选） | - |
51+
| label | 数据标签是给图表添加标注的手段之一，详见[标签](/options/plots/label) | object（可选） | - |
52+
| tooltip | 用于动态展示数据点的详细信息，详见[提示](/options/plots/tooltip) | object（可选） | - |
53+
| style | 视觉样式，配置项详见[绘图属性](/options/plots/style#绘图属性) | object（可选） | - |
54+
| theme | 用于控制图表的整体外观，包括颜色、字体、边距等视觉属性，详见[主题](/options/plots/theme/overview) | string \| object（可选） | `light` |
55+
| onReady | 图表加载回调，用于后续的事件[事件](/options/plots/event)绑定 | Function（可选） | - |
56+
| scale | 将抽象数据映射为视觉数据，详见[比例尺](/options/plots/scale/overview) | object（可选） | - |
57+
| animate | 动画作为可视化的重要组成部分，能显著提高数据可视化的表现力，详见[动画](/options/plots/animate/overview) | object（可选） | - |
58+
| interaction | 提供了按需探索数据的能力，详见[交互](/options/plots/interaction/overview) | object（可选） | - |
59+
| state | 实现交互反馈、高亮、选中等效果，详见[状态](/options/plots/state)，不同交互下图表样式 | object（可选） | - |
60+
| annotations | 视图好比一个画板，`Waterfall` 组件默认在其上绘制了一个瀑布图，我们可以通过 annotations 在上面叠加更多的图层，详见[标注](/examples#statistics-annotation-shape) | Array（可选） | - |
61+
62+
63+
## 事件
64+
65+
详见[选项-事件](/options/plots/event)。
66+
67+
## 方法
68+
69+
详见[图表概览-图表方法](/components/plots/overview#图表方法)。

site/examples/statistics/waterfall/demo/annotation.js renamed to site/examples/statistics/waterfall/demo/basic.js

File renamed without changes.

‎site/examples/statistics/waterfall/demo/connector.js‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
import { Waterfall } from '@ant-design/plots';
2+
import React from 'react';
3+
import { createRoot } from 'react-dom';
4+
5+
const DemoWaterfall = () => {
6+
const config = {
7+
data: [
8+
{ x: 'Net Sales', value: 5085000 },
9+
{ x: 'Cost of Sales', value: -1250450 },
10+
{ x: 'Operating Expenses', value: -2350050 },
11+
{ x: 'Other Income', value: 750000 },
12+
{ x: 'Extraordinary Gain', value: -230050 },
13+
{ x: 'Interest Expense', value: -500000 },
14+
{ x: 'Taxes', value: 490000 },
15+
{ x: 'Net Income', isTotal: true, value: 1994450 },
16+
],
17+
xField: 'x',
18+
yField: 'value',
19+
linkStyle: {
20+
lineDash: [4, 2],
21+
stroke: '#ccc',
22+
},
23+
style: {
24+
maxWidth: 25,
25+
stroke: '#ccc',
26+
fill: (d, idx) => {
27+
return idx === 0 || d.isTotal ? '#96a6a6' : d.value > 0 ? '#64b5f6' : '#ef6c00';
28+
},
29+
},
30+
label: {
31+
text: 'value',
32+
formatter: '~s',
33+
position: (d) => (d.value > 0 ? 'top' : 'bottom'),
34+
textBaseline: (d) => (d.value > 0 ? 'bottom' : 'top'),
35+
fontSize: 10,
36+
dy: (d) => (d.value > 0 ? -4 : 4),
37+
},
38+
connector: {
39+
label: {
40+
text: (d) => `${d.y2 - d.y1}`,
41+
formatter: '~s',
42+
fontSize: 14,
43+
dy: 2,
44+
},
45+
style: { stroke: '#697474', offset: 16 },
46+
},
47+
};
48+
return <Waterfall {...config} />;
49+
};
50+
51+
createRoot(document.getElementById('container')).render(<DemoWaterfall />);

‎site/examples/statistics/waterfall/demo/meta.json‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,28 @@
55
},
66
"demos": [
77
{
8-
"filename": "revenue-flow-waterfall.js",
8+
"filename": "basic.js",
99
"title": {
10-
"zh": "线标记的瀑布图",
11-
"en": "Revenue Flow Waterfall Chart"
10+
"zh": "瀑布图 - 基础用法",
11+
"en": "Waterfall plot - Basic Usage"
1212
},
13-
"screenshot": "https://mdn.alipayobjects.com/mdn/huamei_qa8qxu/afts/img/A*fG4DT7XWNzUAAAAAAAAAAAAADmJ7AQ"
13+
"screenshot": "https://gw.alipayobjects.com/mdn/rms_d314dd/afts/img/A*xOfKT5qr9R4AAAAAAAAAAAAAARQnAQ"
1414
},
1515
{
16-
"filename": "annotation.js",
16+
"filename": "connector.js",
1717
"title": {
18-
"zh": "瀑布图 - 添加标注",
19-
"en": "Waterfall plot with annotation"
18+
"zh": "瀑布图 - 连接线",
19+
"en": "Waterfall plot with connector"
2020
},
21-
"screenshot": "https://gw.alipayobjects.com/mdn/rms_d314dd/afts/img/A*xOfKT5qr9R4AAAAAAAAAAAAAARQnAQ"
21+
"screenshot": "https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*9BOSQozPCx4AAAAAAAAAAAAADmJ7AQ/original"
22+
},
23+
{
24+
"filename": "reverse.js",
25+
"title": {
26+
"zh": "瀑布图 - 反向连线",
27+
"en": "Waterfall plot with reverse connector"
28+
},
29+
"screenshot": "https://mdn.alipayobjects.com/mdn/huamei_qa8qxu/afts/img/A*fG4DT7XWNzUAAAAAAAAAAAAADmJ7AQ"
2230
}
2331
]
2432
}

site/examples/statistics/waterfall/demo/revenue-flow-waterfall.js renamed to site/examples/statistics/waterfall/demo/reverse.js

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@ const DemoWaterfall = () => {
4141
fontSize: 10,
4242
dy: (d) => (d.value > 0 ? -4 : 4),
4343
},
44+
connector: {
45+
reverse: true,
46+
style: { stroke: '#697474', offset: 16 },
47+
},
4448
};
4549
return <Waterfall {...config} />;
4650
};

0 commit comments

Comments
 (0)