Shoelace `<sl-progress-bar>` 组件完全指南:进度条属性、样式定制与无障碍实现

原创2026-09-21 17:58:201,746 阅读
文章标签:UI组件前端

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>
    </>
  );
};

两个注意点:

  1. value 需要手动夹在 0~100 之间——源码中指示器宽度直接取 ${this.value}%(见 progress-bar.component.ts),超出范围会导致指示器溢出轨道(轨道设置了 overflow: hidden 会裁切视觉,但数值语义会失真);
  2. 插槽内容位于指示器内部,颜色默认为 --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 及各种框架集成场景下都能开箱即用,是搭建上传、加载、任务进度等界面的可靠基础组件。

登录后查看全文
shoelace