/** * @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.io/license */ import {FocusMonitor, FocusableOption, FocusOrigin} from '@angular/cdk/a11y'; import {coerceBooleanProperty} from '@angular/cdk/coercion'; import { Attribute, ChangeDetectionStrategy, ChangeDetectorRef, Component, ElementRef, EventEmitter, forwardRef, Inject, Input, NgZone, OnDestroy, Optional, Output, ViewChild, ViewEncapsulation, AfterViewChecked, } from '@angular/core'; import {ControlValueAccessor, NG_VALUE_ACCESSOR} from '@angular/forms'; import { CanColor, CanColorCtor, CanDisable, CanDisableCtor, CanDisableRipple, CanDisableRippleCtor, HasTabIndex, HasTabIndexCtor, MatRipple, mixinColor, mixinDisabled, mixinDisableRipple, mixinTabIndex, } from '@angular/material/core'; import {ANIMATION_MODULE_TYPE} from '@angular/platform-browser/animations'; import {MAT_CHECKBOX_CLICK_ACTION, MatCheckboxClickAction} from './checkbox-config'; // Increasing integer for generating unique ids for checkbox components. let nextUniqueId = 0; /** * Provider Expression that allows mat-checkbox to register as a ControlValueAccessor. * This allows it to support [(ngModel)]. * @docs-private */ export const MAT_CHECKBOX_CONTROL_VALUE_ACCESSOR: any = { provide: NG_VALUE_ACCESSOR, useExisting: forwardRef(() => MatCheckbox), multi: true }; /** * Represents the different states that require custom transitions between them. * @docs-private */ export enum TransitionCheckState { /** The initial state of the component before any user interaction. */ Init, /** The state representing the component when it's becoming checked. */ Checked, /** The state representing the component when it's becoming unchecked. */ Unchecked, /** The state representing the component when it's becoming indeterminate. */ Indeterminate } /** Change event object emitted by MatCheckbox. */ export class MatCheckboxChange { /** The source MatCheckbox of the event. */ source: MatCheckbox; /** The new `checked` value of the checkbox. */ checked: boolean; } // Boilerplate for applying mixins to MatCheckbox. /** @docs-private */ class MatCheckboxBase { constructor(public _elementRef: ElementRef) {} } const _MatCheckboxMixinBase: HasTabIndexCtor & CanColorCtor & CanDisableRippleCtor & CanDisableCtor & typeof MatCheckboxBase = mixinTabIndex(mixinColor(mixinDisableRipple(mixinDisabled(MatCheckboxBase)), 'accent')); /** * A material design checkbox component. Supports all of the functionality of an HTML5 checkbox, * and exposes a similar API. A MatCheckbox can be either checked, unchecked, indeterminate, or * disabled. Note that all additional accessibility attributes are taken care of by the component, * so there is no need to provide them yourself. However, if you want to omit a label and still * have the checkbox be accessible, you may supply an [aria-label] input. * See: https://material.io/design/components/selection-controls.html */ @Component({ moduleId: module.id, selector: 'mat-checkbox', templateUrl: 'checkbox.html', styleUrls: ['checkbox.css'], exportAs: 'matCheckbox', host: { 'class': 'mat-checkbox', '[id]': 'id', '[attr.tabindex]': 'null', '[class.mat-checkbox-indeterminate]': 'indeterminate', '[class.mat-checkbox-checked]': 'checked', '[class.mat-checkbox-disabled]': 'disabled', '[class.mat-checkbox-label-before]': 'labelPosition == "before"', '[class._mat-animation-noopable]': `_animationMode === 'NoopAnimations'`, }, providers: [MAT_CHECKBOX_CONTROL_VALUE_ACCESSOR], inputs: ['disableRipple', 'color', 'tabIndex'], encapsulation: ViewEncapsulation.None, changeDetection: ChangeDetectionStrategy.OnPush }) export class MatCheckbox extends _MatCheckboxMixinBase implements ControlValueAccessor, AfterViewChecked, OnDestroy, CanColor, CanDisable, HasTabIndex, CanDisableRipple, FocusableOption { /** * Attached to the aria-label attribute of the host element. In most cases, aria-labelledby will * take precedence so this may be omitted. */ @Input('aria-label') ariaLabel: string = ''; /** * Users can specify the `aria-labelledby` attribute which will be forwarded to the input element */ @Input('aria-labelledby') ariaLabelledby: string | null = null; private _uniqueId: string = `mat-checkbox-${++nextUniqueId}`; /** A unique id for the checkbox input. If none is supplied, it will be auto-generated. */ @Input() id: string = this._uniqueId; /** Returns the unique id for the visual hidden input. */ get inputId(): string { return `${this.id || this._uniqueId}-input`; } /** Whether the checkbox is required. */ @Input() get required(): boolean { return this._required; } set required(value: boolean) { this._required = coerceBooleanProperty(value); } private _required: boolean; /** Whether the label should appear after or before the checkbox. Defaults to 'after' */ @Input() labelPosition: 'before' | 'after' = 'after'; /** Name value will be applied to the input element if present */ @Input() name: string | null = null; /** Event emitted when the checkbox's `checked` value changes. */ @Output() readonly change: EventEmitter = new EventEmitter(); /** Event emitted when the checkbox's `indeterminate` value changes. */ @Output() readonly indeterminateChange: EventEmitter = new EventEmitter(); /** The value attribute of the native input element */ @Input() value: string; /** The native `` element */ @ViewChild('input', {static: false}) _inputElement: ElementRef; /** Reference to the ripple instance of the checkbox. */ @ViewChild(MatRipple, {static: false}) ripple: MatRipple; /** * Called when the checkbox is blurred. Needed to properly implement ControlValueAccessor. * @docs-private */ _onTouched: () => any = () => {}; private _currentAnimationClass: string = ''; private _currentCheckState: TransitionCheckState = TransitionCheckState.Init; private _controlValueAccessorChangeFn: (value: any) => void = () => {}; constructor(elementRef: ElementRef, private _changeDetectorRef: ChangeDetectorRef, private _focusMonitor: FocusMonitor, private _ngZone: NgZone, @Attribute('tabindex') tabIndex: string, @Optional() @Inject(MAT_CHECKBOX_CLICK_ACTION) private _clickAction: MatCheckboxClickAction, @Optional() @Inject(ANIMATION_MODULE_TYPE) public _animationMode?: string) { super(elementRef); this.tabIndex = parseInt(tabIndex) || 0; this._focusMonitor.monitor(elementRef, true).subscribe(focusOrigin => { if (!focusOrigin) { // When a focused element becomes disabled, the browser *immediately* fires a blur event. // Angular does not expect events to be raised during change detection, so any state change // (such as a form control's 'ng-touched') will cause a changed-after-checked error. // See https://github.com/angular/angular/issues/17793. To work around this, we defer // telling the form control it has been touched until the next tick. Promise.resolve().then(() => { this._onTouched(); _changeDetectorRef.markForCheck(); }); } }); } // TODO: Delete next major revision. ngAfterViewChecked() {} ngOnDestroy() { this._focusMonitor.stopMonitoring(this._elementRef); } /** * Whether the checkbox is checked. */ @Input() get checked(): boolean { return this._checked; } set checked(value: boolean) { if (value != this.checked) { this._checked = value; this._changeDetectorRef.markForCheck(); } } private _checked: boolean = false; /** * Whether the checkbox is disabled. This fully overrides the implementation provided by * mixinDisabled, but the mixin is still required because mixinTabIndex requires it. */ @Input() get disabled() { return this._disabled; } set disabled(value: any) { const newValue = coerceBooleanProperty(value); if (newValue !== this.disabled) { this._disabled = newValue; this._changeDetectorRef.markForCheck(); } } private _disabled: boolean = false; /** * Whether the checkbox is indeterminate. This is also known as "mixed" mode and can be used to * represent a checkbox with three states, e.g. a checkbox that represents a nested list of * checkable items. Note that whenever checkbox is manually clicked, indeterminate is immediately * set to false. */ @Input() get indeterminate(): boolean { return this._indeterminate; } set indeterminate(value: boolean) { const changed = value != this._indeterminate; this._indeterminate = value; if (changed) { if (this._indeterminate) { this._transitionCheckState(TransitionCheckState.Indeterminate); } else { this._transitionCheckState( this.checked ? TransitionCheckState.Checked : TransitionCheckState.Unchecked); } this.indeterminateChange.emit(this._indeterminate); } } private _indeterminate: boolean = false; _isRippleDisabled() { return this.disableRipple || this.disabled; } /** Method being called whenever the label text changes. */ _onLabelTextChange() { // Since the event of the `cdkObserveContent` directive runs outside of the zone, the checkbox // component will be only marked for check, but no actual change detection runs automatically. // Instead of going back into the zone in order to trigger a change detection which causes // *all* components to be checked (if explicitly marked or not using OnPush), we only trigger // an explicit change detection for the checkbox view and its children. this._changeDetectorRef.detectChanges(); } // Implemented as part of ControlValueAccessor. writeValue(value: any) { this.checked = !!value; } // Implemented as part of ControlValueAccessor. registerOnChange(fn: (value: any) => void) { this._controlValueAccessorChangeFn = fn; } // Implemented as part of ControlValueAccessor. registerOnTouched(fn: any) { this._onTouched = fn; } // Implemented as part of ControlValueAccessor. setDisabledState(isDisabled: boolean) { this.disabled = isDisabled; } _getAriaChecked(): 'true' | 'false' | 'mixed' { return this.checked ? 'true' : (this.indeterminate ? 'mixed' : 'false'); } private _transitionCheckState(newState: TransitionCheckState) { let oldState = this._currentCheckState; let element: HTMLElement = this._elementRef.nativeElement; if (oldState === newState) { return; } if (this._currentAnimationClass.length > 0) { element.classList.remove(this._currentAnimationClass); } this._currentAnimationClass = this._getAnimationClassForCheckStateTransition( oldState, newState); this._currentCheckState = newState; if (this._currentAnimationClass.length > 0) { element.classList.add(this._currentAnimationClass); // Remove the animation class to avoid animation when the checkbox is moved between containers const animationClass = this._currentAnimationClass; this._ngZone.runOutsideAngular(() => { setTimeout(() => { element.classList.remove(animationClass); }, 1000); }); } } private _emitChangeEvent() { const event = new MatCheckboxChange(); event.source = this; event.checked = this.checked; this._controlValueAccessorChangeFn(this.checked); this.change.emit(event); } /** Toggles the `checked` state of the checkbox. */ toggle(): void { this.checked = !this.checked; } /** * Event handler for checkbox input element. * Toggles checked state if element is not disabled. * Do not toggle on (change) event since IE doesn't fire change event when * indeterminate checkbox is clicked. * @param event */ _onInputClick(event: Event) { // We have to stop propagation for click events on the visual hidden input element. // By default, when a user clicks on a label element, a generated click event will be // dispatched on the associated input element. Since we are using a label element as our // root container, the click event on the `checkbox` will be executed twice. // The real click event will bubble up, and the generated click event also tries to bubble up. // This will lead to multiple click events. // Preventing bubbling for the second event will solve that issue. event.stopPropagation(); // If resetIndeterminate is false, and the current state is indeterminate, do nothing on click if (!this.disabled && this._clickAction !== 'noop') { // When user manually click on the checkbox, `indeterminate` is set to false. if (this.indeterminate && this._clickAction !== 'check') { Promise.resolve().then(() => { this._indeterminate = false; this.indeterminateChange.emit(this._indeterminate); }); } this.toggle(); this._transitionCheckState( this._checked ? TransitionCheckState.Checked : TransitionCheckState.Unchecked); // Emit our custom change event if the native input emitted one. // It is important to only emit it, if the native input triggered one, because // we don't want to trigger a change event, when the `checked` variable changes for example. this._emitChangeEvent(); } else if (!this.disabled && this._clickAction === 'noop') { // Reset native input when clicked with noop. The native checkbox becomes checked after // click, reset it to be align with `checked` value of `mat-checkbox`. this._inputElement.nativeElement.checked = this.checked; this._inputElement.nativeElement.indeterminate = this.indeterminate; } } /** Focuses the checkbox. */ focus(origin: FocusOrigin = 'keyboard', options?: FocusOptions): void { this._focusMonitor.focusVia(this._inputElement, origin, options); } _onInteractionEvent(event: Event) { // We always have to stop propagation on the change event. // Otherwise the change event, from the input element, will bubble up and // emit its event object to the `change` output. event.stopPropagation(); } private _getAnimationClassForCheckStateTransition( oldState: TransitionCheckState, newState: TransitionCheckState): string { // Don't transition if animations are disabled. if (this._animationMode === 'NoopAnimations') { return ''; } let animSuffix: string = ''; switch (oldState) { case TransitionCheckState.Init: // Handle edge case where user interacts with checkbox that does not have [(ngModel)] or // [checked] bound to it. if (newState === TransitionCheckState.Checked) { animSuffix = 'unchecked-checked'; } else if (newState == TransitionCheckState.Indeterminate) { animSuffix = 'unchecked-indeterminate'; } else { return ''; } break; case TransitionCheckState.Unchecked: animSuffix = newState === TransitionCheckState.Checked ? 'unchecked-checked' : 'unchecked-indeterminate'; break; case TransitionCheckState.Checked: animSuffix = newState === TransitionCheckState.Unchecked ? 'checked-unchecked' : 'checked-indeterminate'; break; case TransitionCheckState.Indeterminate: animSuffix = newState === TransitionCheckState.Checked ? 'indeterminate-checked' : 'indeterminate-unchecked'; break; } return `mat-checkbox-anim-${animSuffix}`; } }