Progress

基础反馈

基于 Bootstrap 5 的进度条组件，用于展示任务或流程的完成情况，支持标签、自定义高度、8 种颜色变体、条纹与条纹动画、堆叠分段以及手动组合多个进度条

Component Demo

Basic usage and examples of the Progress component

基础用法

Progress 默认渲染 `.progress` 容器与内部 `.progress-bar`，now 会同时写入 `aria-valuenow` 与进度条宽度

高度

25%

height 只作用于外层 `.progress`（写入 `--bs-progress-height` 变量），内部进度条与条纹尺寸会自动跟随

背景色

75%

50%

variant 渲染 `bg-*` 工具类；为彩色进度条添加标签时建议同时开启 textBg，改用 `text-bg-*` 以获得足够的文字对比度

多个进度条

ProgressStacked 渲染 `.progress-stacked`；位于其中的 Progress 会自动把宽度写到自身容器上，并继承堆叠容器的 height，无需额外配置

条纹

striped 为进度条渲染 `progress-bar-striped`，以 CSS 渐变在背景色之上叠加条纹

条纹动画

animated 渲染 `progress-bar-animated` 并自动补上条纹类；用户开启“减少动态效果”时动画会自动停止

手动组合

bar 设为 `false` 时 children 直接渲染在 `.progress` 内，可自由组合多个 ProgressBar；此时外层 now 表示整体进度，内部分段仅作展示。ProgressBar 未传 now 时不写内联宽度，可改用 `w-*` 工具类

交互示例

40%

通过 state 驱动 now 即可获得受控进度，当前进度：40%

API Documentation

Complete API reference for the Progress component

Props

Progress

属性名	类型	默认值	描述
`animated`	`boolean`	`false`	是否启用条纹动画，渲染 `progress-bar-animated` 类，并自动附加 `progress-bar-striped` 以保证条纹可见
`as`	`ElementType`	`'div'`	外层 `.progress` 容器渲染的元素类型
`bar`	`boolean`	`true`	是否自动渲染内部 `.progress-bar`；设为 `false` 时 children 直接渲染在 `.progress` 内，便于手动组合多个 `ProgressBar`
`barAs`	`ElementType`	`'div'`	内部 `.progress-bar` 渲染的元素类型
`barProps`	`ProgressBarProps`	-	透传给内部 `ProgressBar` 的属性，可覆盖自动推导的类名、样式与内容
`children`	`ReactNode`	-	进度条标签内容，默认渲染在内部 `.progress-bar` 中
`className`	`string`	-	自定义类名，作用于外层 `.progress` 容器
`height`	`number \| string`	-	进度条高度，写入 `--bs-progress-height` CSS 变量，数字按 px 处理；未设置时继承 `ProgressStacked` 的高度
`label`	`string`	`'progress'`	无障碍名称，渲染为外层容器的 `aria-label`；传入 `aria-labelledby` 时自动省略
`max`	`number`	`100`	最大值，渲染 `aria-valuemax` 并参与宽度百分比计算
`min`	`number`	`0`	最小值，渲染 `aria-valuemin` 并参与宽度百分比计算
`now`	`number`	`0`	当前值，渲染 `aria-valuenow`，并按 `(now - min) / (max - min)` 计算宽度百分比；结果自动裁剪到 0% ~ 100%
`role`	`string`	`'progressbar'`	无障碍角色，Bootstrap 5.3 起该角色与 `aria-value*` 均位于外层 `.progress` 上
`striped`	`boolean`	`false`	是否显示条纹，渲染 `progress-bar-striped` 类
`textBg`	`boolean`	`false`	是否使用 `text-bg-` 替代 `bg-`，让标签文字自动获得足够对比度，适合带标签的彩色进度条
`variant`	`ProgressVariant`	-	进度条颜色变体，为 `.progress-bar` 渲染 `bg-`（或 `text-bg-`）工具类
`...rest`	`HTMLAttributes`	-	外层容器的所有原生属性（如 `style`、`aria-labelledby` 等）

ProgressBar

属性名	类型	默认值	描述
`animated`	`boolean`	`false`	是否启用条纹动画，渲染 `progress-bar-animated` 类，并自动附加条纹类
`as`	`ElementType`	`'div'`	渲染的元素类型
`children`	`ReactNode`	-	进度条标签内容
`className`	`string`	-	自定义类名，可配合 `w-*`、`overflow-visible` 等工具类使用
`max`	`number`	`100`	最大值，参与宽度百分比计算
`min`	`number`	`0`	最小值，参与宽度百分比计算
`now`	`number`	-	当前值，提供时按百分比写入内联 `width`；未提供时不设置宽度，可改用 `w-*` 工具类
`striped`	`boolean`	`false`	是否显示条纹，渲染 `progress-bar-striped` 类
`textBg`	`boolean`	`false`	是否使用 `text-bg-` 替代 `bg-`
`variant`	`ProgressVariant`	-	颜色变体，渲染 `bg-`（或 `text-bg-`）工具类
`...rest`	`HTMLAttributes`	-	根元素的所有原生属性（如 `style`、`aria-hidden` 等）

ProgressStacked

属性名	类型	默认值	描述
`as`	`ElementType`	`'div'`	外层 `.progress-stacked` 容器渲染的元素类型
`children`	`ReactNode`	-	堆叠内容，通常为多个 `Progress`，每个 `Progress` 代表一个分段
`className`	`string`	-	自定义类名
`height`	`number \| string`	-	堆叠进度条高度，写入 `--bs-progress-height` CSS 变量，数字按 px 处理；同时下发给未单独设置 height 的子 `Progress`
`...rest`	`HTMLAttributes`	-	根元素的所有原生属性（如 `style`、`aria-label` 等）

Type Definitions

ProgressBarProps

进度条内层组件属性接口

export interface ProgressBarProps extends HTMLAttributes<HTMLElement> {
  animated?: boolean;
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  max?: number;
  min?: number;
  now?: number;
  striped?: boolean;
  textBg?: boolean;
  variant?: ProgressVariant;
}

ProgressProps

进度条组件属性接口

export interface ProgressProps extends HTMLAttributes<HTMLElement> {
  animated?: boolean;
  as?: ElementType;
  bar?: boolean;
  barAs?: ElementType;
  barProps?: ProgressBarProps;
  children?: ReactNode;
  className?: string;
  height?: number | string;
  label?: string;
  max?: number;
  min?: number;
  now?: number;
  role?: string;
  striped?: boolean;
  textBg?: boolean;
  variant?: ProgressVariant;
}

ProgressStackedContextValue

堆叠进度条上下文值，可通过 `useProgressStacked` 获取（不在堆叠内返回 `null`）

export interface ProgressStackedContextValue {
  height?: number | string;
}

ProgressStackedProps

堆叠进度条组件属性接口

export interface ProgressStackedProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  height?: number | string;
}

ProgressVariant

进度条颜色变体类型

export type ProgressVariant =
  'danger' | 'dark' | 'info' | 'light' | 'primary' | 'secondary' | 'success' | 'warning';