@abolutpersonal/ng-select 中文文档教程

Question

Angular ng-select - Lightweight all in one UI Select, Multiselect and Autocomplete

请参阅 演示 或尝试 Stackblitz

---

Versions

Angular	ng-select
v6.x	v2.x
v5.x	v1.x

---

Table of contents

• Features
• Getting started
• API
• Change detection
• Custom styles
  • Validation state
• Contributing
• Development
• Inspiration

Features

• [x] Custom binding to property or object
• [x] Custom option, label, header and footer templates
• [x] Virtual Scroll support with large data sets (>5000 items).
• [x] Infinite scroll
• [x] Keyboard navigation
• [x] Multiselect
• [x] Flexible autocomplete with client/server filtering
• [x] Custom search
• [x] Custom tags
• [x] Append to
• [x] Group items
• [x] Output events
• [x] Accessibility
• [x] Good base functionality test coverage
• [x] Themes

Warning

库正在积极开发中，可能会对 1.0.0 之后的后续主要版本进行 API 中断更改。

Getting started

Step 1: Install ng-select:

NPM

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

YARN

yarn add @ng-select/ng-select

Step 2: Import the NgSelectModule and angular FormsModule module:

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

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

Step 3: Include a theme:

为了允许自定义和主题化，ng-select 包仅包含正确布局和定位所必需的通用样式。 要全面了解该控件，请在您的应用程序中包含其中一个主题。 如果您使用的是 Angular CLI，则可以将其添加到 styles.scss 或将其包含在 .angular-cli.json（Angular v5 及以下版本）或 < code>angular.json（Angular v6 起）。

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

Step 4 (Optional): Configuration

您还可以通过注入 NgSelectConfig 服务来设置全局配置和本地化消息， 通常在您的根组件中，并自定义其属性的值以提供默认值。

  constructor(private config: NgSelectConfig) {
      this.config.notFoundText = 'Custom not found';
  }

SystemJS

如果您使用的是 SystemJS，您还应该调整您的配置以指向 UMD 包。

在你的 systemjs 配置文件中，map 需要告诉系统加载器在哪里寻找 ng-select：

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

API

Inputs

Input	Type	Default	Required	Description
[addTag]	boolean | ((term: string) => any | Promise<any>)	false	no	Allows to create custom options.
addTagText	string	Add item	no	Set custom text when using tagging
appendTo	string	null	no	Append dropdown to body or any other element using css selector. For correct positioning body should have position:relative
bindValue	string	-	no	Object property to use for selected model. By default binds to whole object.
bindLabel	string	label	no	Object property to use for label. Default label
[closeOnSelect]	boolean	true	no	Whether to close the menu when a value is selected
clearAllText	string	Clear all	no	Set custom text for clear all icon title
[clearable]	boolean	true	no	Allow to clear selected value. Default true
[clearOnBackspace]	boolean	true	no	Clear selected values one by one when clicking backspace. Default true
[compareWith]	(a: any, b: any) => boolean	(a, b) => a === b	no	A function to compare the option values with the selected values. The first argument is a value from an option. The second is a value from the selection(model). A boolean should be returned.
dropdownPosition	bottom | top | auto	auto	no	Set the dropdown position on open
[excludeGroupsFromDefaultSelection]	boolean	false	no	Exclude group from default selection when selectableGroup is true. Default false.
[groupBy]	string | Function	null	no	Allow to group items by key or function expression
[groupValue]	(groupKey: string, cildren: any[]) => Object	-	no	Function expression to provide group value
[selectableGroup]	boolean	false	no	Allow to select group when groupBy is used
[selectableGroupAsModel]	boolean	true	no	Indicates whether to select all children or group itself
[items]	Array<any>	[]	yes	Items array
[loading]	boolean	-	no	You can set the loading state from the outside (e.g. async items loading)
loadingText	string	Loading...	no	Set custom text when for loading items
labelForId	string	-	no	Id to associate control with label.
[markFirst]	boolean	true	no	Marks first item as focused when opening/filtering.
[isOpen]	boolean	-	no	Allows manual control of dropdown opening and closing. True - won't close. False - won't open.
maxSelectedItems	number	none	no	When multiple = true, allows to set a limit number of selection.
[hideSelected]	boolean	false	no	Allows to hide selected items.
[multiple]	boolean	false	no	Allows to select multiple items.
notFoundText	string	No items found	no	Set custom text when filter returns empty result
placeholder	string	-	no	Placeholder text.
[searchable]	boolean	true	no	Allow to search for value. Default true
[searchFn]	(term: string, item: any) => boolean	null	no	Allow to filter by custom search function
[clearSearchOnAdd]	boolean	true	no	Clears search input when item is selected. Default true. Default false when closeOnSelect is false
[selectOnTab]	boolean	false	no	Select marked dropdown item using tab. Default false
[openOnEnter]	boolean	true	no	Open dropdown using enter. Default true
[typeahead]	Subject	-	no	Custom autocomplete or advanced filter.
typeToSearchText	string	Type to search	no	Set custom text when using Typeahead
[virtualScroll]	boolean	false	no	Enable virtual scroll for better performance when rendering a lot of data
autoCorrect	string	off	no	Allows control of the autocorrect attribute.
autoCapitalize	string	off	no	Allows control of the autocapitalize attribute.

Outputs

Output	Description
(add)	Fired when item is added while [multiple]="true". Outputs added item
(blur)	Fired on select blur
(change)	Fired on model change. Outputs whole model
(close)	Fired on select dropdown close
(clear)	Fired on clear icon click
(focus)	Fired on select focus
(search)	Fired while typing search term. Outputs search term with filtered items
(open)	Fired on select dropdown open
(remove)	Fired when item is removed while [multiple]="true"
(scroll)	Fired when scrolled. Provides the start and end index of the currently available items. Can be used for loading more items in chunks before the user has scrolled all the way to the bottom of the list.
(scrollToEnd)	Fired when scrolled to the end of items. Can be used for loading more items in chunks.

Methods

Name	Description
open	Opens the select dropdown panel
close	Closes the select dropdown panel
focus	Focuses the select element

Other

Name	Type	Description
[ngOptionHighlight]	directive	Highlights search term in option. Accepts search term. Should be used on option element.
NgSelectConfig	configuration	Configuration provider for the NgSelect component. You can inject this service and provide application wide configuration.
SELECTIONMODELFACTORY	service	DI token for SelectionModel implementation. You can provide custom implementation changing selection behaviour.

Change Detection

Ng-select 组件实现 OnPush 变化检测这意味着脏检查检查不可变 数据类型。 这意味着如果您执行对象突变，例如：

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

组件将不会检测到更改。 相反，您需要这样做：

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

这将使组件检测到更改和更新。 有些人可能会担心 这是一个昂贵的操作，但是，它比运行 ngDoCheck 和 不断区分数组。

Custom styles

如果您对默认样式不满意，您可以通过增加选择器特异性或创建您自己的主题轻松覆盖它们。 如果您不使用 ViewEncapsulation 或向全局样式表添加样式，这适用。 例如

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

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

，如果您正在使用 ViewEncapsulation，您应该使用特殊的 ::ng-deep 选择器，这将阻止嵌套选择器的作用域。

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

警告：请记住，ng-deep 已被弃用，目前还没有替代品。 请参阅此处。

Validation state

默认情况下，当您使用反应式表单验证器或模板驱动的表单验证器时，CSS 类 ng-invalid 将应用于 ng-select。 您可以通过添加自定义 css 样式来显示错误状态

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

Contributing

欢迎贡献。 您可以先查看 带有标签需要帮助 的问题 或创建新的带有提案或错误报告的问题。 请注意，我们使用的是 https://conventionalcommits.org/ 提交格式。

Development

使用这些终端命令执行clone-to-launch 步骤。

Run demo page in watch mode

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

Testing

yarn run test
or
yarn run test:watch

Release

要发布到 npm 只需运行 ./release.sh，当然如果你有权限的话 ;)

Inspiration

这个组件的灵感来自 React 选择 和虚拟滚动。 检查他们惊人的工作和组件:)