企业官网建设流程全解析

• 前端
• UI组件

导读：本文以 rsuite 官方文档中 Progress 组件「尺寸（Size）」演示片段为核心，深入讲解如何通过strokeWidth调整线条进度条的高度、用radius控制圆角半径，并结合仓库源码揭示其底层实现原理（CSS 变量传递链路、getCssValue单位处理、默认值回退机制）与对应的测试用例验证。读完本文，你将能够精准控制 rsuite 线性进度条的外观尺寸，并理解这些属性在水平、垂直、多段等场景下的实际行为。

一、场景定位：Progress 组件的「Size」示例

在 rsuite 的官方文档中，Progress 组件用于"显示某个操作流程的当前进度"。其中"尺寸（Size）"一节专门讲解如何调整进度条的高度与圆角，对应的示例文档位于 docs/pages/components/progress/fragments/line-stroke-width.md，其完整代码如下：

import { Progress, VStack } from 'rsuite'; const App = () => ( <VStack spacing={10}> <Progress percent={30} strokeWidth={20} /> <Progress percent={30} strokeWidth={20} radius={10}/> </VStack> ); ReactDOM.render(<App />, document.getElementById('root'));

这段示例展示了两个关键点：

1. strokeWidth={20}：将进度条线条高度从默认值调高到 20px；
2. radius={10}：为第二个进度条设置 10px 的圆角半径，使"胶囊"感更明显（第一个保持默认圆角，形成直观对比）。

外层使用VStack spacing={10}将两条进度条垂直排列并保持 10px 间距。进度百分比统一为30，说明尺寸定制与进度数值完全解耦，可以独立配置。

二、strokeWidth：控制线条高度的核心属性

根据官方 Props 表（见 docs/pages/components/progress/en-US/index.md），strokeWidth的类型为number，描述为"线条宽度（Line width）"。需要注意：对于线条型（Line）进度条，strokeWidth实际控制的是进度条的高度（水平布局下），而非水平方向的长度——水平长度由percent决定。

2.1 默认高度与生效机制

从源码角度看，strokeWidth并非直接写成内联样式，而是通过 CSS 变量传递。在 src/Progress/ProgressLine.tsx 中：

const styles = mergeStyles( cssVar('trail-size', getCssValue(trailWidth || strokeWidth)), cssVar('trail-color', trailColor), cssVar('stroke', `${totalPercent}%`), cssVar('size', getCssValue(strokeWidth)), cssVar('color', strokeColor), cssVar('radius', getCssValue(radius)), style );

这里strokeWidth被转换为--rs-progress-line-size变量；而轨道（trail）的尺寸--rs-progress-line-trail-size使用trailWidth || strokeWidth计算——当未单独指定trailWidth时，轨道高度自动跟随strokeWidth，保证进度条与轨道视觉上对齐。

对应 SCSS 中，stroke与trail的高度分别消费这两个变量（见 src/Progress/styles/_progress-line.scss）：

&-trail { height: var(--rs-progress-line-trail-size); } &-stroke { height: var(--rs-progress-line-size); }

SCSS 中声明的默认值为--rs-progress-line-size: 10px;，因此不传strokeWidth时，线条高度默认为 10px。

2.2 单位处理：getCssValue的规则

strokeWidth之所以只接受number，与单位处理工具getCssValue的实现直接相关（见 src/internals/utils/style-sheet/css.ts）：

export function getCssValue(value?: number | string | null, unit = 'px') { if (value === undefined || value === null || value === '') { return undefined; } if (value === 0) { return '0'; } if (typeof value === 'number') { return `${value}${unit}`; // 数字自动追加 px } return value.toString(); // 字符串原样返回 }

即：数字会自动追加px单位，0会输出'0'（不带单位），字符串则原样透传。这解释了 Props 类型设计——strokeWidth为number（内部统一追加px），而radius为number | string（允许传入'50%'这类带单位的字符串值）。测试用例也印证了这一点，见 src/Progress/test/ProgressLine.spec.tsx：

it('Should have a height', () => { render(<ProgressLine strokeWidth={10} />); const style = screen.getByRole('progressbar').getAttribute('style'); expect(style).to.be.match(/--rs-progress-line-trail-size: 10px/); expect(style).to.be.match(/--rs-progress-line-size: 10px/); });

该测试明确验证：传入strokeWidth={10}后，--rs-progress-line-trail-size与--rs-progress-line-size均为10px。

2.3 与trailWidth的分工

当两者同时指定时，可实现"粗轨道、细进度"等差异化视觉；只指定strokeWidth时轨道自动对齐，无需额外维护。

三、radius：圆角半径的定制

radius属性（版本要求：6.0.0+）用于自定义进度条的圆角半径，类型为number | string。示例中radius={10}会生成--rs-progress-line-radius: 10px。

SCSS 中该变量的默认值为--rs-progress-line-radius: var(--rs-radius-sm)（跟随设计系统的小圆角 token），并同时作用于三个层级（见 src/Progress/styles/_progress-line.scss）：

• .rs-progress-line-outer：外层容器的圆角与overflow: hidden；
• .rs-progress-line-trail：背景轨道圆角；
• .rs-progress-line-stroke：进度线条圆角，并带有width, height, background-color的过渡动画（--rs-progress-bg-transition: 0.2s ease-in-out）。

由于三层均使用同一变量，传入radius后轨道、外框与进度条圆角保持一致，不会出现内外圆角不匹配的割裂感。若传入字符串（如radius="50%"），getCssValue会原样输出，可借此实现圆角样式的高级控制。

四、底层原理：从 Props 到 CSS 变量的完整链路

结合 src/Progress/ProgressLine.tsx，尺寸定制的完整数据流如下：

1. Props 解构与默认值：percent默认0、percentPlacement默认'end'、showInfo默认true、classPrefix默认'progress-line'；
2. 总百分比计算：若传入sections，则以各段percent之和作为totalPercent（用于--rs-progress-line-stroke与无障碍属性aria-valuenow）；
3. CSS 变量组装：strokeWidth→--rs-progress-line-size、trailWidth || strokeWidth→--rs-progress-line-trail-size、radius→--rs-progress-line-radius、percent→--rs-progress-line-stroke、strokeColor→--rs-progress-line-color；
4. 结构渲染：outer > trail > stroke三层嵌套，百分比文字（info）根据percentPlacement决定渲染在 stroke 内部还是外部。

组件还通过role="progressbar"、aria-valuemin="0"、aria-valuemax="100"、aria-valuenow={totalPercent}暴露无障碍语义，尺寸调整不会影响进度语义的正确性。

五、尺寸定制的完整实践清单

在实际项目中，strokeWidth与radius常与其他属性组合使用，以下是基于官方 Props 表与源码整理的实战要点：

<Progress percent={60} strokeWidth={16} // 调高进度条高度 radius={8} // 圆角跟随调整，视觉更柔和 strokeColor="#1675e0" // 自定义填充色 trailColor="#f2f2f5" // 自定义轨道色 />

• strokeWidth对percentPlacement的影响：当percentPlacement取'insideStart' | 'insideEnd' | 'insideCenter'时，百分比文字渲染在 stroke 内部（见 src/Progress/ProgressLine.tsx）。此时如果strokeWidth过小（如 10px 默认值），内部文字会显得拥挤，建议搭配percentPlacement="insideEnd"使用时同步加大strokeWidth；
• 垂直模式下的语义翻转：vertical布局中进度条沿高度方向增长，strokeWidth转而起作用为宽度（SCSS 中-vertical .rs-progress-line-trail { width: var(--rs-progress-line-trail-size) }），radius同样生效；
• 多段进度（sections）下的尺寸：sections模式同样消费--rs-progress-line-size与--rs-progress-line-radius，首段与末段的圆角分别取border-start-*-radius/border-end-*-radius（见 src/Progress/styles/_progress-line.scss），尺寸定制在多段场景下依然一致生效；
• indeterminate模式：该模式下 stroke 强制width: 100%，percent被忽略，strokeWidth仍决定动画条带的高度；
• 组件入口：Progress本身即ProgressLine的别名，同时挂载了Progress.Line与Progress.Circle两个子组件（见 src/Progress/Progress.tsx），本文讨论的尺寸属性仅针对Progress.Line。

六、小结

strokeWidth与radius是 rsuite Progress 线条进度条尺寸定制的两个核心属性：前者以像素为单位控制线条高度（数字自动追加px，默认 10px，轨道高度未指定时自动跟随），后者控制圆角半径（支持数字与字符串，默认跟随设计系统--rs-radius-sm，且同步作用于外层、轨道与进度条三层）。二者在水平、垂直、多段、不确定状态等全部模式中保持一致的行为，底层通过getCssValue统一转换为 CSS 变量（--rs-progress-line-size、--rs-progress-line-trail-size、--rs-progress-line-radius），由 src/Progress/styles/_progress-line.scss 消费渲染，并有 src/Progress/test/ProgressLine.spec.tsx 中的高度测试用例兜底验证。

如需进一步了解 Progress 的完整能力（状态、条纹、多段、垂直布局、renderInfo自定义信息等），可继续查阅 Progress 官方文档 及其对应演示片段（docs/pages/components/progress/fragments）。

• 前端
• UI组件