Angular Material 进度指示器指南：MatProgressSpinner 与 MatSpinner 的模式、配置与无障碍实现

Angular Material 进度指示器指南MatProgressSpinner 与 MatSpinner 的模式、配置与无障碍实现【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components导读本文基于 Angular Material本仓库GitHub_Trending/co/components的官方组件文档 progress-spinner.md完整讲解MatProgressSpinner与MatSpinner两个圆形进度指示器的核心用法。你将掌握 determinate确定性与 indeterminate不确定性两种进度模式的区别与选型、value/diameter/strokeWidth/color等全部输入属性的取值规则、全局默认配置的注入方式以及基于 ARIAprogressbar模式的无障碍最佳实践。文末还将深入源码与测试揭示该组件基于 SVG 的绘制原理与官方测试 Harness 的用法。组件概览mat-progress-spinner与mat-spinnermat-progress-spinner与mat-spinner是 Angular Material 提供的圆形进度与活动指示器用于表示正在进行中的操作或操作已完成的百分比。二者的关系非常特殊mat-spinner是mat-progress-spinner modeindeterminate的别名详见源码 progress-spinner.ts 中的选择器声明selector: mat-progress-spinner, mat-spinner。一个最基础的用法是mat-spinner/mat-spinner这正是仓库官方示例 progress-spinner-overview-example.html 中的全部模板代码。引入模块使用前需要在组件中导入MatProgressSpinnerModule或在旧版 NgModule 应用中将其加入imports。模块定义位于 progress-spinner-module.tsimport {MatProgressSpinnerModule} from angular/material/progress-spinner; Component({ selector: app-root, template: mat-spinner/mat-spinner, imports: [MatProgressSpinnerModule], // standalone 组件导入 }) export class AppComponent {}该模块同时导出MatProgressSpinner、MatSpinner以及BidiModule用于支持 RTL 双向文本布局。进度模式Progress Modedeterminate 与 indeterminate官方文档明确说明进度指示器支持两种模式determinate与indeterminate。二者核心对比如下表模式说明determinate标准进度指示器从 0% 填充到 100%反映可量化的任务进度indeterminate仅表示有事情正在发生不传达具体进度数值适合耗时未知的操作默认模式是determinate。在该模式下通过value属性设置进度值取值要求是0 到 100 之间的整数。在indeterminate模式下value属性会被忽略。源码中的模式判定逻辑模式判定并非仅靠装饰器默认值源码 progress-spinner.ts 在构造函数中根据宿主元素的标签名动态决定初始模式this.mode element.nodeName.toLowerCase() mat-spinner ? indeterminate : determinate;也就是说写mat-spinner初始即为 indeterminate写mat-progress-spinner初始为 determinate。当然mode本身是Input()你可以在模板中显式覆盖mat-progress-spinner modedeterminate [value]progress/mat-progress-spinner mat-progress-spinner modeindeterminate/mat-progress-spinner仓库的可配置示例 progress-spinner-configurable-example.ts 用 signal 同时管理两种模式export class ProgressSpinnerConfigurableExample { mode signalProgressSpinnerMode(determinate); value signal(50); }对应的模板 progress-spinner-configurable-example.html 中通过单选框切换模式、滑块调节进度并最终将二者绑定到组件上mat-progress-spinner [mode]mode() [value]value()/mat-progress-spinner如何选择模式任务进度可量化如上传、下载、表单步骤用determinatevalue任务耗时不可知如登录校验、数据初始化用indeterminate需要语义上表示纯活动指示且代码更简洁直接用mat-spinner。深入value属性夹取、忽略与动态切换value是 determinate 模式下唯一的进度数据入口。源码 progress-spinner.ts 的实现揭示了几个重要细节Input({transform: numberAttribute}) get value(): number { return this.mode determinate ? this._value : 0; } set value(v: number) { this._value Math.max(0, Math.min(100, v || 0)); } private _value 0;从实现中可以确认三点范围夹取无论传入什么数值setter 都会通过Math.max(0, Math.min(100, ...))将实际值夹取在 0100 之间。测试 progress-spinner.spec.ts 验证了传入999结果为100、传入-10结果为0。indeterminate 时归零当模式为 indeterminategetter 返回0。这印证了文档中indeterminate 模式下 value 被忽略的说法。模式切换时数值保留虽然 indeterminate 模式下读取到的 value 是 0但内部_value依然保留。测试 progress-spinner.spec.ts 验证了在 indeterminate 时把内部值更新为 75切回 determinate 后读取到的 value 恢复为 75。另外value使用了numberAttribute变换因此模板里直接写字符串value50也会被正确转换为数字对应测试见 progress-spinner.spec.ts。尺寸定制diameter与strokeWidth圆形指示器有两个尺寸相关的输入属性均支持浮点数。属性默认值说明diameter100即BASE_SIZE圆形的直径决定 SVG 的宽高strokeWidthdiameter / 10即直径的 10%圆环描边宽度源码 progress-spinner.ts 中定义了基准常量const BASE_SIZE 100; // 基准直径 const BASE_STROKE_WIDTH 10; // 基准描边宽度直径的 10%diameter会通过宿主绑定同时设置元素的宽、高以及两个 CSS 自定义属性见 progress-spinner.ts[style.width.px]: diameter, [style.height.px]: diameter, [style.--mat-progress-spinner-size]: diameter px, [style.--mat-progress-spinner-active-indicator-width]: diameter px,而strokeWidth的默认值并非固定常量而是随直径动态计算progress-spinner.tsget strokeWidth(): number { return this._strokeWidth ?? this.diameter / 10; }对应测试 progress-spinner.spec.ts 验证当diameter 67时默认strokeWidth为6.7。实际使用示例!-- 直径 32px描边默认 3.2px -- mat-progress-spinner [diameter]32 modedeterminate value60/mat-progress-spinner !-- 直径 48px描边 6px支持浮点数 -- mat-progress-spinner [diameter]48.5 [strokeWidth]6.5 modeindeterminate/mat-progress-spinner测试还覆盖了浮点直径/描边、字符串传值diameter37 strokeWidth11等边界情况均被正确解析见 progress-spinner.spec.ts。颜色主题color输入属性color输入支持 Angular Material 的ThemePalette即primary默认、accent、warnmat-progress-spinner coloraccent modeindeterminate/mat-progress-spinner mat-progress-spinner colorwarn [value]80/mat-progress-spinner颜色通过宿主绑定[class]: mat- color映射为mat-primary/mat-accent/mat-warn类见 progress-spinner.ts测试 progress-spinner.spec.ts 验证了类名的切换逻辑。注意从源码注释看progress-spinner.tscolor的默认配色能力仅适用于 M2 主题在 M3 主题下无效果M3 下需通过设计令牌/样式变体方式定制颜色。全局默认配置MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS如果你希望整个应用中所有 spinner 统一使用某套默认参数比如统一 24px 直径可以通过注入令牌MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS覆盖默认值。该令牌定义于 progress-spinner.ts其默认工厂为{diameter: BASE_SIZE}。可配置的默认选项如下MatProgressSpinnerDefaultOptions接口见 progress-spinner.ts选项类型说明colorThemePalette默认主题色仅 M2 生效diameternumber默认直径strokeWidthnumber默认描边宽度_forceAnimationsboolean是否强制启用动画忽略当前环境对动画的禁用提供方式import {MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS} from angular/material/progress-spinner; providers: [ { provide: MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS, useValue: {diameter: 23, color: warn}, }, ],构造函数会读取这些默认值并应用到每个 spinner 实例progress-spinner.ts。对应测试见 progress-spinner.spec.ts分别验证了默认直径、默认描边宽度与默认颜色的注入。此外构造逻辑还处理了动画环境当全局动画被禁用_getAnimationsState()返回di-disabled且未强制启用动画时会为组件添加_mat-animation-noopable类关闭动画当系统处于减弱动态效果reduced-motion时会添加mat-progress-spinner-reduced-motion类见 progress-spinner.ts。无障碍Accessibility官方文档明确要求MatProgressSpinner实现了 ARIA 的roleprogressbar模式。相关行为可以从源码 progress-spinner.ts 的宿主绑定中得到印证host: { role: progressbar, tabindex: -1, // 使屏幕阅读器能够读取 aria-label [attr.aria-valuemin]: 0, [attr.aria-valuemax]: 100, [attr.aria-valuenow]: mode determinate ? value : null, ... }关键无障碍要点不要修改aria-valuemin与aria-valuemax组件默认固定为0与100。官方文档警告修改这两个值可能导致与部分辅助技术不兼容。aria-valuenow动态管理determinate 模式下等于当前valueindeterminate 模式下该属性被置为null即不渲染。对应测试 progress-spinner.spec.ts 验证了这两种状态下的属性存在性。必须提供可访问标签每个 spinner 都要通过aria-label或aria-labelledby提供文本说明例如mat-progress-spinner modeindeterminate aria-label正在加载用户数据/mat-progress-spinner内部 SVG 对辅助技术隐藏模板 progress-spinner.html 中determinate 与 indeterminate 容器均带有aria-hiddentrue且 SVG 设置了focusablefalse以将其从 Tab 顺序中移除宿主元素tabindex-1保证读屏软件能读取到 aria-label。测试验证了所有子节点均带aria-hiddentrue见 progress-spinner.spec.ts以及 SVG 的focusable属性为falseprogress-spinner.spec.ts。源码级原理SVG 圆环是如何绘制的MatProgressSpinner的可视化完全基于内联 SVG 圆环实现模板见 progress-spinner.html。其核心绘制逻辑依赖以下几个私有方法progress-spinner.ts_circleRadius()圆环半径(diameter - BASE_STROKE_WIDTH) / 2即直径减去基准描边宽度后取半_viewBox()SVG 视口0 0 (2r strokeWidth) (2r strokeWidth)会随描边宽度自适应放大因此测试中strokeWidth 40时 viewBox 变为0 0 130 130见 progress-spinner.spec.ts_strokeCircumference()圆环周长2πr用于设置stroke-dasharray_strokeDashOffset()determinate 进度的关键——偏移量周长 × (100 - value) / 100通过缩短可见弧段实现 0%100% 的填充效果indeterminate 模式下返回null转由动画完成环绕运动_circleStrokeWidth()将描边宽度换算为占直径的百分比作用于circle的stroke-width。determinate 模板progress-spinner.html中单个circle同时绑定stroke-dasharray与stroke-dashoffset即可呈现静态进度弧indeterminate 模板progress-spinner.html则由左/右半圆裁剪器circle-clipper与间隙补丁gap-patch配合 CSS 动画模拟连续旋转的加载效果。测试与测试 Harness单元测试覆盖的关键行为仓库的单元测试 progress-spinner.spec.ts 完整覆盖了本文提到的全部特性可作为行为契约参考未指定模式时默认determinate指定合法模式时保持不变默认value为0indeterminate 模式下读取到0但切换回 determinate 时内部值恢复value夹取在 0100默认描边宽度为直径的 10%自定义diameter/strokeWidth含浮点与字符串形式正确作用于宿主宽高、SVG 尺寸与 viewBox颜色类mat-primary/mat-accent的切换默认选项注入直径、描边、颜色aria-valuenow在 determinate 下存在、indeterminate 下移除子节点aria-hidden。组件测试 Harness对于组件测试场景仓库提供了官方测试工具类MatProgressSpinnerHarnessprogress-spinner-harness.ts基于 CDK 的ComponentHarness实现MatProgressSpinnerHarness.with(options)构造查询谓词可按ProgressSpinnerHarnessFilters过滤getValue()读取宿主aria-valuenow属性并转换为数字无该属性时返回null对应 indeterminate 状态getMode()读取宿主mode属性返回determinate | indeterminate。典型测试写法const loader TestbedHarnessEnvironment.loader(fixture); const spinner await loader.getHarness(MatProgressSpinnerHarness); expect(await spinner.getMode()).toBe(indeterminate); expect(await spinner.getValue()).toBeNull();完整的 Harness 使用示例可参考 progress-spinner-harness-example.spec.ts 与对应组件示例 progress-spinner-harness-example.ts。总结MatProgressSpinner/MatSpinner是一个结构精简但行为严谨的组件两种模式覆盖了可量化进度与不可量化活动两大场景value的夹取与忽略逻辑、diameter/strokeWidth的动态计算、全局默认选项注入均能在源码 progress-spinner.ts 与测试 progress-spinner.spec.ts 中得到印证无障碍方面其固定的aria-valuemin0、aria-valuemax100、动态aria-valuenow与必需的aria-label构成了完整的 ARIAprogressbar实现。在实际项目中按模式选型 → 数值/尺寸定制 → 全局默认值 → 无障碍标注 → 测试验证的顺序即可快速接入并使用。【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考