Select
选择器

下拉选择器。

使用

源码

components/select

文档

何时使用#

弹出一个下拉菜单给用户选择操作，用于代替原生的选择器，或者需要一个更优雅的多选器时。
当选项少时（少于 5 项），建议直接将选项平铺，使用 Radio 是更好的选择。
如果你在寻找一个可输可选的输入框，那你可能需要 AutoComplete。

代码演示#

Lucy

基本使用

基本使用。

      加载中

a10

c12

多选

多选，从已有条目中选择，例子中通过 nzMaxTagCount 限制最多显示3个选项。

      加载中

Tag Mode

标签

tags select，随意输入的内容（scroll the menu）

      加载中

Zhejiang

Hangzhou

联动

省市联动是典型的例子。

推荐使用 Cascader 组件。

      加载中

Jack (100)

获得选项的对象

ngModel 取到的值为选中 nz-option 的 nzValue 值，当 nzValue 传入为一个对象时，ngModel 获取的值也是一个对象，compareWith 的用法参见 SelectControlValueAccessor。

      加载中

Select users

搜索用户

一个带有远程搜索，节流控制，请求时序控制，加载状态的多选示例。

      加载中

Select OS

自定义下拉菜单内容

通过 nzCustomContent 自定义下拉菜单选项显示的内容。

      加载中

Default 01

Default 02

Default Value

默认数据

当需要显示默认值，同时默认值又不在选项列表中时，可以使用 nzHide 在 nz-option 中将默认选项隐藏

      加载中

Lucy

形态变体

Select 形态变体，可选 outlined、filled、borderless、underlined 四种形态。

      加载中

20.0.0

Lucy

传入 Options

通过 nzOptions 直接传入选项内容

      加载中

topLefttopRightbottomLeftbottomRight

HangZhou #310000

弹出位置

可以通过 placement 手动指定弹出的位置。

      加载中

Select a person

带搜索框

展开后可对选项进行搜索。

      加载中

LargeDefaultSmall

a10

c12

a10

c12

tag

三种大小

三种大小的选择框，当 nzSize 分别为 large 和 small 时，输入框高度为 40px 和 24px ，默认高度为 32px。

      加载中

Lucy

分组

用 nz-option-group 进行选项分组。

      加载中

automatic tokenization

自动分词

试下复制 露西,杰克 到输入框里。只在 tags 和 multiple 模式下可用。

      加载中

User

Lucy

User

Lucy

前后缀

自定义前缀 nzPrefix 和后缀图标 nzSuffixIcon。

      加载中

Inserted are removed

隐藏已选择选项

通过 nzHide 隐藏下拉列表中已选择的选项。

      加载中

Select users

下拉加载

一个带有下拉加载远程数据的例子。

      加载中

a10

c12

大量数据

组件使用了虚拟滚动技术，可以同时处理大量数据。

      加载中

Select OS

自定义选择标签

通过 nzCustomTemplate 自定义 nz-select 显示的内容。

      加载中

自定义状态

使用 nzStatus 为 Select 添加状态，可选 error 或者 warning。

      加载中

a10

c12

2 / 3

最大选中数量

你可以通过设置 nzMaxMultipleCount 约束最多可选中的数量，当超出限制时会变成禁止选中状态。

      加载中

API#

<nz-select>
  <nz-option nzValue="lucy" nzLabel="Lucy"></nz-option>
</nz-select>

nz-selectcomponent#

参数	说明	类型	默认值	全局配置	版本
`[nzId]`	组件内部 input 的 id 值	`string`	-
`[ngModel]`	当前选中的 nz-option 的 nzValue 值，可双向绑定，当 `nzMode` 为 `multiple` 或 `tags` 时，ngModel 为数组	`any \| any[]`	-
`[compareWith]`	与 SelectControlValueAccessor 相同	`(o1: any, o2: any) => boolean`	`(o1: any, o2: any) => o1===o2`
`[nzAutoClearSearchValue]`	是否在选中项后清空搜索框，只在 `mode` 为 `multiple` 或 `tags` 时有效。	`boolean`	`true`
`[nzAllowClear]`	支持清除	`boolean`	`false`
`[nzBackdrop]`	浮层是否应带有背景板	`boolean`	`false`
`[nzVariant]`	形态变体	`'outlined' \| 'borderless' \| 'filled' \| 'underlined'`	`'outlined'`	✅	20.0.0
`[nzOpen]`	下拉菜单是否打开，可双向绑定	`boolean`	`false`
`[nzAutoFocus]`	默认获取焦点	`boolean`	`false`
`[nzDisabled]`	是否禁用	`boolean`	`false`
`[nzDropdownClassName]`	下拉菜单的 className 属性	`string \| string[]`	-
`[nzDropdownMatchSelectWidth]`	下拉菜单和选择器同宽	`boolean`	`true`
`[nzDropdownStyle]`	下拉菜单的 style 属性	`object`	-
`[nzCustomTemplate]`	自定义选择框的 Template 内容	`TemplateRef<{ $implicit: NzOptionComponent }>`	-
`[nzServerSearch]`	是否使用服务端搜索，当为 true 时，将不再在前端对 nz-option 进行过滤	`boolean`	`false`
`[nzFilterOption]`	是否根据输入项进行筛选。当其为一个函数时，会接收 `inputValueoption` 两个参数，当 `option` 符合筛选条件时，应返回 `true`，反之则返回 `false`。	`(input?: string, option?: NzOptionComponent) => boolean;`	-
`[nzMaxMultipleCount]`	最多选中多少个标签	`number`	`Infinity`
`[nzMode]`	设置 nz-select 的模式	`'multiple' \| 'tags' \| 'default'`	`'default'`
`[nzNotFoundContent]`	当下拉列表为空时显示的内容	`string \| TemplateRef<void>`	-
`[nzPlaceHolder]`	选择框默认文字	`string`	-
`[nzShowArrow]`	是否显示下拉小箭头	`boolean`	单选为 `true`，多选为 `false`
`[nzShowSearch]`	使单选模式可搜索	`boolean`	`false`
`[nzSize]`	选择框大小	`'large' \| 'small' \| 'default'`	`'default'`
`[nzStatus]`	设置校验状态	`'error' \| 'warning'`	-
`[nzPreix]`	自定义的选择框前缀	`TemplateRef<any> \| string`	-
`[nzSuffixIcon]`	自定义的选择框后缀图标	`TemplateRef<any> \| string`	-	✅
`[nzRemoveIcon]`	自定义的多选框清除图标	`TemplateRef<any>`	-
`[nzClearIcon]`	自定义的多选框清空图标	`TemplateRef<any>`	-
`[nzMenuItemSelectedIcon]`	自定义当前选中的条目图标	`TemplateRef<any>`	-
`[nzTokenSeparators]`	在 tags 和 multiple 模式下自动分词的分隔符	`string[]`	`[]`
`[nzLoading]`	加载中状态	`boolean`	`false`
`[nzMaxTagCount]`	最多显示多少个 tag	`number`	-
`[nzMaxTagPlaceholder]`	隐藏 tag 时显示的内容	`TemplateRef<{ $implicit: any[] }>`	-
`[nzOptions]`	option 列表，可以取代 nz-option，用法参见例子	`Array<{ label: string \| number \| TemplateRef<any>; value: any; key?: string \| number; disabled?: boolean; hide?: boolean; groupLabel?: string \| TemplateRef<any>;}>`	-
`[nzOptionHeightPx]`	下拉菜单中每个 Option 的高度	`number`	`32`	✅
`[nzOptionOverflowSize]`	下拉菜单中最多展示的 Option 个数，超出部分滚动	`number`	`8`
`[nzSelectOnTab]`	允许使用 TAB 键选择项目	`boolean`	`false`
`(ngModelChange)`	选中的 nz-option 发生变化时，调用此函数	`EventEmitter<any[]>`	-
`(nzOpenChange)`	下拉菜单打开状态变化回调	`EventEmitter<boolean>`	-
`(nzScrollToBottom)`	下拉列表滚动到底部的回调	`EventEmitter<any>`	-
`(nzOnSearch)`	文本框值变化时回调	`EventEmitter<string>`	-
`(nzOnClear)`	清空已选项时触发的回调函数。	`EventEmitter<any>`	-	-	20.0.0
`(nzFocus)`	focus 时回调	`EventEmitter<any>`	-
`(nzBlur)`	blur 时回调	`EventEmitter<any>`	-

nz-optioncomponent#

参数	说明	类型	默认值
`[nzDisabled]`	是否禁用	`boolean`	`false`
`[nzTitle]`	选项上的原生 title 提示	`string \| number`	-
`[nzLabel]`	选中该 nz-option 后，nz-select 中显示的文字	`string \| number`	-
`[nzValue]`	nz-select 中 ngModel 的值	`any`	-
`[nzKey]`	nz-select 中 ngModel 的值	`string \| number`	-
`[nzHide]`	是否在选项列表中隐藏该选项	`boolean`	`false`
`[nzCustomContent]`	是否自定义在下拉菜单中的 Template 内容，当为 true 时，nz-option 包裹的内容将直接渲染在下拉菜单中	`boolean`	`false`

nz-option-groupcomponent#

参数	说明	类型	默认值
`[nzLabel]`	组名	`string \| number \| TemplateRef<void>`	-

方法#

nz-selectcomponent#

名称	说明
`blur()`	取消焦点
`focus()`	获取焦点

FAQ#

Q：滚动时浮层元素没有跟随滚动位置#

默认情况下，浮层元素使用 body 作为滚动容器，如果使用了其他滚动容器，在自定义滚动容器元素上添加 CdkScrollable 指令。注意：您需要从 @angular/cdk/scrolling 导入 CdkScrollable 指令或 ScrollingModule 模块。

Select选择器

何时使用#

代码演示#

API#

nz-selectcomponent#

nz-optioncomponent#

nz-option-groupcomponent#

方法#

nz-selectcomponent#

FAQ#

Q：滚动时浮层元素没有跟随滚动位置#

Select
选择器