docs: add waterfall component documentation#3002
Conversation
📝 WalkthroughWalkthrough本次变更主要围绕瀑布图（Waterfall）文档的重构与扩充，涵盖了文档内容、示例代码、配置项说明和部分核心类型定义的完善。同时，新增了瀑布图连接线（connector）相关的配置和功能支持，并对相关类型、常量及示例进行了同步更新。 Changes
Sequence Diagram(s)sequenceDiagram
participant 用户
participant Waterfall组件
participant adaptor
participant connectorTransform
用户->>Waterfall组件: 配置带 connector 的瀑布图
Waterfall组件->>adaptor: 传递 options
adaptor->>connectorTransform: 检查并处理 connector 配置
connectorTransform-->>adaptor: 返回处理后的参数
adaptor->>Waterfall组件: 渲染瀑布图及连接线
Assessment against linked issues
Poem
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
site/examples/statistics/waterfall/demo/reverse.jsOops! Something went wrong! :( ESLint: 8.57.1 ESLint couldn't find the plugin "eslint-plugin-react". (The package "eslint-plugin-react" was not found when loaded as a Node module from the directory "/site".) It's likely that the plugin isn't installed correctly. Try reinstalling by running the following: The plugin "eslint-plugin-react" was referenced from the config file in "site/.eslintrc.js » /node_modules/.pnpm/@umijs+fabric@2.14.1/node_modules/@umijs/fabric/dist/eslint.js". If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team. site/examples/statistics/waterfall/demo/connector.jsOops! Something went wrong! :( ESLint: 8.57.1 ESLint couldn't find the plugin "eslint-plugin-react". (The package "eslint-plugin-react" was not found when loaded as a Node module from the directory "/site".) It's likely that the plugin isn't installed correctly. Try reinstalling by running the following: The plugin "eslint-plugin-react" was referenced from the config file in "site/.eslintrc.js » /node_modules/.pnpm/@umijs+fabric@2.14.1/node_modules/@umijs/fabric/dist/eslint.js". If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team. ✨ Finishing Touches
🧪 Generate Unit Tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
site/examples/statistics/waterfall/demo/reverse.js (1)
44-47: 考虑提取样式配置以提高可读性连接线的样式配置是正确的，但可以考虑将样式对象提取为常量以提高代码可读性。
可以这样重构：
+const connectorStyle = { + reverse: true, + style: { stroke: '#697474', offset: 16 }, +}; + connector: { - reverse: true, - style: { stroke: '#697474', offset: 16 }, + ...connectorStyle, },
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
packages/plots/src/core/constants/index.ts(1 hunks)packages/plots/src/core/plots/waterfall/adaptor.ts(2 hunks)packages/plots/src/core/plots/waterfall/type.ts(1 hunks)packages/plots/src/core/types/common.ts(1 hunks)site/docs/components/plots/area.zh.md(1 hunks)site/docs/components/plots/waterfall.zh.md(1 hunks)site/examples/statistics/waterfall/demo/connector.js(1 hunks)site/examples/statistics/waterfall/demo/meta.json(1 hunks)site/examples/statistics/waterfall/demo/reverse.js(1 hunks)
🧰 Additional context used
🧬 Code Graph Analysis (2)
packages/plots/src/core/plots/waterfall/type.ts (1)
packages/plots/src/core/types/common.ts (2)
Options(93-119)AttrStyle(127-127)
site/examples/statistics/waterfall/demo/connector.js (2)
site/examples/statistics/waterfall/demo/basic.js (2)
DemoWaterfall(5-47)config(13-45)site/examples/statistics/waterfall/demo/reverse.js (2)
DemoWaterfall(5-50)config(6-48)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: deploy
🔇 Additional comments (17)
packages/plots/src/core/constants/index.ts (1)
248-252: 代码实现符合既定模式！新增的
connector配置项遵循了现有的结构模式，具有正确的key、type和extend_keys属性。空的extend_keys数组对于连接线功能来说是合理的，因为它不需要继承通用的字段扩展。site/docs/components/plots/area.zh.md (1)
13-13: 文档描述改进得很好！新的面积图描述更加全面和详细，准确地解释了面积图的概念、用途和优势，将折线图的趋势表达与柱状图的面积对比优势结合得很好。
site/examples/statistics/waterfall/demo/reverse.js (1)
1-53: React 组件实现正确！该示例正确使用了 React 18 的
createRootAPI，瀑布图配置完整，包含了新的反向连接线功能。数据结构和样式配置都很合理，条件渲染逻辑也实现得很好。packages/plots/src/core/types/common.ts (1)
13-13: 类型扩展合理且必要！将
string[]添加到Primitive类型中是合理的，这扩展了编码规范中可使用的原始值类型，支持字符串数组的场景，与新增的连接线功能需求相匹配。site/examples/statistics/waterfall/demo/meta.json (1)
1-32: 示例元数据更新正确！元数据正确反映了瀑布图示例的重组和扩展，包含了基础用法、连接线和反向连接线三个示例。文件命名清晰，标题描述准确，JSON 结构完整有效。
packages/plots/src/core/plots/waterfall/type.ts (2)
3-3: 类型定义更改合理移除了对
xField的排除，这样WaterfallOptions可以继承基础Options类型中的xField属性，使类型定义更加一致和灵活。
9-9: 新增 connector 属性类型定义正确新增的
connector属性类型定义合理：
- 使用
Partial<Options>允许继承所有基础配置选项- 添加可选的
reverse布尔标志用于控制连接线方向- 类型定义与实现逻辑保持一致
packages/plots/src/core/plots/waterfall/adaptor.ts (2)
1-1: 导入语句更新正确添加了
isObject和set工具函数的导入，这些函数在新的connectorTransform函数中被正确使用。
95-95: 流程更新正确在
mark和transformOptions之间正确添加了connectorTransform步骤，确保连接线变换在标记处理之后、选项变换之前执行。site/examples/statistics/waterfall/demo/connector.js (4)
1-4: 导入语句正确导入了必要的依赖项：
Waterfall组件、React 和createRoot，符合现代 React 应用的最佳实践。
7-16: 示例数据设计良好财务数据结构合理，包含了：
- 正值和负值的混合，很好地展示了瀑布图的特点
- 合适的数据标识（
isTotal标记总计项）- 真实的财务场景数据，便于用户理解
38-46: connector 配置展示完整很好地演示了新的
connector功能：
- 标签配置显示数值差异
${d.y2 - d.y1}- 使用格式化器
'~s'简化数值显示- 自定义样式包括颜色和偏移量
- 配置选项全面且实用
51-51: React 渲染方式现代化使用了 React 18 的
createRootAPI，符合最新的 React 最佳实践。site/docs/components/plots/waterfall.zh.md (4)
10-18: 简介部分内容详实且准确新增的瀑布图简介很好地解释了：
- 瀑布图的别名和基本概念
- 核心特征的详细说明
- 视觉隐喻的生动描述
内容专业且易于理解，能够帮助用户快速了解瀑布图的用途和特点。
20-34: 代码演示部分组织合理演示部分的结构清晰：
- 基础用法展示核心功能
- 连接线标记展示新功能
- 反向连接线标记展示高级用法
每个示例都有明确的标题和对应的 playground 路径，便于用户理解和实践。
48-61: 配置项表格内容完整配置项表格涵盖了瀑布图组件的所有主要配置选项：
- 基础数据配置（data, xField, yField）
- 样式配置（style, linkStyle, theme）
- 功能配置（label, tooltip, legend）
- 高级配置（animate, interaction, state）
每个配置项都包含了说明、类型和默认值，便于开发者参考使用。
63-69: 文档引用部分完善正确添加了事件和方法部分的引用链接，使文档结构更加完整，便于用户查找相关信息。
| const connectorTransform = (params: Params) => { | ||
| const { options } = params; | ||
| const { data = [], connector } = options; | ||
| if (!connector) return params; | ||
| set(options, 'connector', { | ||
| xField: connector.reverse ? ['x2', 'x1'] : ['x1', 'x2'], | ||
| yField: connector.reverse ? ['y2', 'y1'] : ['y1', 'y2'], | ||
| data: [ | ||
| { | ||
| x1: data[0].x, | ||
| y1: data[0][END_KEY], | ||
| x2: data[data.length - 1].x, | ||
| y2: data[data.length - 1][END_KEY], | ||
| }, | ||
| ], | ||
| ...(isObject(connector) ? connector : {}), | ||
| }) | ||
| return params; | ||
| }; |
There was a problem hiding this comment.
🛠️ Refactor suggestion
connectorTransform 函数实现需要改进
函数逻辑基本正确，但存在几个问题：
- 缺少数据长度检查：当
data数组为空或只有一个元素时，data[data.length - 1]可能导致问题 - 字段访问可能失败：
data[0].x和data[0][END_KEY]没有进行安全检查
建议添加数据验证：
const connectorTransform = (params: Params) => {
const { options } = params;
const { data = [], connector } = options;
if (!connector) return params;
+ if (data.length < 2) return params;
+
+ const firstItem = data[0];
+ const lastItem = data[data.length - 1];
+ if (!firstItem || !lastItem) return params;
+
set(options, 'connector', {
xField: connector.reverse ? ['x2', 'x1'] : ['x1', 'x2'],
yField: connector.reverse ? ['y2', 'y1'] : ['y1', 'y2'],
data: [
{
- x1: data[0].x,
- y1: data[0][END_KEY],
- x2: data[data.length - 1].x,
- y2: data[data.length - 1][END_KEY],
+ x1: firstItem.x,
+ y1: firstItem[END_KEY],
+ x2: lastItem.x,
+ y2: lastItem[END_KEY],
},
],
...(isObject(connector) ? connector : {}),
})
return params;
};📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const connectorTransform = (params: Params) => { | |
| const { options } = params; | |
| const { data = [], connector } = options; | |
| if (!connector) return params; | |
| set(options, 'connector', { | |
| xField: connector.reverse ? ['x2', 'x1'] : ['x1', 'x2'], | |
| yField: connector.reverse ? ['y2', 'y1'] : ['y1', 'y2'], | |
| data: [ | |
| { | |
| x1: data[0].x, | |
| y1: data[0][END_KEY], | |
| x2: data[data.length - 1].x, | |
| y2: data[data.length - 1][END_KEY], | |
| }, | |
| ], | |
| ...(isObject(connector) ? connector : {}), | |
| }) | |
| return params; | |
| }; | |
| const connectorTransform = (params: Params) => { | |
| const { options } = params; | |
| const { data = [], connector } = options; | |
| if (!connector) return params; | |
| if (data.length < 2) return params; | |
| const firstItem = data[0]; | |
| const lastItem = data[data.length - 1]; | |
| if (!firstItem || !lastItem) return params; | |
| set(options, 'connector', { | |
| xField: connector.reverse ? ['x2', 'x1'] : ['x1', 'x2'], | |
| yField: connector.reverse ? ['y2', 'y1'] : ['y1', 'y2'], | |
| data: [ | |
| { | |
| x1: firstItem.x, | |
| y1: firstItem[END_KEY], | |
| x2: lastItem.x, | |
| y2: lastItem[END_KEY], | |
| }, | |
| ], | |
| ...(isObject(connector) ? connector : {}), | |
| }) | |
| return params; | |
| }; |
🤖 Prompt for AI Agents
In packages/plots/src/core/plots/waterfall/adaptor.ts around lines 75 to 93, the
connectorTransform function lacks validation for the data array length and safe
access to its elements. To fix this, add checks to ensure data has at least two
elements before accessing data[0] and data[data.length - 1]. Also, verify that
data[0].x and data[0][END_KEY] exist before using them to prevent runtime
errors. If the data is insufficient or fields are missing, return params early
or handle the case gracefully.
1 participant
Summary by CodeRabbit
新功能
Primitive类型支持string[]，提升编码灵活性。文档