ng select Загрузить - ng select Загрузка исходного кода

ng select

Другой исходный код

v14.0.0

Скачать

Angular ng-select — легкий выбор пользовательского интерфейса «все в одном», множественный выбор и автозаполнение

См. Демо-страницу.

Версии

Угловой	ng-выбрать
>=19.0.0 <20.0.0	v14.x
>=18.0.0 <19.0.0	v13.x
>=17.0.0 <18.0.0	v12.x
>=16.0.0 <17.0.0	v11.x
>=15.0.0 <16.0.0	v10.x
>=14.0.0 <15.0.0	v9.x
>=13.0.0 <14.0.0	v8.x
>=12.0.0 <13.0.0	v7.x
>=11.0.0 <12.0.0	v6.x
>=10.0.0 <11.0.0	v5.x
>=9.0.0 <10.0.0	v4.x
>=8.0.0 <9.0.0	v3.x
>=6.0.0 <8.0.0	v2.x
v5.xx	v1.x

Поддержка браузера

ng-select поддерживает все браузеры, поддерживаемые Angular. Текущий список см. на странице https://angular.io/guide/browser-support#browser-support. Сюда входят следующие конкретные версии:

 Chrome	2 most recent versions
Firefox	latest and extended support release (ESR)
Edge	2 most recent major versions
Safari	2 most recent major versions
iOS	2 most recent major versions
Android	2 most recent major versions

Функции

Предупреждение

Библиотека находится в активной разработке и может иметь критические изменения API для последующих основных версий после 1.0.0.

Начиная

Шаг 1. Установите `ng-select` :

НПМ

npm install --save @ng-select/ng-select

ПРЯЖА

yarn add @ng-select/ng-select

Шаг 2:

Автономный режим: импортируйте NgSelectComponent и другие необходимые директивы напрямую:

 import { NgLabelTemplateDirective , NgOptionTemplateDirective , NgSelectComponent } from '@ng-select/ng-select' ;
import { FormsModule } from '@angular/forms' ;

@ Component ( {
  selector : 'example' ,
  standalone : true ,
  template : './example.component.html' ,
  styleUrl : './example.component.scss' ,
  imports : [
    NgLabelTemplateDirective ,
    NgOptionTemplateDirective ,
    NgSelectComponent ,
  ] ,
} )
export class ExampleComponent { }

NgModule: импортируйте модуль NgSelectModule и angular FormsModule:

 import { NgSelectModule } from '@ng-select/ng-select' ;
import { FormsModule } from '@angular/forms' ;

@ NgModule ( {
  declarations : [ AppComponent ] ,
  imports : [ NgSelectModule , FormsModule ] ,
  bootstrap : [ AppComponent ]
} )
export class AppModule { }

Шаг 3. Добавьте тему:

Чтобы обеспечить возможность настройки и оформления тем, пакет ng-select включает только общие стили, необходимые для правильного макета и позиционирования. Чтобы получить полный вид элемента управления, включите в свое приложение одну из тем. Если вы используете Angular CLI, вы можете добавить это в свой styles.scss или включить его в .angular-cli.json (Angular v5 и ниже) или angular.json (Angular v6 и более поздние версии).

 @import " ~@ng-select/ng-select/themes/default.theme.css " ;
// ... or 
@import " ~@ng-select/ng-select/themes/material.theme.css " ;

Шаг 4 (необязательно): Настройка

Вы также можете установить сообщения глобальной конфигурации и локализации, внедрив службу NgSelectConfig, обычно в корневой компонент, и настроив значения ее свойств, чтобы предоставить значения по умолчанию.

  constructor ( private config : NgSelectConfig ) {
      this . config . notFoundText = 'Custom not found' ;
      this . config . appendTo = 'body' ;
      // set the bindValue to global config when you use the same 
      // bindValue in most of the place. 
      // You can also override bindValue for the specified template 
      // by defining `bindValue` as property
      // Eg : <ng-select bindValue="some-new-value"></ng-select>
      this . config . bindValue = 'value' ;
  }

Использование

Определите параметры в вашем потребляющем компоненте:

@ Component ( { ... } )
export class ExampleComponent {

    selectedCar : number ;

    cars = [
        { id : 1 , name : 'Volvo' } ,
        { id : 2 , name : 'Saab' } ,
        { id : 3 , name : 'Opel' } ,
        { id : 4 , name : 'Audi' } ,
    ] ;
}

В шаблоне используйте компонент ng-select с вашими параметрами.

 <!--Using ng-option and for loop-->
< ng-select [(ngModel)] =" selectedCar " >
    @for (car of cars; track car.id) {
        < ng-option [value] =" car.id " > {{car.name}} </ ng-option >
    }
</ ng-select >

<!--Using items input-->
< ng-select [items] =" cars " 
           bindLabel =" name " 
           bindValue =" id " 
           [(ngModel)] =" selectedCar " >
</ ng-select >

Более подробные примеры см. на демонстрационной странице.

СистемаJS

Если вы используете SystemJS, вам также следует настроить конфигурацию так, чтобы она указывала на пакет UMD.

В файле конфигурации systemjs map должна указать загрузчику системы, где искать ng-select :

map: {
  '@ng-select/ng-select' : 'node_modules/@ng-select/ng-select/bundles/ng-select.umd.js' ,
}

API

Входы

Вход	Тип	По умолчанию	Необходимый	Описание
[добавитьтег]	`boolean \| ((term: string) => any \| Promise<any>)`	`false`	нет	Позволяет создавать собственные параметры.
добавитьТагтекст	`string`	`Add item`	нет	Установка пользовательского текста при использовании тегов
появление	`string`	`underline`	нет	Позволяет выбрать внешний вид раскрывающегося списка. Установите `outline` , чтобы добавить границу вместо подчеркивания (применяется только к теме «Материал»).
добавитьTo	`string`	нулевой	нет	Добавьте раскрывающийся список к телу или любому другому элементу с помощью селектора CSS. Для правильного позиционирования `body` должно иметь `position:relative`
буферасумма	`string`	нулевой	нет	Добавьте раскрывающийся список к телу или любому другому элементу с помощью селектора CSS. Для правильного позиционирования `body` должно иметь `position:relative`
связываниеValue	`string`	`-`	нет	Свойство объекта, которое будет использоваться для выбранной модели. По умолчанию привязывается ко всему объекту.
связывание метки	`string`	`label`	нет	Свойство объекта, используемое для метки. `label` по умолчанию
[закрытьOnSelect]	`boolean`	истинный	нет	Закрывать ли меню при выборе значения
очиститьAllText	`string`	`Clear all`	нет	Установите собственный текст для очистки всех заголовков значков
[очистить]	`boolean`	`true`	нет	Разрешить очистить выбранное значение. По умолчанию `true`
[clearOnBackspace]	`boolean`	`true`	нет	Очищайте выбранные значения одно за другим, нажимая клавишу Backspace. По умолчанию `true`
[сравнить с]	`(a: any, b: any) => boolean`	`(a, b) => a === b`	нет	Функция для сравнения значений параметров с выбранными значениями. Первый аргумент — это значение опции. Второе — значение из выборки (модели). Должно быть возвращено логическое значение.
раскрывающаяся позиция	`bottom` \| `top` \| `auto`	`auto`	нет	Установите раскрывающееся положение при открытии
[исправленный заполнитель]	`boolean`	`false`	нет	Сделать заполнитель видимым, даже если элемент выбран
[группаПо]	`string` \| `Function`	нулевой	нет	Разрешить группировать элементы по ключевому или функциональному выражению
[групповое значение]	`(groupKey: string, children: any[]) => Object`	-	нет	Функциональное выражение для предоставления значения группы
[выбираемая группа]	`boolean`	ЛОЖЬ	нет	Разрешить выбирать группу при использовании groupBy
[selectableGroupAsModel]	`boolean`	истинный	нет	Указывает, следует ли выбрать всех дочерних элементов или саму группу.
[предметы]	`Array<any>`	`[]`	да	Массив элементов
[загрузка]	`boolean`	`-`	нет	Вы можете установить состояние загрузки извне (например, асинхронная загрузка элементов).
loadingText	`string`	`Loading...`	нет	Установите собственный текст при загрузке элементов
меткаForId	`string`	`-`	нет	Идентификатор для связи элемента управления с меткой.
[markFirst]	`boolean`	`true`	нет	Отмечает первый элемент как выделенный при открытии/фильтрации.
[isOpen]	`boolean`	`-`	нет	Позволяет вручную управлять открытием и закрытием раскрывающегося списка. `true` - не закроется. `false` - не откроется.
Максселектедитемс	`number`	никто	нет	Когда Multiple = true, позволяет установить предельное количество вариантов выбора.
[скрытьВыбранное]	`boolean`	`false`	нет	Позволяет скрыть выбранные элементы.
[несколько]	`boolean`	`false`	нет	Позволяет выбрать несколько элементов.
нефаундтекст	`string`	`No items found`	нет	Установить собственный текст, когда фильтр возвращает пустой результат
заполнитель	`string`	`-`	нет	Текст заполнителя.
[доступно для поиска]	`boolean`	`true`	нет	Разрешить поиск значения. По умолчанию `true`
[только чтение]	`boolean`	`false`	нет	Установите ng-select только для чтения. Чаще всего используется с реактивными формами.
[поискFn]	`(term: string, item: any) => boolean`	`null`	нет	Разрешить фильтрацию по пользовательской функции поиска
[поиск во время сочинения]	`boolean`	`true`	нет	Следует ли фильтровать элементы при запуске композиции
[trackByFn]	`(item: any) => any`	`null`	нет	Предоставить пользовательскую функцию trackBy
[clearSearchOnAdd]	`boolean`	`true`	нет	Очищает ввод поиска при выборе элемента. По умолчанию `true` . По умолчанию `false` , когда closeOnSelect имеет `false`
[отменить выбор по клику]	`boolean`	`false`	нет	Отменяет выбор выбранного элемента при нажатии на него в раскрывающемся списке. По умолчанию `false` . По умолчанию `true` когда несколько `true`
[editableSearchTerm]	`boolean`	`false`	нет	Разрешить редактирование поискового запроса, если выбрана опция. По умолчанию `false` . Работает только в том случае, если Multiple имеет значение `false` .
[выбратьна вкладке]	`boolean`	`false`	нет	Выберите отмеченный элемент раскрывающегося списка с помощью вкладки. По умолчанию `false`
[открытьOnEnter]	`boolean`	`true`	нет	Откройте раскрывающийся список с помощью Enter. По умолчанию `true`
[печатать вперед]	`Subject`	`-`	нет	Пользовательское автозаполнение или расширенный фильтр.
[минтермдлина]	`number`	`0`	нет	Минимальная длина термина для начала поиска. Следует использовать с `typeahead`
типToSearchText	`string`	`Type to search`	нет	Установите собственный текст при использовании Typeahead
[виртуальная прокрутка]	`boolean`	ЛОЖЬ	нет	Включите виртуальную прокрутку для повышения производительности при рендеринге большого количества данных.
[входные атрибуты]	`{ [key: string]: string }`	`-`	нет	Передача пользовательских атрибутов базовому элементу `input`
[табИндекс]	`number`	`-`	нет	Установить tabindex на ng-select
[предотвратитьToggleOnRightClick]	`boolean`	`false`	нет	Запретить открытие ng-select при щелчке правой кнопкой мыши
[keyDownFn]	`($event: KeyboardEvent) => bool`	`true`	нет	Предоставьте пользовательскую функцию keyDown. Выполняется перед обработчиком по умолчанию. Верните false, чтобы подавить выполнение обработчиков нажатия клавиши по умолчанию.

Выходы

Выход	Описание
(добавлять)	Вызывается, когда элемент добавляется, пока `[multiple]="true"` . Выводит добавленный элемент
(размытие)	Срабатывает при выборе размытия
(изменять)	Уволен при смене модели. Выводит всю модель
(закрывать)	Срабатывает при закрытии раскрывающегося списка выбора
(прозрачный)	Запускается при нажатии на значок очистки
(фокус)	Срабатывает при выборе фокуса
(поиск)	Срабатывает при вводе поискового запроса. Выводит поисковый запрос с отфильтрованными элементами
(открыть)	Срабатывает при открытии раскрывающегося списка выбора
(удалять)	Вызывается, когда элемент удаляется, пока `[multiple]="true"`
(прокрутить)	Срабатывает при прокрутке. Предоставляет начальный и конечный индекс доступных в данный момент элементов. Может использоваться для загрузки большего количества элементов частями, прежде чем пользователь прокрутит список до конца.
(прокрутите до конца)	Срабатывает при прокрутке до конца элементов. Может использоваться для загрузки большего количества элементов частями.

Методы

Имя	Описание
открыть	Открывает раскрывающийся список выбора
закрывать	Закрывает раскрывающуюся панель выбора
сосредоточиться	Фокусирует выбранный элемент
размытие	Размывает выбранный элемент

Другой

Имя	Тип	Описание
[ngOptionHighlight]	директива	Выделяет поисковый запрос в опции. Принимает поисковый запрос. Следует использовать в элементе option. ЧИТАЙТЕ
Нгселектконфиг	конфигурация	Поставщик конфигурации для компонента NgSelect. Вы можете внедрить эту услугу и обеспечить конфигурацию всего приложения.
SELECTION_MODEL_FACTORY	услуга	Токен DI для реализации SelectionModel. Вы можете предоставить собственную реализацию, изменяющую поведение выбора.

Пользовательская логика выбора

Ng-select позволяет обеспечить реализацию пользовательского выбора с помощью SELECTION_MODEL_FACTORY . Чтобы переопределить логику по умолчанию, укажите свой фабричный метод в модуле angular.

 // app.module.ts
providers: [
    { provide : SELECTION_MODEL_FACTORY , useValue : < SelectionModelFactory > CustomSelectionFactory }
]

// selection-model.ts
export function CustomSelectionFactory ( ) {
    return new CustomSelectionModel ( ) ;
}

export class CustomSelectionModel implements SelectionModel {
    ...
}

Обнаружение изменений

Компонент Ng-select реализует обнаружение изменений OnPush , что означает, что грязная проверка проверяет неизменяемые типы данных. Это означает, что если вы выполняете мутации объектов, например:

 this . items . push ( { id : 1 , name : 'New item' } )

Компонент не обнаружит изменения. Вместо этого вам нужно сделать:

 this . items = [ ... this . items , { id : 1 , name : 'New item' } ] ;

Это заставит компонент обнаружить изменение и обновить. У некоторых могут возникнуть опасения, что это дорогостоящая операция, однако она гораздо более производительна, чем запуск ngDoCheck и постоянное сравнение массива.

Пользовательские стили

Если вас не устраивают стили по умолчанию, вы можете легко переопределить их, увеличив специфичность селектора или создав собственную тему. Это применимо, если вы не используете ViewEncapsulation или добавляете стили в глобальную таблицу стилей. Например

 < ng-select class =" custom " > </ ng-select >

. ng-select . custom {
    border : 0 px ;
    min-height : 0 px ;
    border-radius : 0 ;
}
. ng-select . custom . ng-select-container  {            
    min-height : 0 px ;
    border-radius : 0 ;
}

Если вы используете ViewEncapsulation , вы можете использовать специальный селектор ::ng-deep , который предотвратит область действия для вложенных селекторов, хотя это скорее обходной путь, и мы рекомендуем использовать решение, описанное выше.

. ng-select . custom :: ng-deep . ng-select-container  {            
    min-height : 0 px ;
    border-radius : 0 ;
}

ВНИМАНИЕ: имейте в виду, что ng-deep устарел и альтернативы ему пока нет. См. здесь.

Состояние проверки

По умолчанию, когда вы используете валидаторы реактивных форм или валидаторы форм, управляемых шаблонами, класс CSS ng-invalid будет применен к ng-select. Вы можете показать состояние ошибок, добавив собственный стиль CSS.

 ng-select . ng-invalid . ng-touched . ng-select-container {
    border-color : # dc3545 ;
    box-shadow : inset 0 1 px 1 px rgba ( 0 , 0 , 0 , 0.075 ) , 0 0 0 3 px # fde6e8 ;
}

Содействие

Взносы приветствуются. Вы можете начать с просмотра проблем с пометкой « Требуется помощь» или создания новой проблемы с предложением или отчетом об ошибке. Обратите внимание, что мы используем формат коммитов https://conventionalcommits.org/.

Разработка

Выполните шаги клонирования для запуска с помощью этих команд терминала.

Запустить демонстрационную страницу в режиме просмотра

 git clone https://github.com/ng-select/ng-select
cd ng-select
yarn
yarn run start

Тестирование

 yarn run test
or
yarn run test:watch

Выпускать

Чтобы выпустить в npm, просто запустите ./release.sh , конечно, если у вас есть разрешения;)

Вдохновение

Этот компонент вдохновлен выбором React и виртуальной прокруткой. Проверьте их потрясающую работу и компоненты :)

Расширять

Дополнительная информация

Версия v14.0.0
Тип Другой исходный код
Время обновления 2024-12-07
размер 492.54KB
От Github

Связанные приложения

ng select