Angular Material Badge 组件完全指南用法、定位、尺寸、可见性与无障碍实践【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/componentsBadge徽章是 Angular Material 中用于为 UI 元素附加小型状态描述符的组件由一个通常包含数字或短字符的小圆点构成紧贴在宿主对象旁显示。本文以官方文档 src/material/badge/badge.md 为核心结合 badge.ts 的源码实现、badge.scss 的样式机制与仓库中的真实示例系统讲解matBadge指令的位置、重叠、尺寸、可见性控制以及matBadgeDescription与aria-describedby的无障碍细节读完即可在真实项目中正确使用与测试 Badge。什么是 BadgeBadge 是 UI 元素的小型状态描述符。一个 Badge 由一个小圆组成通常包含一个数字或一组短字符显示在另一个对象附近用于表达数量如未读消息数、状态如新标签或提示信息。在 Angular Material 中Badge 通过MatBadge指令selector 为[matBadge]实现直接以属性形式挂载到宿主元素上例如给一个按钮或图标加matBadge4即可生成徽章。模块入口为MatBadgeModule公开 API 还包括MatBadgePosition、MatBadgeSize、MAT_BADGE_CONFIG与MatBadgeConfig见 public-api.ts。一个重要前提Badge 必须应用于块级元素官方文档明确要求Badges must always be applied to block-level elementsBadge 必须始终应用于块级元素。由于徽章采用绝对定位相对宿主呈现将matBadge放在行内元素上会导致定位基准失效、布局错乱。快速上手示例下面是最基本的 Badge 用法来自仓库示例 badge-overview-example.html!-- 文本加徽章 -- div matBadge4 classdemo-sectionText with a badge/div !-- 按钮加徽章 -- button matButtonelevated matBadge8 matBadgePositionbefore Action /button !-- 图标加徽章 -- mat-icon matBadge15home/mat-icon对应的组件需要导入MatBadgeModule以及用到按钮、图标时的MatButtonModule、MatIconModule完整组件代码见 badge-overview-example.tsimport {Component, signal} from angular/core; import {MatIconModule} from angular/material/icon; import {MatButtonModule} from angular/material/button; import {MatBadgeModule} from angular/material/badge; Component({ selector: badge-overview-example, templateUrl: badge-overview-example.html, styleUrl: badge-overview-example.css, imports: [MatBadgeModule, MatButtonModule, MatIconModule], }) export class BadgeOverviewExample { hidden signal(false); toggleBadgeVisibility() { this.hidden.update(hidden !hidden); } }Badge 位置Position默认情况下Badge 会被放置在宿主的above after上方、靠后位置。位置可通过matBadgePosition属性改变取值为above|below垂直方向与before|after水平方向的任意组合。!-- 放在宿主左侧 -- button matButtonelevated matBadge8 matBadgePositionbefore Action /button源码中定义的合法取值见 badge.ts共有 8 种export type MatBadgePosition | above after | above before | below before | below after | before | after | above | below;其中单独的before/after/above/below是仅指定单一方向的简写形式。指令在宿主上根据位置动态切换 CSS 类见 badge.tsmat-badge-above/mat-badge-below/mat-badge-before/mat-badge-after底层判断逻辑为isAbove(): boolean { return this.position.indexOf(below) -1; } isAfter(): boolean { return this.position.indexOf(before) -1; }样式层面badge.scss通过绝对定位实现四个方向并特别处理了 RTL从右到左排版.mat-badge-above { bottom: 100%; } .mat-badge-below { top: 100%; } .mat-badge-before { right: 100%; } [dirrtl] .mat-badge-before { right: auto; left: 100%; } .mat-badge-after { left: 100%; } [dirrtl] .mat-badge-after { left: auto; right: 100%; }此外matBadgePosition也支持通过MAT_BADGE_CONFIG注入令牌统一设置默认值见下文全局默认配置。重叠行为OverlapBadge 与宿主内部内容的重叠关系由matBadgeOverlap控制。典型场景是徽章应重叠在图标之上而不重叠在文本短语之上。默认情况下 Badge 会重叠overlap true。!-- 文本上的徽章不重叠 -- div matBadge4 matBadgeOverlapfalse classdemo-sectionText with a badge/div在源码中matBadgeOverlap是一个布尔属性输入通过 Angular 的booleanAttribute转换器支持matBadgeOverlap写死或[matBadgeOverlap]绑定表达式两种写法见 badge.tsInput({alias: matBadgeOverlap, transform: booleanAttribute}) overlap: boolean;重叠状态同样映射为宿主类名mat-badge-overlap。样式上重叠与否对应不同的外边距补偿badge.scss.mat-badge-overlap .mat-badge-content { margin: token-utils.slot(badge-#{$prefix}container-overlap-offset, $fallbacks); }尺寸SizeBadge 共有三种尺寸small、medium和large默认是medium。通过给宿主元素添加matBadgeSize即可切换尺寸div matBadge1 matBadgeSizesmall classdemo-sectionText with small badge/div div matBadge1 matBadgeSizelarge classdemo-sectionText with large badge/div一个值得注意的行为small尺寸的 Badge 不显示标签文本。这在只提示存在未读通知、无需展示确切数量的场景非常有用——例如显示有未读消息但不暴露具体条数。源码中类型定义badge.tsexport type MatBadgeSize small | medium | large;宿主类名映射为mat-badge-small/mat-badge-medium/mat-badge-largebadge.ts。样式实现中尺寸通过 Sass mixin 生成badge.scss默认容器为 22px小号减小 6px 为 16px大号增大 6px 为 28px$default-size: 22px !default; $small-size: $default-size - 6; $large-size: $default-size 6;在 Material 3 主题下徽章使用min-width/min-height使容器能随内容增长避免文字被截断Material 2 则保持传统的width/height行为详见 badge.scss 中的注释说明。可见性控制VisibilityBadge 的可见性可以通过matBadgeHidden以编程方式切换配合信号signal或普通布尔属性即可实现显示/隐藏交互button matButtonelevated matBadge7 [matBadgeHidden]hidden() (click)toggleBadgeVisibility() Hide /button组件侧badge-overview-example.tshidden signal(false); toggleBadgeVisibility() { this.hidden.update(hidden !hidden); }源码中matBadgeHidden同样是布尔属性输入badge.ts默认false。隐藏状态映射到宿主的mat-badge-hidden类样式上直接display: nonebadge.scss.mat-badge-hidden .mat-badge-content { display: none; }另外还有一个关联的matBadgeDisabled输入默认false见 badge.ts用于生成mat-badge-disabled类将徽章渲染为禁用态的灰暗配色badge.scss常与隐藏逻辑配合使用。无障碍AccessibilityBadge 内容本身对屏幕阅读器是隐藏的源码中徽章元素被设置为aria-hiddentrue见 badge.ts因为徽章只是装饰性描述不应进入页面导航流。真正有意义的描述通过以下机制对外暴露matBadgeDescription 与 aria-describedby官方文档要求必须通过matBadgeDescription提供有意义的描述。具体行为分为两种场景见 badge.ts宿主为可交互元素MatBadge通过aria-describedby将描述关联到宿主上内部使用 CDK 的AriaDescriber。宿主为不可交互元素MatBadge追加一个视觉隐藏cdk-visually-hidden的内联描述元素。指令通过InteractivityChecker.isFocusable()判断宿主是否可聚焦从而决定采用哪种方式badge.ts。判断发生在内容变更时源码注释也指出如果宿主的可交互状态会变化通常应结合同一个条件同步设置matBadgeHidden。在 mat-icon 上使用 Badge 的注意事项当把 Badge 应用到mat-icon时需特别注意mat-icon默认带有aria-hiddentrue。如果图标与徽章的组合传达了有意义的信息必须通过其他方式将这些信息呈现出来例如在同屏补充一段视觉隐藏的文本说明。仓库示例正是这么做的badge-overview-example.htmlmat-icon matBadge15home/mat-icon !-- Include text description of the icons meaning for screen-readers -- span classcdk-visually-hidden Example with a home icon with overlaid badge showing the number 15 /span源码层面对此还做了开发期防御当检测到matBadge挂在aria-hiddentrue的mat-icon上时会在开发模式下输出console.warn提示建议设置aria-hiddenfalse见 badge.ts。进阶全局默认配置从源码可以推断MatBadge支持通过MAT_BADGE_CONFIG注入令牌批量配置默认值badge.tsexport interface MatBadgeConfig { /** Default position for badges. */ position?: MatBadgePosition; /** Default size for badges. */ size?: MatBadgeSize; /** Default color to apply to all badges. */ color?: ThemePalette; /** Whether badges should overlap by default. */ overlap?: boolean; } export const MAT_BADGE_CONFIG new InjectionTokenMatBadgeConfig(MAT_BADGE_CONFIG);构造函数中按config?.xxx ?? 默认值的方式回退badge.tscolor默认primary、overlap默认true、position默认above after、size默认medium。在应用级 providers 中提供MAT_BADGE_CONFIG即可统一改变全站徽章的默认外观。注意color主题色仅对 M2 主题生效在 M3 主题下无效M3 的配色定制需要走设计令牌design tokens方案。测试 BadgeMatBadgeHarness仓库为 Badge 提供了官方测试工具MatBadgeHarness位于 src/material/badge/testing宿主选择器为.mat-badge常用方法包括getText()获取徽章文本getPosition()获取MatBadgePosition通过mat-badge-above/below、mat-badge-before/after类组合推断getSize()获取尺寸通过mat-badge-small/medium/large类推断默认返回mediumisOverlapping()/isHidden()/isDisabled()分别判断是否重叠、隐藏、禁用结合TestbedHarnessEnvironment即可编写组件测试仓库中的 badge-harness-example.spec.ts 给出了完整范式import {ComponentFixture, TestBed} from angular/core/testing; import {TestbedHarnessEnvironment} from angular/cdk/testing/testbed; import {MatBadgeHarness} from angular/material/badge/testing; import {HarnessLoader} from angular/cdk/testing; import {BadgeHarnessExample} from ./badge-harness-example; describe(BadgeHarnessExample, () { let fixture: ComponentFixtureBadgeHarnessExample; let loader: HarnessLoader; beforeEach(() { fixture TestBed.createComponent(BadgeHarnessExample); fixture.detectChanges(); loader TestbedHarnessEnvironment.loader(fixture); }); it(should load all badge harnesses, async () { const badges await loader.getAllHarnesses(MatBadgeHarness); expect(badges.length).toBe(3); }); it(should be able to get the text of a badge, async () { const badge await loader.getHarness(MatBadgeHarness.with({selector: #simple})); expect(await badge.getText()).toBe(S); fixture.componentInstance.simpleContent.set(Changed); expect(await badge.getText()).toBe(Changed); }); it(should get whether a badge is overlapping, async () { const badge await loader.getHarness(MatBadgeHarness.with({selector: #overlapping})); expect(await badge.isOverlapping()).toBe(true); fixture.componentInstance.overlap.set(false); expect(await badge.isOverlapping()).toBe(false); }); it(should get whether a badge is disabled, async () { const badge await loader.getHarness(MatBadgeHarness.with({selector: #disabled})); expect(await badge.isDisabled()).toBe(true); fixture.componentInstance.disabled.set(false); expect(await badge.isDisabled()).toBe(false); }); });配合MatBadgeHarness.with({text: ...})过滤器可按文本定位特定徽章见 badge-harness.ts。源码实现要点与最佳实践总结从 badge.ts 的实现还可以提炼出以下关键机制徽章元素动态创建ngOnInit中通过_createBadgeElement()创建span classmat-badge-content追加到宿主末尾并清理由服务端渲染遗留的旧徽章_clearExistingBadges保证 SSR 场景下不重复渲染badge.ts、badge.ts。入场动画徽章插入后以requestAnimationFrame添加mat-badge-active类实现从scale(0.6)到transform: none的过渡动画badge.ts当全局动画禁用或标记_mat-animation-noopable时跳过过渡badge.scss。overflow 处理宿主被强制设置为overflow: visible保证徽章可以渲染到元素边界之外即使mat-icon等组件显式设置了overflow: hidden也以更高的选择器优先级覆盖badge.scss。文本截断徽章内容设置了white-space: nowrap与text-overflow: ellipsis超长内容会以省略号截断badge.scss。使用建议只把matBadge用在块级元素上避免行内元素导致定位异常。图标上用徽章时重叠保持默认true文本旁用徽章时设置matBadgeOverlapfalse。需要传达确切数量且空间充足时用medium/large仅提示有未读时用small并配合matBadgeHidden控制显隐。永远为徽章提供matBadgeDescription图标场景务必补充可读的替代文本规避mat-icon默认aria-hidden造成的信息丢失。全站统一默认外观时通过MAT_BADGE_CONFIG注入默认 position / size / color / overlap。组件测试优先使用MatBadgeHarness避免直接依赖 DOM 类名细节。如需查看完整示例与样式细节可继续阅读仓库中的 badge-overview 示例目录、badge-harness 示例目录以及样式源文件 badge.scss 和主题文件 badge-theme.scss。【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考