React 组件

UGSelect 选择器

从数据中选择一个或多个值，覆盖筛选、分组、清空、禁用、键盘操作和原生表单提交。

导入方式

按需从包入口导入组件，并在应用入口引入一次样式文件。

tsx

import { UGSelect } from '@ug666/ui-react'

基础选择

受控值保留选项原始类型，方向键、Home、End、Enter、Space 和字符检索均可操作。

发布状态

当前值：draft

多选与数量限制

多选值使用数组；达到上限后保留已选项，并禁用其余候选项。

参与角色

最多选择 3 项

筛选、分组与清空

筛选只改变候选列表；分组来自 option.group，清空会恢复未选择状态。

目标环境

远程查询与加载

remoteMethod 只负责查询；默认防抖 300ms，中文输入法组合结束后才发起查询，结果和 loading 仍由应用控制。

远程城市

弹层容器与裁剪

选项面板默认传送到 body，根据视口空间自动翻转与收拢，并在离场动画完成后卸载。

受限容器内选择

选项面板不会被当前容器裁剪

创建选项与默认高亮

输入不存在的内容后可直接创建；defaultFirstOption 让 Enter 选择当前首项。

项目标签

多选折叠与值类型

折叠只改变展示；数字 1 与字符串“1”使用不同身份，不会错误互选。

折叠多选

原始值类型

当前类型：number

尺寸

尺寸由组件或 ConfigProvider 统一控制，宽度始终由外层布局决定。

default

状态与空数据

错误、帮助、禁用、无数据与无匹配结果使用各自明确的反馈。

审批结果

模型列表加载失败（request id: 20260730063805111984525826）

锁定状态

空数据

原生表单

name、required 和 defaultValue 同步到原生 select；提交保持原始选项值，表单重置会恢复初始选择。

属性

属性	类型	默认值	说明
options	SelectOption[]	必填	选项数据；支持 disabled 与 group。
value / defaultValue	string \| number \| Array<string \| number>	—	受控值或非受控初始值；multiple 时使用数组。
multiple	boolean	false	开启多选模式。
multipleLimit	number	0	多选数量上限；0 表示不限制。
clearable	boolean	false	有选择值时显示清空操作。
filterable	boolean	false	打开后提供选项筛选输入框。
filterMethod	(query, option) => boolean	标签包含查询词	覆盖默认筛选规则。
remote / remoteMethod / remoteDebounce	boolean / (query) => void \| Promise<void> / number	false / — / 300	由应用按查询词远程更新 options，并控制查询防抖毫秒数。
loading / loadingText	boolean / string	false / '加载中'	显示异步加载状态和提示文案。
reserveKeyword	boolean	false	多选后保留当前筛选词。
allowCreate / defaultFirstOption	boolean / boolean	false / false	允许由筛选词创建选项，并控制回车时是否默认选择首项。
collapseTags / maxCollapseTags / collapseTagsTooltip	boolean / number / boolean	false / 1 / false	折叠多选值，控制保留数量，并可通过原生提示查看隐藏项。
placeholder	string	'请选择'	未选择时的提示。
size	'sm' \| 'default' \| 'lg'	全局配置 / default	选择器尺寸。
disabled	boolean	全局配置 / false	禁用交互。
label / helperText / error	string	—	字段标签、帮助说明和错误反馈。
name / required	原生 select 属性	— / false	参与原生表单提交与必填校验；提交值保持原始 string/number，不包含内部身份编码。
noDataText / noMatchText	string	暂无选项 / 没有匹配项	空数据与无匹配结果文案。
teleported / appendTo	boolean / HTMLElement \| string	true / document.body	将选项面板传送到指定容器，避免被滚动区裁剪；默认包含视口翻转、边界收拢和完整离场动效。
onValueChange	(value) => void	—	选择值变化时触发，保留原始 string/number 类型。
onOpenChange / onClear	回调	—	展开状态变化与清空时触发。
原生属性 / ref	SelectHTMLAttributes / Ref<HTMLSelectElement>	—	其余属性透传到用于表单提交的原生 select。