MultiSelector Props

名称	类型	默认值	说明
modelValue	(string | number)[]	[]	已选值。
options	MultiSelectorOption[]	必需	字符串、选项对象、分隔线或分组。
label	string	必需	字段标签。
isLabelHidden	boolean	false	视觉上隐藏标签，读屏仍然读得到。旧名 labelHidden 同样可用，两者任一为真就隐藏。
placeholder	string	Select… / 请选择	没有选中项时的占位符。
searchable	boolean	false	在列表里显示搜索框。
selectAll	boolean	false	显示全选行。跳过禁用项。
triggerDisplay	'count' | 'labels' | 'badges'	'count'	关闭后如何展示已选项。
maxBadges	number	3	badges 和 labels 最多露出几项，更窄时还会按宽度再收。
clearable	boolean	false	是否可清除。
hasClear	boolean	false	有选中项时显示清除按钮。和旧名 clearable 等价，两者任一为真即生效。
checkboxPosition	'start' | 'end'	'start'	勾选标记的位置。
variant	'input' | 'secondary' | 'ghost'	'input'	input 带边框。secondary 对齐次要按钮。ghost 适合工具栏。后两种上的 attached 状态会收成独立说明。
containerClass / controlClass	class	—	分别加到字段外壳和触发器本体。根上的 class 落在本体。选项上的 action 和单选一样：点它不改选择，面板变成两列网格。
disabled	boolean	false	是否禁用。
disabledMessage	string	—	禁用原因。和 disabled 一起用时，鼠标悬停或键盘聚焦会弹出提示，触发器靠 aria-disabled 保持可聚焦，但仍然打不开列表。不用再在外面套 Tooltip：禁用的控件收不到悬停事件。旧名 disabledReason 等价。
disabledReason	string	—	禁用原因。有值时控件仍可聚焦。和 disabledMessage 等价。
isDefaultOpen	boolean	false	挂载后就展开列表。
status	'default' | 'success' | 'warning' | 'error'	'default'	状态样式。
statusMessage	string	—	字段下方的状态说明。
statusVariant	'attached' | 'detached' | 'tooltip'	'attached'	状态说明的位置。ghost 会把 attached 收成独立说明。tooltip 把说明留在字段里的图标上。
size	'sm' | 'md' | 'lg'	'md'	尺寸。
name	string	—	表单字段名。每个已选值提交一次。
isReadOnly	boolean	false	只读。已选值还在，可以聚焦并提交，但不能打开或清除。不变暗。
isLoading	boolean	false	触发器显示加载指示。加载时没有创建行，也不显示空状态。
formatValue	(items) => string	—	自定义关闭后的文字。只用于数量和标签两种展示，标签徽章会忽略。没有选中项时不调用。
hasCreate	boolean	false	和搜索一起用。输入和任何标签都不相同（忽略大小写）时，第一行是创建。
handleRef	Ref | (handle) => void	—	从外面打开、关闭或查询。模板里传函数。只读和禁用时打开无效。
emptyText	string	无匹配项 / No matches	列表里没有任何选项时的文案。
emptySearchText	string	未找到结果 / No results found	搜索没有命中时的文案。

MultiSelector Emits

名称	载荷	说明
update:modelValue	value: (string | number)[]	选中项变化时触发。
change	value, change?	选中项变化时触发。创建时第二参是 { type: 'create', query }。
search	query: string	搜索文字变化时触发。
openChange	isOpen: boolean	列表打开或关闭时触发。
click	event: MouseEvent	触发器上的点击，在列表切换之后触发。取消不了切换。
focus	event: FocusEvent	触发器获得焦点时触发。
keydown	event: KeyboardEvent	触发器上内置键盘模型没处理的按键才触发。它处理并取消的按键不再透出。

MultiSelector Slots

名称	参数	说明
icon	—	触发器开头的图标。
option	{ option, selected, active }	自定义选项。
empty	—	自定义空状态。
trigger	{ id, onClick, onKeyDown, onFocus, aria-haspopup, aria-expanded, aria-controls, aria-busy, triggerRef }	用一个自制控件（行内图标、芯片、图标按钮）替掉整个字段和触发器。把绑定铺到控件上，并把 triggerRef 作为 :ref 传进去，列表就以它为锚点。字段外壳（标签、状态、清除、加载）都不再渲染。