chenzy-design

如何引入

import { Select } from '@chenzy-design/svelte';

基础用法

受控单选，onChange 回调返回选中值，disabled 项不可选。

已选：（未选）

多选

设置 multiple 开启多选，选中项以 Tag 形式展示。

已选：（未选）

可搜索

设置 filter 开启输入过滤，适合选项较多的场景。

分组

options 含 { label, options } 即渲染为分组下拉。

已选：（未选）

尺寸与状态

size 三档尺寸，status 标记 warning / error 校验态。

校验状态：

前缀与清除

prefix 前缀内容，clearable 清除按钮，showArrow 控制下拉箭头。

远程搜索

onSearch 防抖回调外部更新 options，配合 loading 展示加载态。

输入触发远程搜索

创建条目

allowCreate 允许在 filter 无匹配时创建并选中新选项，onCreate 回调。

已选：（未选）

标签折叠

多选 maxTagCount 超出折叠为 +N，showRestTagsPopover 悬浮展示剩余。

已选 4 项

虚拟化

virtualized 开启列表虚拟化，2000 项仅渲染视口内选项。

2000 项，仅渲染视口内选项

命令式方法

bind:this 拿实例调 open/close/focus/selectAll/deselectAll 等命令式方法。

已选 0 项

API 参考

Select

Props

属性	说明	类型	默认值
`value`	—	`string\|number\|(string\|number)[]`	undefined
`defaultValue`	—	`string\|number\|(string\|number)[]`	undefined
`options`	选项；含 { label, options:[] } 即分组	`OptionData[] \| OptionGroup[]`	[]
`multiple`	—	`boolean`	false
`filter`	—	`boolean`	false
`open`	—	`boolean`	undefined
`defaultOpen`	—	`boolean`	false
`size`	—	`'small'\|'default'\|'large'`	default
`status`	—	`'default'\|'warning'\|'error'`	default
`placeholder`	—	`string`	'请选择'
`ariaLabel`	combobox 触发器可访问名	`string`	undefined
`ariaLabelledby`	关联外部 label 的 id（优先于 ariaLabel）	`string`	undefined
`id`	触发器 id，用于关联外部 <label for="...">	`string`	undefined
`disabled`	—	`boolean`	false
`clearable`	—	`boolean`	false
`borderless`	无边框模式	`boolean`	false
`autoFocus`	挂载后自动聚焦触发器	`boolean`	false
`autoAdjustOverflow`	浮层被遮挡时自动翻转方向（映射 use:floating autoAdjust，对齐 Semi）	`boolean`	true
`maxTagCount`	多选 tag 超出折叠为 +N（0=不折叠）	`number`	0
`maxTagTextLength`	单个 Tag 文本最大长度，超出截断为「前缀…」，完整文本经 title 查看	`number`	undefined
`showRestTagsPopover`	多选 maxTagCount 折叠出 +N 时，hover +N 用 Popover 浮层展示剩余全部 Tag（对齐 Semi restTagsPopover）	`boolean`	false
`restTagsPopoverProps`	透传给 +N 悬停 Popover 浮层的配置（spread 到 Popover，可覆盖 position/trigger/spacing 等）	`object`	undefined
`expandRestTagsOnClick`	多选 maxTagCount 折叠时，浮层打开态下点击 +N 就地展开剩余全部 Tag（纯展示，不改值）	`boolean`	false
`ellipsisTrigger`	多选且有 maxTagCount 时，对溢出可见 Tag 文本做单行省略（完整文本经 title 查看）	`boolean`	false
`showArrow`	是否显示触发器右侧下拉箭头；false 隐藏（suffix 存在时以 suffix 为准）	`boolean`	true
`clickToHide`	浮层已展开时，点击触发器是否收起浮层	`boolean`	false
`defaultActiveFirstOption`	打开浮层时默认高亮首个可用选项（键盘 Enter 可直接选中）	`boolean`	true
`allowCreate`	filter 无匹配时可创建新选项	`boolean`	false
`autoClearSearchValue`	多选选中后自动清空搜索词	`boolean`	true
`optionLabelProp`	用作回显的字段名	`string`	'label'
`searchPosition`	搜索框位置（仅 filter=true 生效）：dropdown=浮层顶部搜索框（打开自动聚焦）；trigger=输入内联在触发器上就地过滤	`'dropdown' \| 'trigger'`	'dropdown'
`inputProps`	透传给搜索 input 的额外属性（勿传 value/onChange/onFocus 等覆盖内部搜索回调的键）	`object`	undefined
`preventScroll`	autoFocus/命令式聚焦触发器时传入 focus({ preventScroll })，避免页面跳动	`boolean`	false
`insetLabel`	内嵌标签：浮入触发器左侧的常驻标签（纯展示，不影响值/过滤）	`string \| Snippet`	undefined
`insetLabelId`	insetLabel 的 id，经 aria-labelledby 关联触发器 combobox（仅 insetLabel 存在时生效）	`string`	undefined
`onSearch`	远程搜索（防抖回调，外部更新 options）	`(query: string) => void`	undefined
`loading`	远程加载中（显示 spinner）	`boolean`	false
`searchDebounce`	onSearch 防抖毫秒	`number`	300
`virtualized`	选项虚拟化：大数据下拉只渲染视口内 option（仅非分组生效，分组时回退全量）	`boolean`	false
`optionHeight`	虚拟化选项行高（px），需与样式实际行高一致	`number`	32
`maxHeight`	下拉最大高度（px）；虚拟化时同时作为视口高度	`number`	256
`dropdownMatchSelectWidth`	浮层宽度是否跟随触发器；false 时浮层自适应内容宽度	`boolean`	true
`dropdownClassName`	浮层根 div 追加的自定义 className（与内置 cd-select__dropdown 并存）	`string`	undefined
`dropdownStyle`	浮层根 div 合并的自定义内联样式（勿含 position/transform）	`string`	undefined
`zIndex`	浮层层级（z-index）；不传由 CSS 层级 token 控制	`number`	undefined
`dropdownMargin`	浮层与触发器间距(px)，映射到 floating offset；object 按 placement 主轴取值	`number \| { top?, bottom?, left?, right? }`	undefined
`destroyOnClose`	关闭时销毁浮层 DOM	`boolean`	false
`getPopupContainer`	浮层挂载目标容器	`() => HTMLElement`	undefined
`onChange`	—	`(v: string\|number\|(string\|number)[]) => void`	undefined
`onOpenChange`	—	`(open: boolean) => void`	undefined
`onSelect`	选中某项时触发	`(value, option) => void`	undefined
`onDeselect`	多选取消某项时触发	`(value, option) => void`	undefined
`onClear`	点击清除按钮时触发	`() => void`	undefined
`onCreate`	allowCreate 创建新项时触发	`(value: string) => void`	undefined
`onFocus`	触发器获焦时触发	`() => void`	undefined
`onBlur`	触发器失焦时触发	`() => void`	undefined
`onScrollToBottom`	浮层列表滚动触底时触发	`() => void`	undefined
`onListScroll`	浮层选项列表滚动时触发（携带原生 scroll 事件）	`(e: Event) => void`	undefined
`onExceed`	多选超出 maxTagCount 时触发（携带被隐藏的 option）	`(option) => void`	undefined
`onChangeWithObject`	携带完整 option 对象的 change 回调	`(option \| option[]) => void`	undefined

Methods

属性	类型	说明
`open()`	`—`	命令式展开下拉列表（对齐 Semi）
`close()`	`—`	命令式收起下拉列表（对齐 Semi）
`focus()`	`—`	命令式聚焦触发器（尊重 preventScroll，对齐 Semi）
`clearInput()`	`—`	命令式清空搜索框（对齐 Semi）
`deselectAll()`	`—`	命令式清空所有已选项（对齐 Semi）
`selectAll()`	`—`	命令式选中所有可选 Option（仅多选，对齐 Semi）
`search(value, event?)`	`—`	命令式设置搜索值并触发搜索（对齐 Semi）
`rePosition()`	`—`	命令式触发浮层重新定位（对齐 Semi）

Accessibility

设计变量

变量	默认值	用法
`--cd-transition-delay-select-bg`	`var(--cd-motion-delay-none)`	选择器-背景色-延迟时间
`--cd-transition-delay-select-border`	`var(--cd-motion-delay-none)`	选择器-边框-延迟时间
`--cd-transition-delay-select-option-bg`	`var(--cd-motion-delay-none)`	选择器-选项-延迟时间
`--cd-transition-duration-select-bg`	`var(--cd-motion-duration-none)`	选择器-背景色-动画持续时间
`--cd-transition-duration-select-border`	`var(--cd-motion-duration-none)`	选择器-边框-动画持续时间
`--cd-transition-duration-select-option-bg`	`var(--cd-motion-duration-none)`	选择器-选项-动画持续时间
`--cd-transition-function-select-bg`	`var(--cd-motion-ease-in)`	选择器-背景色-过渡曲线
`--cd-transition-function-select-border`	`var(--cd-motion-ease-in)`	选择器-边框-过渡曲线
`--cd-transition-function-select-option-bg`	`var(--cd-motion-ease-in)`	选择器-选项-过渡曲线