ng select下载 - ng select源代码下载

ng select

其他源码

v14.0.0

下载

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

特征

警告

库正在积极开发中，并且可能会对 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包仅包含正确布局和定位所需的通用样式。要获得控件的完整外观，请在应用程序中包含主题之一。如果您使用 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' ,
}

应用程序编程接口

输入

输入	类型	默认	必需的	描述
[添加标签]	`boolean \| ((term: string) => any \| Promise<any>)`	`false`	不	允许创建自定义选项。
添加标签文本	`string`	`Add item`	不	使用标记时设置自定义文本
外貌	`string`	`underline`	不	允许选择下拉外观。设置为`outline`以添加边框而不是下划线（仅适用于 Material 主题）
附加到	`string`	无效的	不	使用 css 选择器将下拉列表附加到正文或任何其他元素。为了正确定位`body`应该有`position:relative`
缓冲量	`string`	无效的	不	使用 css 选择器将下拉列表附加到正文或任何其他元素。为了正确定位`body`应该有`position:relative`
绑定值	`string`	`-`	不	用于选定模型的对象属性。默认情况下绑定到整个对象。
绑定标签	`string`	`label`	不	用于标签的对象属性。默认`label`
[选择时关闭]	`boolean`	真的	不	选择值时是否关闭菜单
清除所有文本	`string`	`Clear all`	不	设置自定义文本以清除所有图标标题
[可清除]	`boolean`	`true`	不	允许清除所选值。默认`true`
[清除退格键]	`boolean`	`true`	不	单击退格键时将一一清除所选值。默认`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时允许选择组
[可选择的组作为模型]	`boolean`	真的	不	指示是否选择所有子项或组本身
[项目]	`Array<any>`	`[]`	是的	项目数组
[加载中]	`boolean`	`-`	不	您可以从外部设置加载状态（例如异步项目加载）
加载文本	`string`	`Loading...`	不	加载项目时设置自定义文本
标签ForId	`string`	`-`	不	将控件与标签关联的 ID。
[标记第一]	`boolean`	`true`	不	打开/过滤时将第一个项目标记为焦点。
[正在打开]	`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`	不	组合开始时是否应过滤项目
[按 Fn 轨迹]	`(item: any) => any`	`null`	不	提供自定义trackBy功能
[添加时清除搜索]	`boolean`	`true`	不	选择项目后清除搜索输入。默认`true` 。 closeOnSelect为`false`时默认为`false`
[单击时取消选择]	`boolean`	`false`	不	在下拉列表中单击所选项目时取消选择该项目。默认`false` 。当multiple为`true`时默认`true`
[可编辑搜索术语]	`boolean`	`false`	不	如果选择了选项，则允许编辑搜索查询。默认`false` 。仅当 multiple 为`false`时才有效。
[选择选项卡]	`boolean`	`false`	不	使用选项卡选择标记的下拉项目。默认`false`
[输入时打开]	`boolean`	`true`	不	使用 Enter 键打开下拉菜单。默认`true`
[提前输入]	`Subject`	`-`	不	自定义自动完成或高级过滤器。
[最小期限长度]	`number`	`0`	不	开始搜索的最短术语长度。应该与`typeahead`一起使用
输入搜索文本	`string`	`Type to search`	不	使用 Typeahead 时设置自定义文本
[虚拟滚动]	`boolean`	错误的	不	渲染大量数据时启用虚拟滚动以获得更好的性能
[输入属性]	`{ [key: string]: string }`	`-`	不	将自定义属性传递给底层`input`元素
[标签索引]	`number`	`-`	不	在 ng-select 上设置 tabindex
[防止右键单击切换]	`boolean`	`false`	不	防止右键单击时打开 ng-select
[按键向下Fn]	`($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 select 和 Virtual Scroll。检查他们令人惊叹的工作和组件:)

展开

附加信息

版本 v14.0.0
类型其他源码
更新时间 2024-12-07
大小 492.54KB
来自于 Github

ng select