ng select

Angular ng-select - 경량 올인원 UI 선택, 다중 선택 및 자동 완성

데모 페이지를 참조하세요.

---

버전

모난	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
• 변화 감지
• 맞춤 스타일
  • 유효성 검사 상태
• 기여
• 개발
• 영감

특징

• 속성 또는 개체에 대한 사용자 지정 바인딩
• 사용자 정의 옵션, 라벨, 머리글 및 바닥글 템플릿
• 대규모 데이터 세트(>5000개 항목)에 대한 가상 스크롤 지원.
• 무한 스크롤
• 키보드 탐색
• 다중 선택
• 클라이언트/서버 필터링을 통한 유연한 자동 완성
• 맞춤 검색
• 맞춤 태그
• 다음에 추가
• 그룹 항목
• 출력 이벤트
• 접근성
• 좋은 기본 기능 테스트 범위
• 테마

경고

라이브러리는 활발하게 개발 중이며 1.0.0 이후의 후속 주요 버전에 대한 API 주요 변경 사항이 있을 수 있습니다.

시작하기

1단계: ng-select 설치:

NPM

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 및 각도 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	아니요	사용자 정의 옵션을 생성할 수 있습니다.
addTagText	string	Add item	아니요	태그 사용 시 사용자 정의 텍스트 설정
모습	string	underline	아니요	드롭다운 모양을 선택할 수 있습니다. 밑줄 대신 테두리를 추가하려면 outline 으로 설정합니다. (Material 테마에만 적용)
추가	string	null	아니요	CSS 선택기를 사용하여 본문이나 다른 요소에 드롭다운을 추가합니다. 올바른 위치 지정을 위해 body position:relative 가 있어야 합니다.
버퍼량	string	null	아니요	CSS 선택기를 사용하여 본문이나 다른 요소에 드롭다운을 추가합니다. 올바른 위치 지정을 위해 body position:relative 가 있어야 합니다.
바인드값	string	-	아니요	선택한 모델에 사용할 개체 속성입니다. 기본적으로 전체 개체에 바인딩됩니다.
바인드 라벨	string	label	아니요	레이블에 사용할 개체 속성입니다. 기본 label
[닫기선택]	boolean	진실	아니요	값이 선택될 때 메뉴를 닫을지 여부
모든 텍스트 지우기	string	Clear all	아니요	모든 아이콘 제목 지우기를 위한 사용자 정의 텍스트 설정
[삭제 가능]	boolean	true	아니요	선택한 값을 지울 수 있습니다. 기본값은 true
[clearOnBackspace]	boolean	true	아니요	백스페이스를 클릭하면 선택한 값이 하나씩 지워집니다. 기본값은 true
[비교]	(a: any, b: any) => boolean	(a, b) => a === b	아니요	옵션값과 선택한 값을 비교하는 기능입니다. 첫 번째 인수는 옵션의 값입니다. 두 번째는 선택(모델)의 값입니다. 부울이 반환되어야 합니다.
드롭다운위치	bottom | top | auto	auto	아니요	열 때 드롭다운 위치 설정
[고정자리 표시자]	boolean	false	아니요	항목을 선택한 경우에도 자리 표시자가 표시되도록 설정
[그룹별]	string | Function	null	아니요	키 또는 함수 표현식을 기준으로 항목을 그룹화할 수 있습니다.
[그룹값]	(groupKey: string, children: any[]) => Object	-	아니요	그룹 값을 제공하는 함수 표현식
[선택 가능 그룹]	boolean	거짓	아니요	groupBy 사용 시 그룹 선택 허용
[selectableGroupAsModel]	boolean	진실	아니요	모든 하위 항목을 선택할지 그룹 자체를 선택할지 여부를 나타냅니다.
[아이템]	Array<any>	[]	예	항목 배열
[로드 중]	boolean	-	아니요	외부에서 로딩 상태를 설정할 수 있습니다(예: 비동기 항목 로딩).
로딩텍스트	string	Loading...	아니요	항목을 로드할 때 사용자 정의 텍스트 설정
labelForId	string	-	아니요	컨트롤을 레이블과 연결하는 ID입니다.
[마크퍼스트]	boolean	true	아니요	열기/필터링 시 첫 번째 항목에 초점이 맞춰진 것으로 표시합니다.
[열린 상태]	boolean	-	아니요	드롭다운 열기 및 닫기를 수동으로 제어할 수 있습니다. true - 닫히지 않습니다. false - 열리지 않습니다.
최대선택항목	number	없음	아니요	multiple = true인 경우 선택 제한 수를 설정할 수 있습니다.
[선택 숨기기]	boolean	false	아니요	선택한 항목을 숨길 수 있습니다.
[다수의]	boolean	false	아니요	여러 항목을 선택할 수 있습니다.
notFoundText	string	No items found	아니요	필터가 빈 결과를 반환할 때 맞춤 텍스트 설정
자리 표시자	string	-	아니요	자리표시자 텍스트.
[검색 가능]	boolean	true	아니요	가치 검색을 허용합니다. 기본값은 true
[읽기 전용]	boolean	false	아니요	ng-select를 읽기 전용으로 설정하십시오. 주로 반응형과 함께 사용됩니다.
[검색Fn]	(term: string, item: any) => boolean	null	아니요	맞춤 검색 기능으로 필터링 허용
[작곡중검색]	boolean	true	아니요	작성이 시작되는 동안 항목을 필터링해야 하는지 여부
[트랙바이Fn]	(item: any) => any	null	아니요	맞춤형 trackBy 기능 제공
[clearSearchOnAdd]	boolean	true	아니요	항목 선택 시 검색 입력을 지웁니다. 기본값은 true . closeOnSelect 가 false 인 경우 기본값은 false 입니다.
[선택 해제OnClick]	boolean	false	아니요	드롭다운에서 클릭하면 선택한 항목의 선택이 취소됩니다. 기본값은 false . 다중 이 true 인 경우 기본값은 true
[편집 가능한 검색어]	boolean	false	아니요	옵션을 선택한 경우 검색어 편집을 허용합니다. 기본값은 false . multiple 이 false 인 경우에만 작동합니다.
[탭온 선택]	boolean	false	아니요	탭을 사용하여 표시된 드롭다운 항목을 선택합니다. 기본값은 false
[openOnEnter]	boolean	true	아니요	Enter를 사용하여 드롭다운을 엽니다. 기본값은 true
[입력기]	Subject	-	아니요	사용자 정의 자동 완성 또는 고급 필터.
[최소기간길이]	number	0	아니요	검색을 시작하기 위한 최소 용어 길이입니다. typeahead 와 함께 사용해야 함
검색텍스트로 입력	string	Type to search	아니요	Typeahead 사용 시 사용자 정의 텍스트 설정
[가상스크롤]	boolean	거짓	아니요	많은 양의 데이터를 렌더링할 때 성능 향상을 위해 가상 스크롤을 활성화합니다.
[입력 속성]	{ [key: string]: string }	-	아니요	사용자 정의 속성을 기본 input 요소에 전달
[탭인덱스]	number	-	아니요	ng-select에서 tabindex 설정
[ToggleOnRightClick 방지]	boolean	false	아니요	마우스 오른쪽 버튼 클릭 시 ng-select 열기 방지
[keyDownFn]	($event: KeyboardEvent) => bool	true	아니요	사용자 정의 keyDown 기능을 제공합니다. 기본 핸들러보다 먼저 실행됩니다. 기본 키 다운 핸들러의 실행을 억제하려면 false를 반환합니다.

출력

산출	설명
(추가하다)	[multiple]="true" 인 동안 항목이 추가되면 시작됩니다. 추가된 항목을 출력합니다.
(흐림)	선택 흐림 시 실행됨
(변화)	모델 변경으로 인해 실행되었습니다. 전체 모델 출력
(닫다)	선택한 드롭다운이 닫힐 때 실행됩니다.
(분명한)	지우기 아이콘 클릭 시 실행됨
(집중하다)	선택 포커스에서 실행됨
(찾다)	검색어를 입력하는 동안 실행되었습니다. 필터링된 항목으로 검색어를 출력합니다.
(열려 있는)	선택 드롭다운이 열리면 실행됩니다.
(제거하다)	[multiple]="true" 인 동안 항목이 제거되면 시작됩니다.
(스크롤)	스크롤할 때 발생합니다. 현재 사용 가능한 항목의 시작 및 끝 인덱스를 제공합니다. 사용자가 목록의 맨 아래까지 스크롤하기 전에 더 많은 항목을 청크로 로드하는 데 사용할 수 있습니다.
(끝까지 스크롤)	항목 끝까지 스크롤하면 시작됩니다. 더 많은 항목을 청크로 로드하는 데 사용할 수 있습니다.

행동 양식

이름	설명
열려 있는	선택 드롭다운 패널을 엽니다.
닫다	선택 드롭다운 패널을 닫습니다.
집중하다	선택 요소에 초점을 맞춥니다.
흐림	선택 요소를 흐리게 합니다.

다른

이름	유형	설명
[ngOptionHighlight]	지령	옵션에서 검색어를 강조 표시합니다. 검색어를 허용합니다. 옵션 요소에 사용해야 합니다. 읽어보기
NgSelectConfig	구성	NgSelect 구성 요소에 대한 구성 공급자입니다. 이 서비스를 주입하고 애플리케이션 전체 구성을 제공할 수 있습니다.
SELECTION_MODEL_FACTORY	서비스	SelectionModel 구현을 위한 DI 토큰입니다. 선택 동작을 변경하는 사용자 정의 구현을 제공할 수 있습니다.

맞춤 선택 논리

Ng-select를 사용하면 SELECTION_MODEL_FACTORY 를 사용하여 사용자 정의 선택 구현을 제공할 수 있습니다. 기본 논리를 재정의하려면 각도 모듈에 팩토리 메서드를 제공하세요.

 // 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 선택 및 가상 스크롤에서 영감을 받았습니다. 그들의 놀라운 작품과 구성 요소를 확인해보세요 :)