src/material/badge/badge.ts - main - githubmirror/components

src/material/badge/badge.ts
375 строк13 KB
Kristiyan Kostadinov
fix(material/badge): allow badge defaults to be configured (#33312)
01 июн 2026, 10:17
01 июн 2026, 10:172384aed
/**
 * @license
 * Copyright Google LLC All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://angular.dev/license
 */

import {_IdGenerator, AriaDescriber, InteractivityChecker} from '@angular/cdk/a11y';

import {
  booleanAttribute,
  Component,
  Directive,
  ElementRef,
  inject,
  Input,
  NgZone,
  OnDestroy,
  OnInit,
  Renderer2,
  ViewEncapsulation,
  DOCUMENT,
  AfterViewInit,
  InjectionToken,
} from '@angular/core';
import {_animationsDisabled, ThemePalette} from '../core';
import {_CdkPrivateStyleLoader, _VisuallyHiddenLoader} from '@angular/cdk/private';

/** Allowed position options for matBadgePosition */
export type MatBadgePosition =
  | 'above after'
  | 'above before'
  | 'below before'
  | 'below after'
  | 'before'
  | 'after'
  | 'above'
  | 'below';

/** Allowed size options for matBadgeSize */
export type MatBadgeSize = 'small' | 'medium' | 'large';

/** Object that can be used to configure the default options for the badge component. */
export 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;
}

/** Injection token that can be used to configure the default options for the badge component. */
export const MAT_BADGE_CONFIG = new InjectionToken<MatBadgeConfig>('MAT_BADGE_CONFIG');

const BADGE_CONTENT_CLASS = 'mat-badge-content';

/**
 * Component used to load the structural styles of the badge.
 * @docs-private
 */
@Component({
  styleUrl: 'badge.css',
  encapsulation: ViewEncapsulation.None,
  template: '',
})
export class _MatBadgeStyleLoader {}

/** Directive to display a text badge. */
@Directive({
  selector: '[matBadge]',
  host: {
    'class': 'mat-badge',
    '[class.mat-badge-overlap]': 'overlap',
    '[class.mat-badge-above]': 'isAbove()',
    '[class.mat-badge-below]': '!isAbove()',
    '[class.mat-badge-before]': '!isAfter()',
    '[class.mat-badge-after]': 'isAfter()',
    '[class.mat-badge-small]': 'size === "small"',
    '[class.mat-badge-medium]': 'size === "medium"',
    '[class.mat-badge-large]': 'size === "large"',
    '[class.mat-badge-hidden]': 'hidden || !content',
    '[class.mat-badge-disabled]': 'disabled',
  },
})
export class MatBadge implements OnInit, AfterViewInit, OnDestroy {
  private _ngZone = inject(NgZone);
  private _elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
  private _ariaDescriber = inject(AriaDescriber);
  private _renderer = inject(Renderer2);
  private _animationsDisabled = _animationsDisabled();
  private _idGenerator = inject(_IdGenerator);

  /**
   * Theme color of the badge. This API is supported in M2 themes only, it
   * has no effect in M3 themes. For color customization in M3, see https://material.angular.dev/components/badge/styling.
   *
   * For information on applying color variants in M3, see
   * https://material.angular.dev/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-color-variants
   */
  @Input('matBadgeColor')
  get color(): ThemePalette {
    return this._color;
  }
  set color(value: ThemePalette) {
    this._setColor(value);
    this._color = value;
  }
  private _color: ThemePalette;

  /** Whether the badge should overlap its contents or not */
  @Input({alias: 'matBadgeOverlap', transform: booleanAttribute}) overlap: boolean;

  /** Whether the badge is disabled. */
  @Input({alias: 'matBadgeDisabled', transform: booleanAttribute}) disabled: boolean = false;

  /**
   * Position the badge should reside.
   * Accepts any combination of 'above'|'below' and 'before'|'after'
   */
  @Input('matBadgePosition') position: MatBadgePosition;

  /** The content for the badge */
  @Input('matBadge')
  get content(): string | number | undefined | null {
    return this._content;
  }
  set content(newContent: string | number | undefined | null) {
    this._updateRenderedContent(newContent);
  }
  private _content: string | number | undefined | null;

  /** Message used to describe the decorated element via aria-describedby */
  @Input('matBadgeDescription')
  get description(): string {
    return this._description;
  }
  set description(newDescription: string) {
    this._updateDescription(newDescription);
  }
  private _description!: string;

  /** Size of the badge. Can be 'small', 'medium', or 'large'. */
  @Input('matBadgeSize') size: MatBadgeSize;

  /** Whether the badge is hidden. */
  @Input({alias: 'matBadgeHidden', transform: booleanAttribute}) hidden: boolean = false;

  /** Visible badge element. */
  private _badgeElement: HTMLElement | undefined;

  /** Inline badge description. Used when the badge is applied to non-interactive host elements. */
  private _inlineBadgeDescription: HTMLElement | undefined;

  /** Whether the OnInit lifecycle hook has run yet */
  private _isInitialized = false;

  /** InteractivityChecker to determine if the badge host is focusable. */
  private _interactivityChecker = inject(InteractivityChecker);

  private _document = inject(DOCUMENT);

  constructor() {
    const config = inject(MAT_BADGE_CONFIG, {optional: true});
    const styleLoader = inject(_CdkPrivateStyleLoader);
    styleLoader.load(_MatBadgeStyleLoader);
    styleLoader.load(_VisuallyHiddenLoader);

    this._color = config?.color || 'primary';
    this.overlap = config?.overlap ?? true;
    this.position = config?.position || 'above after';
    this.size = config?.size || 'medium';

    if (typeof ngDevMode === 'undefined' || ngDevMode) {
      const nativeElement = this._elementRef.nativeElement;

      if (nativeElement.nodeType !== nativeElement.ELEMENT_NODE) {
        throw Error('matBadge must be attached to an element node.');
      }
    }
  }

  /** Whether the badge is above the host or not */
  isAbove(): boolean {
    return this.position.indexOf('below') === -1;
  }

  /** Whether the badge is after the host or not */
  isAfter(): boolean {
    return this.position.indexOf('before') === -1;
  }

  /**
   * Gets the element into which the badge's content is being rendered. Undefined if the element
   * hasn't been created (e.g. if the badge doesn't have content).
   */
  getBadgeElement(): HTMLElement | undefined {
    return this._badgeElement;
  }

  ngOnInit() {
    // We may have server-side rendered badge that we need to clear.
    // We need to do this in ngOnInit because the full content of the component
    // on which the badge is attached won't necessarily be in the DOM until this point.
    this._clearExistingBadges();

    if (this.content && !this._badgeElement) {
      this._badgeElement = this._createBadgeElement();
      this._updateRenderedContent(this.content);
    }

    this._isInitialized = true;
  }

  ngAfterViewInit() {
    if (typeof ngDevMode === 'undefined' || ngDevMode) {
      const nativeElement = this._elementRef.nativeElement;

      // Heads-up for developers to avoid putting matBadge on <mat-icon>
      // as it is aria-hidden by default docs mention this at:
      // https://material.angular.dev/components/badge/overview#accessibility
      if (
        nativeElement.tagName.toLowerCase() === 'mat-icon' &&
        nativeElement.getAttribute('aria-hidden') === 'true'
      ) {
        console.warn(
          `Detected a matBadge on an "aria-hidden" "<mat-icon>". ` +
            `Consider setting aria-hidden="false" in order to surface the information assistive technology.` +
            `\n${nativeElement.outerHTML}`,
        );
      }
    }
  }

  ngOnDestroy() {
    // ViewEngine only: when creating a badge through the Renderer, Angular remembers its index.
    // We have to destroy it ourselves, otherwise it'll be retained in memory.
    if (this._renderer.destroyNode) {
      this._renderer.destroyNode(this._badgeElement);
      this._inlineBadgeDescription?.remove();
    }

    this._ariaDescriber.removeDescription(this._elementRef.nativeElement, this.description);
  }

  /** Gets whether the badge's host element is interactive. */
  private _isHostInteractive(): boolean {
    // Ignore visibility since it requires an expensive style caluclation.
    return this._interactivityChecker.isFocusable(this._elementRef.nativeElement, {
      ignoreVisibility: true,
    });
  }

  /** Creates the badge element */
  private _createBadgeElement(): HTMLElement {
    const badgeElement = this._renderer.createElement('span');
    const activeClass = 'mat-badge-active';

    badgeElement.setAttribute('id', this._idGenerator.getId('mat-badge-content-'));

    // The badge is aria-hidden because we don't want it to appear in the page's navigation
    // flow. Instead, we use the badge to describe the decorated element with aria-describedby.
    badgeElement.setAttribute('aria-hidden', 'true');
    badgeElement.classList.add(BADGE_CONTENT_CLASS);

    if (this._animationsDisabled) {
      badgeElement.classList.add('_mat-animation-noopable');
    }

    this._elementRef.nativeElement.appendChild(badgeElement);

    // animate in after insertion
    if (typeof requestAnimationFrame === 'function' && !this._animationsDisabled) {
      this._ngZone.runOutsideAngular(() => {
        requestAnimationFrame(() => {
          badgeElement.classList.add(activeClass);
        });
      });
    } else {
      badgeElement.classList.add(activeClass);
    }

    return badgeElement;
  }

  /** Update the text content of the badge element in the DOM, creating the element if necessary. */
  private _updateRenderedContent(newContent: string | number | undefined | null): void {
    const newContentNormalized: string = `${newContent ?? ''}`.trim();

    // Don't create the badge element if the directive isn't initialized because we want to
    // append the badge element to the *end* of the host element's content for backwards
    // compatibility.
    if (this._isInitialized && newContentNormalized && !this._badgeElement) {
      this._badgeElement = this._createBadgeElement();
    }

    if (this._badgeElement) {
      this._badgeElement.textContent = newContentNormalized;
    }

    this._content = newContentNormalized;
  }

  /** Updates the host element's aria description via AriaDescriber. */
  private _updateDescription(newDescription: string): void {
    // Always start by removing the aria-describedby; we will add a new one if necessary.
    this._ariaDescriber.removeDescription(this._elementRef.nativeElement, this.description);

    // NOTE: We only check whether the host is interactive here, which happens during
    // when then badge content changes. It is possible that the host changes
    // interactivity status separate from one of these. However, watching the interactivity
    // status of the host would require a `MutationObserver`, which is likely more code + overhead
    // than it's worth; from usages inside Google, we see that the vats majority of badges either
    // never change interactivity, or also set `matBadgeHidden` based on the same condition.

    if (!newDescription || this._isHostInteractive()) {
      this._removeInlineDescription();
    }

    this._description = newDescription;

    // We don't add `aria-describedby` for non-interactive hosts elements because we
    // instead insert the description inline.
    if (this._isHostInteractive()) {
      this._ariaDescriber.describe(this._elementRef.nativeElement, newDescription);
    } else {
      this._updateInlineDescription();
    }
  }

  private _updateInlineDescription() {
    // Create the inline description element if it doesn't exist
    if (!this._inlineBadgeDescription) {
      this._inlineBadgeDescription = this._document.createElement('span');
      this._inlineBadgeDescription.classList.add('cdk-visually-hidden');
    }

    this._inlineBadgeDescription.textContent = this.description;
    this._badgeElement?.appendChild(this._inlineBadgeDescription);
  }

  private _removeInlineDescription() {
    this._inlineBadgeDescription?.remove();
    this._inlineBadgeDescription = undefined;
  }

  /** Adds css theme class given the color to the component host */
  private _setColor(colorPalette: ThemePalette) {
    const classList = this._elementRef.nativeElement.classList;
    classList.remove(`mat-badge-${this._color}`);
    if (colorPalette) {
      classList.add(`mat-badge-${colorPalette}`);
    }
  }

  /** Clears any existing badges that might be left over from server-side rendering. */
  private _clearExistingBadges() {
    // Only check direct children of this host element in order to avoid deleting
    // any badges that might exist in descendant elements.
    const badges = this._elementRef.nativeElement.querySelectorAll(
      `:scope > .${BADGE_CONTENT_CLASS}`,
    );
    for (const badgeElement of Array.from(badges)) {
      if (badgeElement !== this._badgeElement) {
        badgeElement.remove();
      }
    }
  }
}