rsuite ProgressCircle 自定义信息渲染指南：renderInfo 的完整用法与源码解析

• 前端
• UI组件

本文聚焦 rsuite 组件库中ProgressCircle（环形进度条）的renderInfo属性，讲解如何用一段自定义渲染函数完全接管圆环中央的信息展示——无论是固定文案、百分比文本，还是根据进度状态（success / fail / active）动态渲染图标或颜色。读完本文，你将掌握renderInfo的签名与参数语义、三种典型用法，以及它背后的默认渲染逻辑与源码实现。

1. 认识 renderInfo：接管圆环中央的信息区

ProgressCircle默认会在圆形进度条中央显示一个百分比文本（例如30%），而showInfo用于控制该信息区的显隐。当默认的"30%"文本无法满足业务需要时，就可以通过renderInfo属性传入自定义渲染函数，完全接管这个信息区。

从 ProgressCircle.tsx 的类型定义可以看到其完整签名：

renderInfo?: (percent: number, status?: 'success' | 'fail' | 'active') => React.ReactNode;

• 第一个参数percent：当前进度百分比（数值类型，如 30、60、100）。
• 第二个参数status：进度状态，可选值为'success' | 'fail' | 'active'，未设置时为undefined。
• 返回值：任意 ReactNode，即最终渲染在圆环中央的内容。

renderInfo并不是ProgressCircle独有的能力。从源码结构看，它由 ProgressInfo.tsx 这个共享组件统一实现，同时服务于ProgressCircle与线性的ProgressLine（见 ProgressLine.tsx），因此这套自定义渲染逻辑在两种进度条组件间保持一致。

2. 三种典型用法：从静态文案到状态感知

关联文档 render-info.md 中的示例覆盖了从简到繁的三个层级，下面逐一展开。

2.1 固定文案：忽略参数，渲染静态内容

最简单的场景是信息区不需要随进度变化，只需展示一个固定标签（如 "Usage"）：

import { ProgressCircle, HStack, VStack, Text } from 'rsuite'; import { FaCheckCircle } from 'react-icons/fa'; const App = () => ( <HStack spacing={20}> <ProgressCircle percent={30} w={100} renderInfo={percent => `Usage`} /> </HStack> ); ReactDOM.render(<App />, document.getElementById('root'));

这里的renderInfo={percent => \Usage`}声明了参数percent但未使用它，直接返回字符串Usage`。该用法对应仓库中的 Story 示例（Progress.stories.tsx）。

2.2 结构化多行内容：利用 percent 动态插值

当需要在圆环中央同时展示标签与实时百分比时，可以在函数体内组合多个布局组件，并通过第一个参数percent动态拼接文本：

<ProgressCircle percent={60} w={100} renderInfo={percent => ( <VStack align="center"> <Text>Usage</Text> <Text>{percent}%</Text> </VStack> )} />

此时percent为 60，<Text>{percent}%</Text>渲染出 "60%"，与上方的 "Usage" 标签在VStack中垂直居中排列。这种写法让信息区兼具说明文字与实时数据，适合磁盘占用、配额消耗等需要同时表达"指标含义 + 数值"的场景。

提示：VStack与HStack是 rsuite 内置的弹性布局组件，这里的align="center"控制子元素在交叉轴上的对齐方式。

2.3 状态感知渲染：根据 status 切换图标与颜色

renderInfo的第二个参数status让信息区可以感知进度状态，实现"完成即变图标"的交互效果：

<ProgressCircle percent={100} w={100} status="success" renderInfo={(percent, status) => ( <span style={{ color: status === 'success' ? '#4CAF50' : '#000' }} > {status === 'success' ? <FaCheckCircle size="30" color="#4CAF50" /> : `${percent}%`} </span> )} />

• 当status === 'success'时，渲染一个绿色的FaCheckCircle图标（来自react-icons/fa）；
• 否则回退为${percent}%文本，同时通过内联样式控制文字颜色。

这种模式非常适合"上传完成""任务成功"等状态反馈场景：进度未满时显示百分比，达到 100% 且状态为 success 时自动切换为成功图标。

3. 完整示例代码

将三个示例组合起来，即可得到关联文档中的完整演示：

import { ProgressCircle, HStack, VStack, Text } from 'rsuite'; import { FaCheckCircle } from 'react-icons/fa'; const App = () => ( <HStack spacing={20}> <ProgressCircle percent={30} w={100} renderInfo={percent => `Usage`} /> <ProgressCircle percent={60} w={100} renderInfo={percent => ( <VStack align="center"> <Text>Usage</Text> <Text>{percent}%</Text> </VStack> )} /> <ProgressCircle percent={100} w={100} status="success" renderInfo={(percent, status) => ( <span style={{ color: status === 'success' ? '#4CAF50' : '#000' }} > {status === 'success' ? <FaCheckCircle size="30" color="#4CAF50" /> : `${percent}%`} </span> )} /> </HStack> ); ReactDOM.render(<App />, document.getElementById('root'));

其中w={100}通过BoxProps透传控制圆环直径（对应类型定义中的width属性，详见 ProgressCircle.tsx），percent则控制弧线进度。

4. 源码级原理：renderInfo 如何被调用

renderInfo的调用链并不复杂，理解它有助于把握参数语义与边界行为。

4.1 传递路径

在 ProgressCircle.tsx 中，组件在showInfo为 true 时渲染ProgressInfo，并把percent、status、renderInfo一并传入：

{showInfo && ( <ProgressInfo percent={totalPercent} renderInfo={renderInfo} status={status} classPrefix={classPrefix} /> )}

注意这里的percent并非原始 prop，而是经过useMemo计算的totalPercent（ProgressCircle.tsx）：当提供了多色分段sections时，它等于各段百分比之和并封顶 100；未提供sections时即为percent本身。因此renderInfo收到的第一个参数始终是"最终展示的总进度值"。

4.2 默认渲染逻辑

ProgressInfo内部（ProgressInfo.tsx）的优先级为：

1. 若提供了renderInfo，直接调用renderInfo(percent, status)，以返回值覆盖一切；
2. 未提供时，若存在status且不是'active'，渲染内置的状态图标（来自PROGRESS_STATUS_ICON常量）；
3. 否则渲染默认的${percent}%文本。

也就是说，一旦传入renderInfo，默认的百分比文本与内置状态图标都会被完全替换——这是自定义渲染函数"接管"语义的确切来源。同时showInfo={false}可以整体关闭该信息区（对应 ProgressCircle.spec.tsx 中的测试用例）。

5. 测试与 Story 佐证

仓库中为renderInfo提供了多组测试与演示，可作为行为契约：

• 自定义内容渲染：renderInfo={() => <span className="custom-info">Custom Content</span>}时，断言.rs-progress-circle-info内的文本等于Custom Content（ProgressCircle.spec.tsx）。
• 携带 status 的自定义渲染：renderInfo={(percent, status) => ...}且status="success"时，断言渲染结果为50-success，证明两个参数都正确传入（ProgressCircle.spec.tsx）。
• 与 sections 协同：多段进度场景下，renderInfo={percent => \Total: ${percent}%`}渲染出Total: 70%`，验证回调收到的是各段之和（ProgressCircleSections.spec.tsx）。
• Storybook 演示：RenderInfo与ShowInfo两个 Story 分别展示了固定文案、多行结构两种用法以及信息区开关效果（Progress.stories.tsx）。

此外，useProgressCirclePath.ts 负责计算圆环的 SVG 路径与 stroke-dasharray 样式，圆环本身基于viewBox="0 0 100 100的坐标系绘制，中心点即 (50, 50)——这也解释了为什么信息区内容天然居中于圆环内部。

6. 使用建议与注意事项

• 返回类型：renderInfo返回任意 ReactNode，可以是字符串、JSX 或null。返回null可让信息区留白但保留 DOM 节点。
• 不要重复拼接百分号：参数percent是数值，展示时需自行追加%（如`${percent}%`）或使用 rsuite 的Text组件。
• 状态优先级：只要传入renderInfo，内置状态图标便不再显示；如需同时呈现状态图标与自定义内容，需在回调内部自行处理status。
• 配合 sections 使用：当使用多色分段sections时，回调第一参数为总百分比（封顶 100），可实现"多段进度 + 总览信息"的组合展示。
• 关闭信息区：如果只想展示纯圆环，可用showInfo={false}，无需借助renderInfo。

综上，renderInfo是 rsuiteProgressCircle中灵活度最高、最值得掌握的信息定制入口：从固定文案到结构化内容，再到状态感知的动态图标，一套函数即可覆盖绝大多数业务需求；而 ProgressInfo.tsx 的共享实现与测试用例，则保证了它在环形与线性进度条之间的行为一致性。

• 前端
• UI组件