ng select
v14.0.0
Consulte a página de demonstração.
| Angular | ng-selecionar |
|---|---|
| >=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 oferece suporte a todos os navegadores suportados pelo Angular. Para a lista atual, consulte https://angular.io/guide/browser-support#browser-support. Isso inclui as seguintes versões específicas:
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
A biblioteca está em desenvolvimento ativo e pode ter alterações significativas na API para versões principais subsequentes após 1.0.0.
ng-select : npm install --save @ng-select/ng-selectyarn add @ng-select/ng-select 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 { } import { NgSelectModule } from '@ng-select/ng-select' ;
import { FormsModule } from '@angular/forms' ;
@ NgModule ( {
declarations : [ AppComponent ] ,
imports : [ NgSelectModule , FormsModule ] ,
bootstrap : [ AppComponent ]
} )
export class AppModule { } Para permitir personalização e temas, o pacote ng-select inclui apenas estilos genéricos que são necessários para layout e posicionamento corretos. Para obter uma visão completa do controle, inclua um dos temas em seu aplicativo. Se estiver usando o Angular CLI, você pode adicionar isso ao seu styles.scss ou incluí-lo em .angular-cli.json (Angular v5 e inferior) ou angular.json (Angular v6 em diante).
@import " ~@ng-select/ng-select/themes/default.theme.css " ;
// ... or
@import " ~@ng-select/ng-select/themes/material.theme.css " ;
Você também pode definir mensagens globais de configuração e localização injetando o serviço NgSelectConfig, normalmente em seu componente raiz, e personalizar os valores de suas propriedades para fornecer valores padrão.
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' ;
}Defina opções em seu componente de consumo:
@ Component ( { ... } )
export class ExampleComponent {
selectedCar : number ;
cars = [
{ id : 1 , name : 'Volvo' } ,
{ id : 2 , name : 'Saab' } ,
{ id : 3 , name : 'Opel' } ,
{ id : 4 , name : 'Audi' } ,
] ;
} No modelo, use o componente ng-select com suas opções
<!--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 >Para exemplos mais detalhados, consulte a página de demonstração
Se estiver usando SystemJS, você também deverá ajustar sua configuração para apontar para o pacote UMD.
No arquivo de configuração do systemjs, map precisa informar ao carregador do sistema onde procurar ng-select :
map: {
'@ng-select/ng-select' : 'node_modules/@ng-select/ng-select/bundles/ng-select.umd.js' ,
} | Entrada | Tipo | Padrão | Obrigatório | Descrição |
|---|---|---|---|---|
| [adicionarTag] | boolean | ((term: string) => any | Promise<any>) | false | não | Permite criar opções personalizadas. |
| adicionarTagText | string | Add item | não | Definir texto personalizado ao usar marcação |
| aparência | string | underline | não | Permite selecionar a aparência do menu suspenso. Defina como outline para adicionar borda em vez de sublinhado (aplica-se apenas ao tema Material) |
| anexar a | string | nulo | não | Anexe o menu suspenso ao corpo ou qualquer outro elemento usando o seletor css. Para o posicionamento correto body deve ter position:relative |
| bufferAmount | string | nulo | não | Anexe o menu suspenso ao corpo ou qualquer outro elemento usando o seletor css. Para o posicionamento correto body deve ter position:relative |
| vincularValor | string | - | não | Propriedade do objeto a ser usada para o modelo selecionado. Por padrão, vincula-se ao objeto inteiro. |
| bindLabel | string | label | não | Propriedade do objeto a ser usada para rótulo. label padrão |
| [closeOnSelect] | boolean | verdadeiro | não | Se deve fechar o menu quando um valor é selecionado |
| limparTodoTexto | string | Clear all | não | Defina o texto personalizado para limpar todos os títulos dos ícones |
| [limpável] | boolean | true | não | Permitir limpar o valor selecionado. Padrão true |
| [clearOnBackspace] | boolean | true | não | Limpe os valores selecionados um por um ao clicar em backspace. Padrão true |
| [comparar com] | (a: any, b: any) => boolean | (a, b) => a === b | não | Uma função para comparar os valores das opções com os valores selecionados. O primeiro argumento é um valor de uma opção. O segundo é um valor da seleção (modelo). Um booleano deve ser retornado. |
| posição suspensa | bottom | top | auto | auto | não | Defina a posição suspensa como aberta |
| [espaço reservado fixo] | boolean | false | não | Definir espaço reservado visível mesmo quando um item é selecionado |
| [grupoPor] | string | Function | nulo | não | Permitir agrupar itens por chave ou expressão de função |
| [valor do grupo] | (groupKey: string, children: any[]) => Object | - | não | Expressão de função para fornecer valor de grupo |
| [grupo selecionável] | boolean | falso | não | Permitir selecionar grupo quando groupBy for usado |
| [selecionávelGroupAsModel] | boolean | verdadeiro | não | Indica se todos os filhos devem ser selecionados ou o próprio grupo |
| [Unid] | Array<any> | [] | sim | Matriz de itens |
| [carregando] | boolean | - | não | Você pode definir o estado de carregamento externamente (por exemplo, carregamento assíncrono de itens) |
| carregandoTexto | string | Loading... | não | Defina texto personalizado ao carregar itens |
| rótuloForId | string | - | não | Id para associar o controle ao rótulo. |
| [marcar primeiro] | boolean | true | não | Marca o primeiro item como focado ao abrir/filtrar. |
| [está aberto] | boolean | - | não | Permite o controle manual da abertura e fechamento do dropdown. true - não fecha. false - não abre. |
| maxSelectedItems | number | nenhum | não | Quando multiple = true, permite definir um número limite de seleção. |
| [ocultar selecionado] | boolean | false | não | Permite ocultar itens selecionados. |
| [múltiplo] | boolean | false | não | Permite selecionar vários itens. |
| notFoundText | string | No items found | não | Definir texto personalizado quando o filtro retornar um resultado vazio |
| espaço reservado | string | - | não | Texto de espaço reservado. |
| [pesquisável] | boolean | true | não | Permitir pesquisar valor. Padrão true |
| [somente leitura] | boolean | false | não | Defina ng-select como somente leitura. Usado principalmente com formas reativas. |
| [pesquisaFn] | (term: string, item: any) => boolean | null | não | Permitir filtrar por função de pesquisa personalizada |
| [searchWhileComposing] | boolean | true | não | Se os itens devem ser filtrados durante o início da composição |
| [trackByFn] | (item: any) => any | null | não | Fornece função trackBy personalizada |
| [clearSearchOnAdd] | boolean | true | não | Limpa a entrada de pesquisa quando o item é selecionado. Padrão true . Padrão false quando closeOnSelect é false |
| [desmarcarOnClick] | boolean | false | não | Desmarca um item selecionado quando ele é clicado no menu suspenso. Padrão false . Padrão true quando múltiplo é true |
| [editávelSearchTerm] | boolean | false | não | Permitir editar a consulta de pesquisa se a opção for selecionada. Padrão false . Funciona apenas se multiple for false . |
| [selecionarNaTab] | boolean | false | não | Selecione o item suspenso marcado usando a guia. Padrão false |
| [openOnEnter] | boolean | true | não | Abra o menu suspenso usando Enter. Padrão true |
| [digitar antecipadamente] | Subject | - | não | Preenchimento automático personalizado ou filtro avançado. |
| [minTermLength] | number | 0 | não | Duração mínima do prazo para iniciar uma pesquisa. Deve ser usado com typeahead |
| typeToSearchText | string | Type to search | não | Defina texto personalizado ao usar Typeahead |
| [rolagem virtual] | boolean | falso | não | Ative a rolagem virtual para melhor desempenho ao renderizar muitos dados |
| [inputAttrs] | { [key: string]: string } | - | não | Passe atributos personalizados para o elemento input subjacente |
| [tabIndex] | number | - | não | Definir tabindex no ng-select |
| [prevenirToggleOnRightClick] | boolean | false | não | Impedir a abertura do ng-select ao clicar com o botão direito do mouse |
| [keyDownFn] | ($event: KeyboardEvent) => bool | true | não | Fornece função keyDown personalizada. Executado antes do manipulador padrão. Retorne false para suprimir a execução de manipuladores de teclas padrão |
| Saída | Descrição |
|---|---|
| (adicionar) | Disparado quando o item é adicionado while [multiple]="true" . Produz item adicionado |
| (borrão) | Disparado no desfoque selecionado |
| (mudar) | Demitido na mudança de modelo. Produz o modelo inteiro |
| (fechar) | Disparado ao selecionar o fechamento do menu suspenso |
| (claro) | Disparado ao clicar no ícone claro |
| (foco) | Disparado em foco selecionado |
| (procurar) | Disparado ao digitar o termo de pesquisa. Produz termo de pesquisa com itens filtrados |
| (abrir) | Disparado no menu suspenso de seleção aberto |
| (remover) | Disparado quando o item é removido enquanto [multiple]="true" |
| (rolar) | Disparado quando rolado. Fornece o índice inicial e final dos itens atualmente disponíveis. Pode ser usado para carregar mais itens em partes antes que o usuário role até o final da lista. |
| (rolar para o fim) | Disparado quando rolado até o final dos itens. Pode ser usado para carregar mais itens em pedaços. |
| Nome | Descrição |
|---|---|
| abrir | Abre o painel suspenso de seleção |
| fechar | Fecha o painel suspenso de seleção |
| foco | Foca o elemento selecionado |
| borrão | Desfoca o elemento selecionado |
| Nome | Tipo | Descrição |
|---|---|---|
| [ngOptionHighlight] | diretiva | Destaca o termo de pesquisa na opção. Aceita termo de pesquisa. Deve ser usado no elemento de opção. LEIA-ME |
| NgSelectConfig | configuração | Provedor de configuração para o componente NgSelect. Você pode injetar este serviço e fornecer configuração para todo o aplicativo. |
| SELECTION_MODEL_FACTORY | serviço | Token DI para implementação do SelectionModel. Você pode fornecer implementação personalizada alterando o comportamento de seleção. |
Ng-select permite fornecer implementação de seleção personalizada usando SELECTION_MODEL_FACTORY . Para substituir a lógica padrão, forneça seu método de fábrica em seu módulo 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 {
...
} O componente Ng-select implementa a detecção de alterações OnPush , o que significa que a verificação suja verifica tipos de dados imutáveis. Isso significa que se você fizer mutações de objetos como:
this . items . push ( { id : 1 , name : 'New item' } )O componente não detectará uma alteração. Em vez disso, você precisa fazer:
this . items = [ ... this . items , { id : 1 , name : 'New item' } ] ; Isso fará com que o componente detecte a alteração e atualize. Alguns podem temer que esta seja uma operação cara, no entanto, tem muito melhor desempenho do que executar ngDoCheck e comparar constantemente o array.
Se você não estiver satisfeito com os estilos padrão, poderá substituí-los facilmente com maior especificidade do seletor ou criando seu próprio tema. Isso se aplica se você não estiver usando nenhum ViewEncapsulation ou adicionando estilos à folha de estilo global. Por exemplo
< 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 ;
} Se você estiver usando ViewEncapsulation , poderá usar o seletor ::ng-deep especial que impedirá a definição do escopo de seletores aninhados, embora isso seja mais uma solução alternativa e recomendamos o uso da solução descrita acima.
. ng-select . custom :: ng-deep . ng-select-container {
min-height : 0 px ;
border-radius : 0 ;
}AVISO: Tenha em mente que o ng-deep está obsoleto e ainda não há alternativa para ele. Veja aqui.
Por padrão, quando você usa validadores de formulários reativos ou validadores de formulários orientados por modelo, a classe css ng-invalid será aplicada no ng-select. Você pode mostrar o estado dos erros adicionando um estilo CSS personalizado
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 ;
}Contribuições são bem-vindas. Você pode começar examinando os problemas com o rótulo Ajuda desejada ou criando um novo problema com proposta ou relatório de bug. Observe que estamos usando o formato https://conventionalcommits.org/ commits.
Execute as etapas de clonagem para inicialização com estes comandos de terminal.
git clone https://github.com/ng-select/ng-select
cd ng-select
yarn
yarn run start
yarn run test
or
yarn run test:watch
Para liberar para npm basta executar ./release.sh , claro se você tiver permissões;)
Este componente é inspirado no React select e no Virtual scroll. Confira o incrível trabalho e componentes deles :)
