Angular Material Progress Spinner 完整 API 指南angular/material_progress-spinner公共接口深度解析【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components本文以angular/material_progress-spinner的公共 API 报告goldens/material/progress-spinner/index.api.md为核心逐一解读MatProgressSpinner组件、MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS注入令牌、ProgressSpinnerMode类型与MatSpinner别名等全部公开接口并结合本仓库中该组件的源码实现、模板与测试用例说明每个输入属性在底层是如何被解析、钳制与渲染的帮助你在实际项目中正确配置圆形进度指示器并规避无障碍与动画误区。从 API 报告看组件的完整公共面API 报告由 API Extractor 自动生成是组件公共 API 的“权威清单”。它精确列出了angular/material_progress-spinner包对外暴露的全部符号包括两个类、一个接口、一个类型别名、一个注入令牌与一个弃用别名公开符号类型说明MatProgressSpinner类组件圆形进度指示器选择器mat-progress-spinner, mat-spinnerMatProgressSpinnerModule类NgModule导入即获得组件能力MatProgressSpinnerDefaultOptions接口可通过依赖注入覆盖的默认配置MAT_PROGRESS_SPINNER_DEFAULT_OPTIONSInjectionToken用于提供全局默认配置的令牌ProgressSpinnerMode类型别名determinate \| indeterminateMatSpinner常量弃用MatProgressSpinner的历史别名报告还透露了几个实现细节组件声明了 5 个输入color、mode、value、diameter、strokeWidth且diameter、strokeWidth、value三个数值输入通过ngAcceptInputType静态字段接收任意类型由 Angular 的numberAttribute转换器处理同时组件内部维护了_circleRadius()、_strokeCircumference()、_strokeDashOffset()、_viewBox()等 SVG 几何计算辅助方法。下文将结合源码逐一展开。快速上手两种组件形态MatProgressSpinner的宿主选择器同时注册了mat-progress-spinner与mat-spinner两个名称见 progress-spinner.ts 中的selector字段。二者的关系在构造函数中被固定this.mode element.nodeName.toLowerCase() mat-spinner ? indeterminate : determinate;即mat-spinner是mat-progress-spinner modeindeterminate的简写形式。引用该组件只需导入模块import {MatProgressSpinnerModule} from angular/material/progress-spinner; NgModule({ imports: [MatProgressSpinnerModule], }) export class AppModule {}从模块源码progress-spinner-module.ts可以看到模块同时导出了MatProgressSpinner、MatSpinner以及来自angular/cdk/bidi的BidiModule——后者对应 API 报告中模块声明里对i2.BidiModule的依赖用于在 RTL 环境下正确处理圆形指示的方向。进度模式determinate 与 indeterminateProgressSpinnerMode在 progress-spinner.ts 中定义为联合类型export type ProgressSpinnerMode determinate | indeterminate;两种模式的语义与行为如下与组件文档 progress-spinner.md 一致模式语义value行为determinate标准进度指示从 0% 填充到 100%生效决定弧线长短indeterminate表示“正在发生某事”不传达具体进度被忽略始终返回 0默认模式是determinate。这一点既有文档佐证“The default mode is determinate”也有测试佐证在 progress-spinner.spec.ts 中should apply a mode of determinate if no mode is provided 用例断言未传mode时组件实例的mode为determinate。关于value与模式的关系源码中的 getter 揭示了一个容易被忽略的细节get value(): number { return this.mode determinate ? this._value : 0; } set value(v: number) { this._value Math.max(0, Math.min(100, v || 0)); }即输入值始终被钳制在 0100 之间且内部值会被保留。切换到 indeterminate 模式时value对外返回 0但切回 determinate 后原先设置的值会恢复。测试用例 should retain the value if it updates while indeterminateprogress-spinner.spec.ts完整验证了这一保留语义。用法示例!-- determinatevalue 决定进度 -- mat-progress-spinner modedeterminate value60/mat-progress-spinner !-- indeterminate无需 value -- mat-progress-spinner modeindeterminate/mat-progress-spinner !-- 简写别名 -- mat-spinner/mat-spinner尺寸与描边diameter 与 strokeWidthdiameter决定整个圆形的像素直径直接反映为宿主元素的宽高strokeWidth决定圆弧描边的粗细。二者在组件构造时都有内置基准值progress-spinner.tsconst BASE_SIZE 100; // 默认直径 100px const BASE_STROKE_WIDTH 10; // 基准描边宽 10px两个输入的默认与联动逻辑如下diameter默认值为BASE_SIZE100通过numberAttribute转换器接收数字或数字字符串strokeWidth的 getter 在未显式赋值时回退为diameter / 10progress-spinner.ts即默认保持“直径的十分之一”这一比例便于随尺寸等比缩放宿主元素上通过[style.width.px]、[style.height.px]同步直径并额外设置 CSS 自定义属性--mat-progress-spinner-size与--mat-progress-spinner-active-indicator-width供内部样式使用见组件host元数据。典型用法!-- 直径 50px描边默认 5px -- mat-progress-spinner diameter50/mat-progress-spinner !-- 显式指定描边宽度 -- mat-progress-spinner diameter80 strokeWidth8 value30/mat-progress-spinner底层的 SVG 几何计算API 报告列出的_circleRadius()、_strokeCircumference()、_strokeDashOffset()、_viewBox()与_circleStrokeWidth()是模板渲染的关键模板progress-spinner.html中的circle元素依赖这些方法计算半径、周长与虚线偏移。_circleRadius()(diameter - BASE_STROKE_WIDTH) / 2即半径在直径基础上扣除基准描边宽度的一半防止圆弧溢出_strokeCircumference()2 * Math.PI * radius即圆的周长用作stroke-dasharray_strokeDashOffset()仅在 determinate 模式下返回circumference * (100 - value) / 100通过“减少可见弧长”来表现进度百分比indeterminate 模式下返回null由 CSS 动画接管旋转_viewBox()0 0 (2r strokeWidth) (2r strokeWidth)保证 SVG 视口恰好容纳圆与描边。也就是说进度弧线并非“按角度截取”而是利用 SVGstroke-dashoffset技术把圆周按百分比“遮罩”这与 MDC circular progress 的实现保持一致。全局默认配置MAT_PROGRESS_SPINNER_DEFAULT_OPTIONSAPI 报告给出了MatProgressSpinnerDefaultOptions接口的完整字段export interface MatProgressSpinnerDefaultOptions { color?: ThemePalette; diameter?: number; _forceAnimations?: boolean; strokeWidth?: number; }对应的注入令牌在 progress-spinner.ts 中定义默认工厂只提供{diameter: BASE_SIZE}export const MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS new InjectionTokenMatProgressSpinnerDefaultOptions(mat-progress-spinner-default-options, { providedIn: root, factory: () ({diameter: BASE_SIZE}), });在应用根或特性模块中覆盖该令牌即可为全站所有mat-progress-spinner提供统一默认值例如统一缩小到 40pximport {MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS} from angular/material/progress-spinner; providers: [ { provide: MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS, useValue: {diameter: 40, strokeWidth: 4, color: primary}, }, ]构造函数读取默认值的逻辑progress-spinner.ts要点如下若有defaults.color则同时写入当前颜色与_defaultColor默认主题色为primary若有defaults.diameter、defaults.strokeWidth则作为初始值应用组件级显式输入会覆盖这些默认值Angular 输入绑定在构造后生效。_forceAnimations与动画降级接口中以下划线开头的_forceAnimations属于内部半公开字段它控制动画是否“强制启用”。构造函数中const animationsState _getAnimationsState(); this._noopAnimations animationsState di-disabled !!defaults !defaults._forceAnimations;即当 Angular 动画状态为 disabled 时除非显式设置_forceAnimations: true否则组件会加上_mat-animation-noopable类并关闭动画而当系统处于reduced-motion减弱动态效果偏好时组件会追加mat-progress-spinner-reduced-motion类以尊重用户偏好。这套逻辑同时保障了性能敏感场景关闭动画与无障碍场景减弱动画。主题色color 输入与 M2/M3 差异color输入接受ThemePalette通常为primary | accent | warn及 null/undefinedgetter 的逻辑是this._color || this._defaultColor未指定时回退到默认主题色primary。宿主元素通过[class]mat- color动态挂载mat-primary等类名见组件host元数据。需要特别留意 API 报告与源码注释中的约束color仅在 M2 主题下生效在 M3 主题下无效果。主题样式文件 _progress-spinner-theme.scss 证实了这一设计——其colormixin 针对非 M3 主题额外为.mat-accent、.mat-warn生成色板 token而 M3 主题则改用 color-variant 机制。因此M2 主题直接使用coloraccent等即可M3 主题请改用主题的 color-variant 参数include mat.progress-spinner-theme($theme, $color-variant: ...)或设计令牌定制颜色。无障碍实现完整的 ARIA progressbar 模式API 报告中虽然没有直接列出 ARIA 属性但宿主元数据progress-spinner.ts与组件文档progress-spinner.md给出了完整的无障碍契约host: { role: progressbar, tabindex: -1, [attr.aria-valuemin]: 0, [attr.aria-valuemax]: 100, [attr.aria-valuenow]: mode determinate ? value : null, [attr.mode]: mode, }组件根元素自带roleprogressbar并设置aria-valuemin0、aria-valuemax100官方建议不要修改这两个值以免与某些辅助技术不兼容determinate 模式下aria-valuenow实时反映当前进度indeterminate 模式不输出aria-valuenow辅助技术会据此识别为“进行中但无具体进度”tabindex-1让屏幕阅读器可以读取aria-label不过组件文档特别提示 JAWS 在 Firefox 上存在已知问题每个 spinner 都必须通过aria-label或aria-labelledby提供可访问标签例如mat-progress-spinner aria-label加载中 modeindeterminate/mat-progress-spinner模板中所有圆形图形容器均带aria-hiddentrue见 progress-spinner.html避免重复朗读这是为兼容 ChromeVox 而做的处理。组件测试 HarnessMatProgressSpinnerHarness对于需要编写组件测试的场景本仓库在 testing/progress-spinner-harness.ts 提供了官方测试 Harnessexport class MatProgressSpinnerHarness extends ComponentHarness { static hostSelector .mat-mdc-progress-spinner; static withT extends MatProgressSpinnerHarness( this: ComponentHarnessConstructorT, options: ProgressSpinnerHarnessFilters {}, ): HarnessPredicateT {...} /** Gets the progress spinners value. */ async getValue(): Promisenumber | null {...} /** Gets the progress spinners mode. */ async getMode(): PromiseProgressSpinnerMode {...} }宿主选择器为.mat-mdc-progress-spinner与组件host中的class对应getValue()读取aria-valuenow属性并使用coerceNumberProperty转为数字无属性时返回nullgetMode()直接读取mode属性过滤条件ProgressSpinnerHarnessFilters继承自BaseHarnessFiltersprogress-spinner-harness-filters.ts目前没有额外过滤字段但保留了with()的扩展入口。在测试中使用import {MatProgressSpinnerHarness} from angular/material/progress-spinner/testing; const spinner await loader.getHarness(MatProgressSpinnerHarness); expect(await spinner.getMode()).toBe(indeterminate);弃用说明MatSpinner 别名API 报告将MatSpinner标记为public deprecated/** * deprecated Import Progress Spinner instead. Note that the * mat-spinner selector isnt deprecated. * breaking-change 16.0.0 */ export const MatSpinner MatProgressSpinner;需要区分两件事被弃用的是MatSpinner这个 TypeScript 符号请直接导入MatProgressSpinner而mat-spinner选择器本身并未弃用仍可放心在模板中使用。此外MatProgressSpinnerModule仍同时导出二者现有基于MatSpinner的代码在模块层面不受影响。从 API 到实践一个完整的综合示例将以上 API 组合起来一个覆盖全局默认值、尺寸定制与无障碍标签的完整示例mat-progress-spinner modedeterminate value{{uploadProgress}} diameter48 strokeWidth5 colorprimary aria-label文件上传进度/mat-progress-spinner配套的全局默认配置import {MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS} from angular/material/progress-spinner; export const SPINNER_DEFAULTS { provide: MAT_PROGRESS_SPINNER_DEFAULT_OPTIONS, useValue: {diameter: 48, strokeWidth: 5, color: primary}, };小结一下各输入属性的默认值与行为依据 progress-spinner.ts 与 API 报告输入默认值说明modedeterminatemat-spinner为indeterminate进度模式value0钳制在 0100determinate 模式下的进度值indeterminate 时对外返回 0diameter100圆形直径px决定宿主宽高strokeWidthdiameter / 10描边宽度px未设置时随直径等比缩放colorprimary主题色仅 M2 主题生效在集成时请特别核对三点确认项目使用的是 M2 还是 M3 主题以决定color的用法为每个 spinner 补齐aria-label若全局关闭了 Angular 动画考虑是否需要_forceAnimations恢复指示动画。通过 API 报告 源码 测试三者互证MatProgressSpinner的每一个公共接口都有明确的实现落点与可验证的行为这为团队后续的定制与排查提供了最可靠的依据。【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考