Shoelace `<sl-progress-bar>` 组件完全指南:进度条属性、样式定制与无障碍实现
Shoelace <sl-progress-bar> 组件完全指南:进度条属性、样式定制与无障碍实现
<sl-progress-bar> 是 Shoelace(Web Awesome)组件库中用于展示进行中操作状态的进度条组件,适用于文件上传、任务加载、流程推进等场景。本文以官方组件文档为核心,结合仓库源码与测试用例,完整讲解其属性、插槽、CSS 自定义属性、React 用法以及底层渲染与无障碍实现,读完即可在项目中直接使用并深度定制。
组件定位与核心能力
进度条(Progress Bar)用于向用户展示某个持续进行中的操作的状态。Shoelace 的 <sl-progress-bar> 是一个状态稳定的组件(自 v2.0 起提供,见 progress-bar.component.ts 的 @status stable、@since 2.0 注释),它通过 role="progressbar" 暴露无障碍语义,支持两种运行模式:
- 确定性进度:通过
value属性指定 0~100 之间的完成百分比,指示器按比例填充轨道; - 不确定进度(indeterminate):当操作正在进行但无法估算完成比例时(如等待网络请求),显示循环滑动的动画指示器。
组件通过 Shadow DOM 封装,仅暴露 value、indeterminate、label 三个公共属性,对外提供 1 个默认插槽、2 个 CSS Part 和 4 个 CSS 自定义属性,整体 API 非常精简。
快速上手
原生 HTML 用法
引入组件后,直接使用自定义元素标签即可:
<sl-progress-bar value="50"></sl-progress-bar>
value 决定指示器填充的比例,上例会渲染一个填充到 50% 的进度条。
React 用法
Shoelace 提供了 React 包装组件,可从 @shoelace-style/shoelace/dist/react/progress-bar 导入:
import SlProgressBar from '@shoelace-style/shoelace/dist/react/progress-bar';
const App = () => <SlProgressBar value={50} />;
注意包名为 @shoelace-style/shoelace(见 package.json)。React 组件与原生元素的属性和事件一一对应,value 既可以传数字(value={50}),也可以传字符串(value="50"),因为组件内部将其归约为数字。
API 一览
组件文档页(由 docs/_includes/component.njk 模板根据自定义元素清单自动生成)会呈现完整的 Slots、Properties、CSS Parts、CSS Custom Properties 表格。<sl-progress-bar> 的完整 API 如下:
Properties(属性)
| 名称 | 描述 | 反射(Reflects) | 类型 | 默认值 |
|---|---|---|---|---|
value |
当前进度百分比,范围 0~100 | 是 | number |
0 |
indeterminate |
为 true 时忽略百分比、隐藏标签,并绘制为不确定状态 | 是 | boolean |
false |
label |
供辅助设备使用的自定义标签 | 是 | string |
'' |
此外所有组件还继承 title 属性(渲染为原生 title)与只读的 updateComplete Promise(在组件完成一次更新渲染后 resolve,见 usage 文档)。
Slot(插槽)
| 名称 | 描述 |
|---|---|
(default) |
在进度指示器内部显示的标签内容 |
CSS Parts(可定制部件)
| 名称 | 描述 |
|---|---|
base |
组件的基础外层容器 |
indicator |
进度条的指示器(填充部分) |
label |
进度条内部的标签 |
CSS Custom Properties(自定义属性)
| 名称 | 描述 | 默认值 |
|---|---|---|
--height |
进度条高度 | 1rem |
--track-color |
轨道颜色 | var(--sl-color-neutral-200) |
--indicator-color |
指示器颜色 | var(--sl-color-primary-600) |
--label-color |
标签文字颜色 | var(--sl-color-neutral-0) |
这些默认值定义在 progress-bar.styles.ts 的 :host 规则中,可通过行内 style 或全局 CSS 覆盖(见下文“样式定制”)。
为进度条添加标签(Labels)
默认情况下,辅助设备(屏幕阅读器)会依据本地化词条来播报进度条。通过 label 属性可以自定义播报文案,例如在上传场景中明确告知“上传进度”:
<sl-progress-bar value="50" label="Upload progress"></sl-progress-bar>
import SlProgressBar from '@shoelace-style/shoelace/dist/react/progress-bar';
const App = () => <SlProgressBar value="50" label="Upload progress" />;
从源码看,label 会被映射到 aria-label;当 label 为空时,组件自动使用本地化词条 localize.term('progress')(英文环境下即 "Progress",见 src/translations/en.ts)作为兜底,保证进度条在任何语言环境下都有可访问名称(见 progress-bar.component.ts)。
除了 label 属性,测试中还验证了 ariaLabel 与 ariaLabelledBy 的用法(见 progress-bar.test.ts),即也可以直接给组件设置 aria-label 或引用外部标签元素的 aria-labelledby,同样能通过可访问性测试。
自定义高度
进度条默认高度为 1rem(约 16px)。通过 CSS 自定义属性 --height 可任意调整:
<sl-progress-bar value="50" style="--height: 6px;"></sl-progress-bar>
import SlProgressBar from '@shoelace-style/shoelace/dist/react/progress-bar';
const App = () => <SlProgressBar value={50} style={{ '--height': '6px' }} />;
--height 会同时作用于轨道与指示器:指示器通过 line-height: var(--height) 让内部文字垂直居中,保证标签始终贴合高度变化(见 progress-bar.styles.ts)。设置较小的值(如 4~6px)可得到细条形进度指示器,适合紧凑型界面。
显示数值:默认插槽 + 动态更新
进度条的数值本身不会自动显示,需要借助默认插槽(default slot)将内容放入指示器内部。下面的示例展示了如何结合 <sl-button> 和 <sl-icon> 实现“加减 10%”的交互,并让数值文字与 value 同步:
<sl-progress-bar value="50" class="progress-bar-values">50%</sl-progress-bar>
<br />
<sl-button circle><sl-icon name="dash" label="Decrease"></sl-icon></sl-button>
<sl-button circle><sl-icon name="plus" label="Increase"></sl-icon></sl-button>
<script>
const progressBar = document.querySelector('.progress-bar-values');
const subtractButton = progressBar.nextElementSibling.nextElementSibling;
const addButton = subtractButton.nextElementSibling;
addButton.addEventListener('click', () => {
const value = Math.min(100, progressBar.value + 10);
progressBar.value = value;
progressBar.textContent = `${value}%`;
});
subtractButton.addEventListener('click', () => {
const value = Math.max(0, progressBar.value - 10);
progressBar.value = value;
progressBar.textContent = `${value}%`;
});
</script>
React 中借助 useState 管理状态即可实现同样效果:
import { useState } from 'react';
import SlButton from '@shoelace-style/shoelace/dist/react/button';
import SlIcon from '@shoelace-style/shoelace/dist/react/icon';
import SlProgressBar from '@shoelace-style/shoelace/dist/react/progress-bar';
const App = () => {
const [value, setValue] = useState(50);
function adjustValue(amount) {
let newValue = value + amount;
if (newValue < 0) newValue = 0;
if (newValue > 100) newValue = 100;
setValue(newValue);
}
return (
<>
<SlProgressBar value={value}>{value}%</SlProgressBar>
<br />
<SlButton circle onClick={() => adjustValue(-10)}>
<SlIcon name="dash" label="Decrease" />
</SlButton>
<SlButton circle onClick={() => adjustValue(10)}>
<SlIcon name="plus" label="Increase" />
</SlButton>
</>
);
};
两个注意点:
value需要手动夹在 0~100 之间——源码中指示器宽度直接取${this.value}%(见 progress-bar.component.ts),超出范围会导致指示器溢出轨道(轨道设置了overflow: hidden会裁切视觉,但数值语义会失真);- 插槽内容位于指示器内部,颜色默认为
--label-color(--sl-color-neutral-0,即浅色),在深色指示器上对比清晰。
关于插槽的使用细节(默认插槽与命名插槽的区别、slot 属性的用法),可参考 使用文档。
不确定状态(Indeterminate)
当操作正在进行但进度无法确定时,使用 indeterminate 属性:
<sl-progress-bar indeterminate></sl-progress-bar>
import SlProgressBar from '@shoelace-style/shoelace/dist/react/progress-bar';
const App = () => <SlProgressBar indeterminate />;
进入该状态后:
value被忽略:指示器不再按百分比定位,而是以固定宽度(50%)在轨道中循环滑动;- 标签被隐藏:即使传入了插槽内容或
label,也不会渲染显示(源码中仅当!this.indeterminate时才渲染<slot>,见 progress-bar.component.ts); - ARIA 语义同步调整:
aria-valuenow被置为0,避免辅助设备读到无意义的数值(见 progress-bar.component.ts)。
动画由 indeterminate 关键帧驱动:指示器从 left: -50% 滑向 left: 100%,单次周期 2.5 秒、使用 cubic-bezier(0.37, 0, 0.63, 1) 缓动并无限循环(见 progress-bar.styles.ts)。
深入源码:渲染结构与底层实现
<sl-progress-bar> 的完整实现位于 progress-bar.component.ts,核心渲染逻辑如下:
render() {
return html`
<div
part="base"
class=${classMap({
'progress-bar': true,
'progress-bar--indeterminate': this.indeterminate,
'progress-bar--rtl': this.localize.dir() === 'rtl'
})}
role="progressbar"
title=${ifDefined(this.title)}
aria-label=${this.label.length > 0 ? this.label : this.localize.term('progress')}
aria-valuemin="0"
aria-valuemax="100"
aria-valuenow=${this.indeterminate ? 0 : this.value}
>
<div part="indicator" class="progress-bar__indicator" style=${styleMap({ width: `${this.value}%` })}>
${!this.indeterminate ? html` <slot part="label" class="progress-bar__label"></slot> ` : ''}
</div>
</div>
`;
}
值得关注的实现细节:
- 属性反射:
value与indeterminate都通过reflect: true反射为 HTML 属性,因此你可以在开发者工具中直接观察到状态变化,也便于 CSS 属性选择器定制样式; - RTL 支持:当本地化方向为从右到左(RTL)时,组件自动添加
progress-bar--rtl类,指示器改用indeterminate-rtl关键帧从右侧滑动(见 progress-bar.styles.ts),进度条方向与阅读方向保持一致; - 过渡动画:指示器的
width与background-color均有 400ms 的过渡(见 progress-bar.styles.ts),因此动态改变value时进度条会平滑伸缩而不是突兀跳变; - 强制颜色模式适配:在
forced-colors: active(如 Windows 高对比度模式)下,轨道与指示器改用SelectedItem系统色并描边,保证可访问性(见 progress-bar.styles.ts)。
组件的注册与导出也很标准:progress-bar.ts 中通过 SlProgressBar.define('sl-progress-bar') 完成自定义元素注册,并在全局 HTMLElementTagNameMap 中登记类型;入口文件 src/shoelace.ts 将其作为 SlProgressBar 导出,因此全量引入 dist/shoelace.js 后组件即自动可用。
样式定制的完整示例
结合上述 CSS 自定义属性,可以一次性定制高度、轨道色、指示器色与标签色:
<sl-progress-bar
value="75"
label="Downloading assets"
style="--height: 12px; --track-color: #e0e0e0; --indicator-color: #4caf50; --label-color: #fff;"
>
75%
</sl-progress-bar>
如果希望组件级统一定制,也可以在全局样式中覆盖这些变量,例如配合暗色主题:
sl-progress-bar {
--track-color: var(--sl-color-neutral-700);
--indicator-color: var(--sl-color-primary-500);
}
对于更精细的样式控制,可通过 ::part() 选择器直接命中 base、indicator、label 三个部件进行覆写。
测试验证:无障碍与行为保障
仓库为 <sl-progress-bar> 提供了完整的测试套件(progress-bar.test.ts),从多个维度验证组件行为:
- 可访问性:在仅传
value、带title、带indeterminate、带ariaLabel、带ariaLabelledBy五种场景下均通过@open-wc/testing的to.be.accessible()断言; - ARIA 数值映射:
value="25"时,base部件的aria-valuenow属性为'25'; - 指示器宽度:
value="25"时,indicator部件的内联样式为width:25%;,与渲染逻辑一一对应; - 不确定状态:设置
indeterminate后,base部件会获得progress-bar progress-bar--indeterminate两个类,驱动滑动动画生效。
这些测试既是对组件行为的回归保障,也可以作为你理解组件语义的参考样例。
小结
<sl-progress-bar> 以极简的 API(3 个属性、1 个插槽、4 个 CSS 自定义属性)覆盖了进度展示的核心需求:确定性进度用 value,未知进度用 indeterminate,无障碍播报用 label,数值显示用默认插槽,视觉定制用 --height 等自定义属性。结合其 400ms 平滑过渡、RTL 支持、强制颜色模式适配与完整的可访问性测试,它在原生 HTML、React 及各种框架集成场景下都能开箱即用,是搭建上传、加载、任务进度等界面的可靠基础组件。