ng select

Angular ng-select - 軽量のオールインワン UI 選択、複数選択、オートコンプリート

デモページを参照してください。

---

バージョン

角度のある	ng-select
>=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 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バンドルには正しいレイアウトと配置に必要な汎用スタイルのみが含まれています。コントロールの外観を完全に把握するには、アプリケーションにテーマの 1 つを含めます。 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に設定すると、下線の代わりに枠線が追加されます (マテリアル テーマにのみ適用されます)
追加する	string	ヌル	いいえ	CSS セレクターを使用して、ドロップダウンを本文またはその他の要素に追加します。正しい位置に配置するには、 body position:relative指定する必要があります。
バッファ量	string	ヌル	いいえ	CSS セレクターを使用して、ドロップダウンを本文またはその他の要素に追加します。正しい位置に配置するには、 body position:relative指定する必要があります。
バインド値	string	-	いいえ	選択したモデルに使用するオブジェクトのプロパティ。デフォルトではオブジェクト全体にバインドされます。
バインドラベル	string	label	いいえ	ラベルに使用するオブジェクトのプロパティ。デフォルトのlabel
[閉じる選択時]	boolean	真実	いいえ	値を選択したときにメニューを閉じるかどうか
すべてのテキストをクリア	string	Clear all	いいえ	すべてクリアアイコンタイトルのカスタムテキストを設定する
【クリア可能】	boolean	true	いいえ	選択した値をクリアできます。デフォルトはtrue
[クリアオンバックスペース]	boolean	true	いいえ	バックスペースをクリックすると、選択した値が 1 つずつクリアされます。デフォルトはtrue
[比較]	(a: any, b: any) => boolean	(a, b) => a === b	いいえ	オプションの値と選択された値を比較する関数。最初の引数はオプションの値です。 2 番目は選択 (モデル) からの値です。ブール値が返される必要があります。
ドロップダウン位置	bottom | top | auto	auto	いいえ	ドロップダウンの位置をオープンに設定します
[固定プレースホルダー]	boolean	false	いいえ	項目が選択されている場合でもプレースホルダーが表示されるように設定します
[グループ別]	string | Function	ヌル	いいえ	キーまたは関数式によって項目をグループ化できるようにする
[グループ値]	(groupKey: string, children: any[]) => Object	-	いいえ	グループ値を提供する関数式
[選択可能なグループ]	boolean	間違い	いいえ	groupBy を使用する場合にグループを選択できるようにする
[モデルとして選択可能なグループ]	boolean	真実	いいえ	すべての子を選択するかグループ自体を選択するかを示します
【アイテム】	Array<any>	[]	はい	項目配列
[読み込み中]	boolean	-	いいえ	外部からロード状態を設定できます (例: 非同期アイテムのロード)
読み込み中テキスト	string	Loading...	いいえ	アイテムをロードするときにカスタムテキストを設定する
ID のラベル	string	-	いいえ	コントロールをラベルに関連付ける ID。
[マークファースト]	boolean	true	いいえ	開く/フィルタリングするときに、最初のアイテムをフォーカスされているものとしてマークします。
[オープンです]	boolean	-	いいえ	ドロップダウンの開閉を手動で制御できます。 true - 閉じません。 false - 開きません。
maxSelectedItems	number	なし	いいえ	multiple = true の場合、選択の制限数を設定できます。
[選択項目を隠す]	boolean	false	いいえ	選択した項目を非表示にできます。
[複数]	boolean	false	いいえ	複数の項目を選択できます。
notFoundText	string	No items found	いいえ	フィルターが空の結果を返した場合にカスタム テキストを設定する
プレースホルダー	string	-	いいえ	プレースホルダーのテキスト。
【検索可能】	boolean	true	いいえ	値の検索を許可します。デフォルトはtrue
[読み取り専用]	boolean	false	いいえ	ng-select を読み取り専用として設定します。主にリアクティブフォームで使用されます。
[検索ファン]	(term: string, item: any) => boolean	null	いいえ	カスタム検索機能によるフィルタリングを許可する
[作曲しながら検索]	boolean	true	いいえ	合成の開始時に項目をフィルタリングするかどうか
[トラックによるFn]	(item: any) => any	null	いいえ	カスタム trackBy 関数を提供する
[クリア検索オン追加]	boolean	true	いいえ	項目が選択されている場合、検索入力をクリアします。デフォルトはtrue 。 closeOnSelectがfalseの場合のデフォルトはfalse
[クリック時選択解除]	boolean	false	いいえ	ドロップダウンで選択した項目をクリックすると、その項目の選択が解除されます。デフォルトはfalse 。 multipleがtrueの場合、デフォルトはtrue
[編集可能な検索用語]	boolean	false	いいえ	オプションが選択されている場合、検索クエリの編集を許可します。デフォルトはfalse 。 multiple がfalse場合にのみ機能します。
[selectOnTab]	boolean	false	いいえ	タブを使用してマークされたドロップダウン項目を選択します。デフォルトはfalse
[入力時にオープン]	boolean	true	いいえ	Enterを使用してドロップダウンを開きます。デフォルトはtrue
[先行入力]	Subject	-	いいえ	カスタムのオートコンプリートまたは高度なフィルター。
[minTermLength]	number	0	いいえ	検索を開始するための最小用語の長さ。 typeaheadと一緒に使用する必要があります
検索テキストを入力してください	string	Type to search	いいえ	先行入力を使用するときにカスタム テキストを設定する
[仮想スクロール]	boolean	間違い	いいえ	大量のデータをレンダリングする際のパフォーマンスを向上させるために仮想スクロールを有効にする
[入力属性]	{ [key: string]: string }	-	いいえ	カスタム属性を基礎となるinput要素に渡す
[タブインデックス]	number	-	いいえ	ng-select に tabindex を設定する
[右クリック時のトグルを防止]	boolean	false	いいえ	マウスの右クリックで ng-select が開かないようにする
[キーダウンFn]	($event: KeyboardEvent) => bool	true	いいえ	カスタム keyDown 関数を提供します。デフォルトのハンドラの前に実行されます。デフォルトのキーダウンハンドラーの実行を抑制するには false を返します。

出力

出力	説明
（追加）	[multiple]="true"のときに項目が追加されたときに発生します。出力追加項目
(ぼやけて)	ブラーを選択したときに発生します
（変化）	機種変更時に発動。モデル全体を出力します
（近い）	ドロップダウンを選択して閉じるときに発生します
（クリア）	クリアアイコンをクリックすると発生します
（集中）	フォーカスを選択すると発生します
（検索）	検索語の入力中に発生します。フィルタリングされた項目を含む検索語を出力します
（開ける）	選択したドロップダウンを開いたときに発生します
（取り除く）	[multiple]="true"のときにアイテムが削除されたときに発生します
（スクロール）	スクロールすると発生します。現在利用可能な項目の開始インデックスと終了インデックスを提供します。ユーザーがリストの一番下までスクロールする前に、さらに多くの項目をまとめてロードするために使用できます。
(スクロールトゥエンド)	項目の最後までスクロールすると発生します。より多くのアイテムをまとめてロードするために使用できます。

メソッド

名前	説明
開ける	選択ドロップダウンパネルを開きます
近い	選択ドロップダウン パネルを閉じます
集中	選択要素にフォーカスを当てます
ぼかし	選択した要素をぼかします

他の

名前	タイプ	説明
[ngオプションハイライト]	指令	オプション内の検索語を強調表示します。検索語を受け入れます。オプション要素で使用する必要があります。お読みください
NgSelectConfig	構成	NgSelect コンポーネントの構成プロバイダー。このサービスを挿入して、アプリケーション全体の構成を提供できます。
SELECTION_MODEL_FACTORY	サービス	SelectionModel 実装用の DI トークン。選択動作を変更するカスタム実装を提供できます。

カスタム選択ロジック

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 選択と仮想スクロールからインスピレーションを得ています。彼らの素晴らしい作品とコンポーネントをチェックしてください:)