@progress/kendo-angular-dropdowns
Version:
A wide variety of native Angular dropdown components including AutoComplete, ComboBox, DropDownList, DropDownTree, MultiColumnComboBox, MultiSelect, and MultiSelectTree
707 lines (706 loc) • 26.5 kB
TypeScript
/**-----------------------------------------------------------------------------------------
* Copyright © 2025 Progress Software Corporation. All rights reserved.
* Licensed under commercial license. See LICENSE.md in the project root for more information
*-------------------------------------------------------------------------------------------*/
import { AdaptiveMode } from '../common/util';
import { SearchBarComponent } from '../common/searchbar.component';
import { Renderer2, ViewContainerRef, ElementRef, TemplateRef, OnDestroy, OnChanges, DoCheck, EventEmitter, AfterContentChecked, AfterViewInit, ChangeDetectorRef, KeyValueDiffers, NgZone, OnInit, Injector } from '@angular/core';
import { Observable } from 'rxjs';
import { SuffixTemplateDirective, PrefixTemplateDirective } from '@progress/kendo-angular-common';
import { AdaptiveSize, AdaptiveService } from '@progress/kendo-angular-utils';
import { FormControl } from '@angular/forms';
import { SelectionService, SelectionEvent } from '../common/selection/selection.service';
import { PopupSettings } from '../common/models/popup-settings';
import { NavigationService } from '../common/navigation/navigation.service';
import { DisabledItemsService } from '../common/disabled-items/disabled-items.service';
import { ItemDisabledFn } from '../common/disabled-items/item-disabled';
import { ItemTemplateDirective } from '../common/templates/item-template.directive';
import { CustomItemTemplateDirective } from '../common/templates/custom-item-template.directive';
import { GroupTemplateDirective } from '../common/templates/group-template.directive';
import { FixedGroupTemplateDirective } from '../common/templates/fixed-group-template.directive';
import { HeaderTemplateDirective } from '../common/templates/header-template.directive';
import { FooterTemplateDirective } from '../common/templates/footer-template.directive';
import { TagTemplateDirective } from '../common/templates/tag-template.directive';
import { GroupTagTemplateDirective } from '../common/templates/group-tag-template.directive';
import { NoDataTemplateDirective } from '../common/templates/no-data-template.directive';
import { PreventableEvent } from '../common/models/preventable-event';
import { RemoveTagEvent } from '../common/models/remove-tag-event';
import { LocalizationService } from '@progress/kendo-angular-l10n';
import { PopupService, PopupRef } from '@progress/kendo-angular-popup';
import { FilterableComponent } from '../common/filtering/filterable-component';
import { DataService } from '../common/data.service';
import { ListComponent } from '../common/list.component';
import { MultiSelectCheckableSettings } from '../common/models/checkboxes-settings';
import { VirtualizationSettings } from '../common/models/virtualization-settings';
import { PageChangeEvent } from '../common/models/page-change-event';
import { DropDownSize } from '../common/models/size';
import { DropDownRounded } from '../common/models/rounded';
import { DropDownFillMode } from '../common/models/fillmode';
import { SVGIcon } from '@progress/kendo-svg-icons';
import { ActionSheetComponent } from '@progress/kendo-angular-navigation';
import { TextBoxComponent } from '@progress/kendo-angular-inputs';
import { ResponsiveRendererComponent } from '../common/action-sheet.component';
import { TagListComponent } from '../common/taglist.component';
import * as i0 from "@angular/core";
/**
* Represents the [Kendo UI MultiSelect component for Angular]({% slug overview_multiselect %}).
*
* @example
* ```ts
* _@Component({
* selector: 'my-app',
* template: `
* <kendo-multiselect [data]="listItems">
* </kendo-multiselect>
* `
* })
* class AppComponent {
* public listItems: Array<string> = ["Item 1", "Item 2", "Item 3", "Item 4"];
* }
* ```
*/
export declare class MultiSelectComponent implements OnDestroy, OnChanges, OnInit, DoCheck, AfterContentChecked, AfterViewInit, FilterableComponent {
wrapper: ElementRef;
private localization;
private popupService;
private dataService;
private selectionService;
private navigationService;
private disabledItemsService;
private cdr;
private differs;
private renderer;
private _zone;
private injector;
hostElement: ElementRef;
private adaptiveService;
/**
* @hidden
*/
animationDuration: number;
/**
* @hidden
*/
xIcon: SVGIcon;
/**
* @hidden
*/
plusIcon: SVGIcon;
listBoxId: string;
tagListId: string;
tagPrefix: string;
optionPrefix: string;
popupRef: PopupRef;
text: string;
tags: any[];
focusedTagIndex: number;
/**
* @hidden
*/
responsiveRendererComponent: ResponsiveRendererComponent;
/**
* @hidden
*/
get actionSheet(): ActionSheetComponent;
/**
* @hidden
*/
get actionSheetSearchBar(): TextBoxComponent;
/**
* @hidden
*/
get ariaControls(): string;
/**
* @hidden
*/
get isControlRequired(): boolean;
/**
* @hidden
*/
get formControl(): FormControl;
/**
* Focuses a specific item of the MultiSelect based on a provided index.
* If there is a custom item it is positioned at index -1.
* If null or invalid index is provided the focus will be removed.
*/
focusItemAt(index: number): void;
/**
* Focuses the MultiSelect.
*/
focus(): void;
/**
* @hidden
*/
handleInputFocus(): void;
/**
* @hidden
*/
onAdaptiveTextBoxChange(text: string): void;
/**
* Blurs the MultiSelect.
*/
blur(): void;
/**
* @hidden
*/
handleFocus(): void;
/**
* @hidden
*/
handleBlur(): void;
/**
* @hidden
*/
handleInputBlur(): void;
/**
* @hidden
*/
onPointerDown(event: any): void;
/**
* @hidden
*/
onResize(): void;
get appendTo(): ViewContainerRef;
/**
* Shows or hides the current group sticky header when using grouped data.
* By default the sticky header is displayed ([see example]({% slug grouping_autocomplete %}#toc-sticky-header)).
*/
showStickyHeader: boolean;
/**
* @hidden
*/
focusableId: string;
/**
* Determines whether to close the options list of the MultiSelect after the item selection is finished
* ([see example]({% slug openstate_multiselect %}#toc-keeping-the-options-list-open-while-on-focus)).
* @default true
*/
autoClose: boolean;
/**
* Sets and gets the loading state of the MultiSelect.
*/
loading: boolean;
/**
* Sets the data of the MultiSelect.
*
* > The data has to be provided in an array-like list of items.
*/
set data(data: any[]);
get data(): any[];
/**
* Sets the value of the MultiSelect. It can be either of the primitive (string, numbers) or of the complex (objects) type.
* To define the type, use the `valuePrimitive` option.
*
* > All selected values which are not present in the source are ignored.
*/
set value(values: any[]);
get value(): any[];
/**
* Sets the data item field that represents the item value.
* If the data contains only primitive values, do not define it.
*
* > The `valueField` property can be set to point to a nested property value - e.g. `category.id`.
*/
valueField: string;
/**
* Sets the data item field that represents the item text.
* If the data contains only primitive values, do not define it.
*
* > The `textField` property can be set to point to a nested property value - e.g. `category.name`.
*/
textField: string;
/**
* Specifies the [`tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) of the component.
*/
tabindex: number;
/**
* @hidden
*/
set tabIndex(tabIndex: number);
get tabIndex(): number;
/**
* Sets the size of the component.
*
* The possible values are:
* * `small`
* * `medium` (default)
* * `large`
* * `none`
*
*/
set size(size: DropDownSize);
get size(): DropDownSize;
/**
* Sets the border radius of the component.
*
* The possible values are:
* * `small`
* * `medium` (default)
* * `large`
* * `full`
* * `none`
*
*/
set rounded(rounded: DropDownRounded);
get rounded(): DropDownRounded;
/**
* Sets the fillMode of the component.
*
* The possible values are:
* * `flat`
* * `solid` (default)
* * `outline`
* * `none`
*
*/
set fillMode(fillMode: DropDownFillMode);
get fillMode(): DropDownFillMode;
/**
* The hint which is displayed when the component is empty.
* When the values are selected, it disappears.
*/
set placeholder(text: string);
get placeholder(): string;
/**
* Enables or disables the adaptive mode. By default the adaptive rendering is disabled.
*/
adaptiveMode: AdaptiveMode;
/**
* Sets the title of the ActionSheet that is rendered instead of the Popup when using small screen devices.
* By default the ActionSheet title uses the text provided for the label of the AutoComplete.
*/
title: string;
/**
* Sets the subtitle of the ActionSheet that is rendered instead of the Popup when using small screen devices.
* By default the ActionSheet subtitle uses the text provided for the `placeholder` of the AutoComplete.
*/
set subtitle(_subtitle: string);
get subtitle(): string;
/**
* @hidden
*/
get isAdaptiveModeEnabled(): boolean;
/**
* Sets the disabled state of the component. To learn how to disable the component in reactive forms, refer to the article on [Forms Support](slug:formssupport_multiselect#toc-managing-the-multiselect-disabled-state-in-reactive-forms).
*/
disabled: boolean;
/**
* Defines a Boolean function that is executed for each data item in the component
* ([see examples]({% slug disableditems_multiselect %})). Determines whether the item will be disabled.
*/
set itemDisabled(fn: ItemDisabledFn);
/**
* Specifies whether checkboxes will be rendered before each item in the popup list.
*/
set checkboxes(settings: MultiSelectCheckableSettings | boolean);
get checkboxes(): MultiSelectCheckableSettings;
/**
* Sets the read-only state of the component.
*
* @default false
*/
readonly: boolean;
/**
* Enables the [filtering]({% slug filtering_multiselect %}) functionality of the MultiSelect.
*/
filterable: boolean;
/**
* Enables the [virtualization]({% slug virtualization_multiselect %}) functionality.
*/
set virtual(settings: boolean | VirtualizationSettings);
get virtual(): VirtualizationSettings;
/**
* Configures the popup of the MultiSelect.
*
* The available options are:
* - `animate: Boolean`—Controls the popup animation. By default, the open and close animations are enabled.
* - `width: Number | String`—Sets the width of the popup container. By default, the width of the host element is used. If set to `auto`, the component automatically adjusts the width of the popup and no item labels are wrapped. The `auto` mode is not supported when virtual scrolling is enabled.
* - `height: Number`—Sets the height of the popup container.
* - `popupClass: String`—Specifies a list of CSS classes that are used to style the popup.
* - `appendTo: "root" | "component" | ViewContainerRef`—Specifies the component to which the popup will be appended.
*/
set popupSettings(settings: PopupSettings);
get popupSettings(): PopupSettings;
/**
* Sets the height of the options list in the popup. By default, `listHeight` is 200px.
*
* > The `listHeight` property affects only the list of options and not the whole popup container.
* > To set the height of the popup container, use `popupSettings.height`.
*
* > When using `adaptiveMode` and the screen size is `small` or `medium` the `listHeight` property is set to null.
*/
set listHeight(_listHeight: number);
get listHeight(): number;
private _listHeight;
/**
* Specifies the type of the selected value.
* If set to `true`, the selected value has to be of the primitive type
* ([more information and example]({% slug valuebinding_multiselect %}#toc-primitive-values-from-object-fields)).
*/
set valuePrimitive(isPrimitive: boolean);
get valuePrimitive(): boolean;
/**
* If set to `true`, renders a button on hovering over the component.
* Clicking this button resets the value of the component to an empty array and triggers the `change` event.
*/
clearButton: boolean;
/**
* A user-defined callback function which receives an array of selected data items and maps them to an array of tags
* ([see examples]({% slug summarytagmode_multiselect %}#toc-rendering-of-tags)).
*
* @param { Any[] } dataItems - The selected data items from the list.
* @returns { Any[] } - The tags that will be rendered by the component.
*/
tagMapper: (tags: any) => any;
/**
* Specifies whether the MultiSelect allows user-defined values that are not present in the dataset
* ([more information and examples]({% slug custom_values_multiselect %})).
* Defaults to `false`.
*
* The feature is not available when using adaptive mode.
*/
allowCustom: boolean;
/**
* A user-defined callback function which returns normalized custom values.
* Typically used when the data items are different from type `string`.
*
* @param { Any } value - The custom value that is defined by the user.
* @returns { Any }
*
* @example
* ```ts
* import { map } from 'rxjs/operators';
*
* _@Component({
* selector: 'my-app',
* template: `
* <kendo-multiselect
* [allowCustom]="true"
* [data]="listItems"
* textField="text"
* valueField="value"
* [valueNormalizer]="valueNormalizer"
* (valueChange)="onValueChange($event)"
* >
* </kendo-multiselect>
* `
* })
*
* class AppComponent {
* public listItems: Array<{ text: string, value: number }> = [
* { text: "Small", value: 1 },
* { text: "Medium", value: 2 },
* { text: "Large", value: 3 }
* ];
*
* public onValueChange(value) {
* console.log("valueChange : ", value);
* }
*
* public valueNormalizer = (text$: Observable<string>) => text$.pipe(map((text: string) => {
* return {
* value: Math.floor(Math.random() * (1000 - 100) + 1000), //generate unique valueField
* text: text };
* }));
*
* }
* ```
*/
valueNormalizer: (text: Observable<string>) => Observable<any>;
/**
* Sets the HTML attributes of the inner focusable input element. Attributes which are essential for certain component functionalities cannot be changed.
*/
inputAttributes: {
[key: string]: string;
};
/**
* Fires each time the user types in the input field.
* You can filter the source based on the passed filtration value.
*/
filterChange: EventEmitter<string>;
/**
* Fires each time the value is changed—
* when the component is blurred or the value is cleared through the **Clear** button
* ([see example](slug:events_multiselect)).
* When the value of the component is programmatically changed to `ngModel` or `formControl`
* through its API or form binding, the `valueChange` event is not triggered because it
* might cause a mix-up with the built-in `valueChange` mechanisms of the `ngModel` or `formControl` bindings.
*/
valueChange: EventEmitter<any[]>;
/**
* Fires each time the popup is about to open
* ([see example]({% slug openstate_multiselect %}#toc-preventing-opening-and-closing)).
* This event is preventable. If you cancel it, the popup will remain closed.
*/
open: EventEmitter<PreventableEvent>;
/**
* Fires after the popup has been opened.
*/
opened: EventEmitter<any>;
/**
* Fires each time the popup is about to close
* ([see example]({% slug openstate_multiselect %}#toc-preventing-opening-and-closing)).
* This event is preventable. If you cancel it, the popup will remain open.
*/
close: EventEmitter<PreventableEvent>;
/**
* Fires after the popup has been closed.
*/
closed: EventEmitter<any>;
/**
* Fires each time the user focuses the MultiSelect.
*/
onFocus: EventEmitter<any>;
/**
* Fires each time the MultiSelect gets blurred.
*/
onBlur: EventEmitter<any>;
/**
* Fires each time the user focuses the `input` element.
*/
inputFocus: EventEmitter<any>;
/**
* Fires each time the `input` element gets blurred.
*/
inputBlur: EventEmitter<any>;
/**
* Fires each time a tag is about to be removed([see examples]({% slug summarytagmode_multiselecttree %}#toc-notifying-on-removing-group-tags)).
* This event is preventable. If you cancel it, the tag will not be removed.
*/
removeTag: EventEmitter<RemoveTagEvent>;
container: ViewContainerRef;
searchbar: SearchBarComponent;
tagList: TagListComponent;
popupTemplate: TemplateRef<any>;
optionsList: ListComponent;
template: ItemTemplateDirective;
customItemTemplate: CustomItemTemplateDirective;
groupTemplate: GroupTemplateDirective;
fixedGroupTemplate: FixedGroupTemplateDirective;
headerTemplate: HeaderTemplateDirective;
footerTemplate: FooterTemplateDirective;
tagTemplate: TagTemplateDirective;
groupTagTemplate: GroupTagTemplateDirective;
noDataTemplate: NoDataTemplateDirective;
/**
* @hidden
*/
suffixTemplate: SuffixTemplateDirective;
/**
* @hidden
*/
prefixTemplate: PrefixTemplateDirective;
hostClasses: boolean;
get dir(): string;
get disabledClass(): boolean;
get isLoading(): boolean;
/**
* @hidden
*/
windowSize: AdaptiveSize;
/**
* @hidden
*/
get isActionSheetExpanded(): boolean;
/**
* @hidden
*/
get isAdaptive(): boolean;
disabledIndices: Set<number>;
private initialized;
private _size;
private _rounded;
private _fillMode;
private _subtitle;
private _valueHolder;
constructor(wrapper: ElementRef, localization: LocalizationService, popupService: PopupService, dataService: DataService, selectionService: SelectionService, navigationService: NavigationService, disabledItemsService: DisabledItemsService, cdr: ChangeDetectorRef, differs: KeyValueDiffers, renderer: Renderer2, _zone: NgZone, injector: Injector, hostElement: ElementRef, adaptiveService: AdaptiveService);
get listContainerClasses(): any[];
/**
* @hidden
*/
get customItemSizeClass(): any;
get width(): any;
get height(): any;
get activeDescendant(): string;
get clearButtonVisiblity(): string;
/**
* @hidden
*/
applyValue(): void;
/**
* @hidden
*/
cancelValue(): void;
/**
* @hidden
*/
verifySettings(): void;
/**
* @hidden
*/
change(event: SelectionEvent): void;
/**
* @hidden
*/
setState(value: any[]): void;
/**
* @hidden
*/
handleFilter(text: string): void;
/**
* @hidden
*/
pageChange(event: PageChangeEvent): void;
/**
* @hidden
*/
clearFilter(): void;
/**
* @hidden
*/
handleNavigate(event: any): void;
/**
* @hidden
*/
handleRemoveTag({ tag }: {
tag: any;
index?: number;
}): void;
/**
* @hidden
*/
clearAll(event?: any): void;
/**
* @hidden
*/
protected addCustomValue(text: string): void;
ngAfterContentChecked(): void;
ngDoCheck(): void;
ngOnInit(): void;
ngOnChanges(changes: any): void;
ngAfterViewInit(): void;
ngOnDestroy(): void;
/**
* Toggles the visibility of the popup or actionSheet
* ([see example]({% slug openstate_multiselect %}#toc-setting-the-initially-opened-component)).
* If you use the `toggle` method to open or close the popup or actionSheet, the respective `open` and `close` events will not be fired.
*
* @param open - The state of the popup.
*/
toggle(open?: boolean): void;
/**
* Returns the current open state. Returns `true` if the popup or actionSheet is open.
*/
get isOpen(): boolean;
/**
* Resets the value of the MultiSelect.
* If you use the `reset` method to clear the value of the component,
* the model will not update automatically and the `selectionChange` and `valueChange` events will not be fired.
*/
reset(): void;
/**
* @hidden
*/
messageFor(key: string): string;
/**
* @hidden
*/
writeValue(value: any): void;
/**
* @hidden
*/
registerOnChange(fn: any): void;
/**
* @hidden
*/
registerOnTouched(fn: any): void;
/**
* @hidden
*/
setDisabledState(isDisabled: boolean): void;
/**
* @hidden
*/
onTagMapperChange(): void;
/**
* @hidden
*/
handleClick(): void;
protected onChangeCallback: Function;
protected onTouchedCallback: Function;
private _placeholder;
private _open;
private _value;
private _popupSettings;
private _virtualSettings;
private _valuePrimitive;
private _checkboxes;
private _isFocused;
set isFocused(isFocused: boolean);
get isFocused(): boolean;
private selectedDataItems;
private popupPointerDownHandler;
private isOpenPrevented;
private customValueSubject;
private customValueSubscription;
private subs;
private touchstartDisposeHandler;
private direction;
private differ;
private valueChangeDetected;
private subscribeEvents;
private subscribeTouchEvents;
private unsubscribeEvents;
private removeGroupTag;
private removeSingleTag;
/**
* @hidden
*
* Determines which of the provided tags should be disabled and stores their position indices
*/
private disabledItemsMapper;
private createCustomValueStream;
private handleItemChange;
private handleMousedown;
private handleKeydown;
private handleEnter;
private handleClose;
private handleEnd;
private handleHome;
private sortSelectionAscending;
private handleSelectAll;
private handleSelectAllToBeginning;
private handleSelectAllToEnd;
private handleSelectUpDown;
/**
* Selects all items between the focused item and the last clicked item (index). Also removes all other selected items.
*/
private selectRangeFromTo;
private handleUp;
private handleBackspace;
private handleDelete;
private handleLeftKey;
private handleDownKey;
private handleRightKey;
private findIndex;
private searchTextAndFocus;
private closePopup;
private openPopup;
/**
* @hidden
*/
togglePopup(open: boolean): void;
private triggerPopupEvents;
private _toggle;
private destroyPopup;
private createPopup;
private emitValueChange;
private resolveDataItemFromTags;
private firstFocusableIndex;
private nextTick;
private setComponentClasses;
private closeActionSheet;
private openActionSheet;
static ɵfac: i0.ɵɵFactoryDeclaration<MultiSelectComponent, never>;
static ɵcmp: i0.ɵɵComponentDeclaration<MultiSelectComponent, "kendo-multiselect", ["kendoMultiSelect"], { "showStickyHeader": { "alias": "showStickyHeader"; "required": false; }; "focusableId": { "alias": "focusableId"; "required": false; }; "autoClose": { "alias": "autoClose"; "required": false; }; "loading": { "alias": "loading"; "required": false; }; "data": { "alias": "data"; "required": false; }; "value": { "alias": "value"; "required": false; }; "valueField": { "alias": "valueField"; "required": false; }; "textField": { "alias": "textField"; "required": false; }; "tabindex": { "alias": "tabindex"; "required": false; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "size": { "alias": "size"; "required": false; }; "rounded": { "alias": "rounded"; "required": false; }; "fillMode": { "alias": "fillMode"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "adaptiveMode": { "alias": "adaptiveMode"; "required": false; }; "title": { "alias": "title"; "required": false; }; "subtitle": { "alias": "subtitle"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "itemDisabled": { "alias": "itemDisabled"; "required": false; }; "checkboxes": { "alias": "checkboxes"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "filterable": { "alias": "filterable"; "required": false; }; "virtual": { "alias": "virtual"; "required": false; }; "popupSettings": { "alias": "popupSettings"; "required": false; }; "listHeight": { "alias": "listHeight"; "required": false; }; "valuePrimitive": { "alias": "valuePrimitive"; "required": false; }; "clearButton": { "alias": "clearButton"; "required": false; }; "tagMapper": { "alias": "tagMapper"; "required": false; }; "allowCustom": { "alias": "allowCustom"; "required": false; }; "valueNormalizer": { "alias": "valueNormalizer"; "required": false; }; "inputAttributes": { "alias": "inputAttributes"; "required": false; }; }, { "filterChange": "filterChange"; "valueChange": "valueChange"; "open": "open"; "opened": "opened"; "close": "close"; "closed": "closed"; "onFocus": "focus"; "onBlur": "blur"; "inputFocus": "inputFocus"; "inputBlur": "inputBlur"; "removeTag": "removeTag"; }, ["template", "customItemTemplate", "groupTemplate", "fixedGroupTemplate", "headerTemplate", "footerTemplate", "tagTemplate", "groupTagTemplate", "noDataTemplate", "suffixTemplate", "prefixTemplate"], never, true, never>;
}