Select 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

在下拉列表中选择选项，可由数据直接生成面板，也可自定义选项组合，支持搜索与键盘操作。

使用选择

用于下拉单选。默认传 options 生成 Listbox / MenuItem；显式 children 替换默认选项面板。命令菜单优先 SelectButton；不是任意多选或自由输入控件。

• options 默认生成列表；显式 children 提供 Listbox / MenuItem 后替换默认列表。

• persistent 保存选择；action 只调用 onAction 并关闭，不保存本次选择。默认子项用 parts，显式子项直接配置。

• 列表通过 Escape 关闭后，字段型与 buttonTrigger／SelectButton 模式均恢复真实触发按钮焦点；搜索头关闭行为由共享 Listbox 管理。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Select, Listbox, MenuItem, Text, Button } from '@snowui-design-system/components';</script> <Select placeholder="请选择城市" style="width: 20rem; max-width: 100%;">    <Listbox>        <MenuItem as="item" value="shanghai">Shanghai</MenuItem>        <MenuItem as="item" value="hangzhou">Hangzhou</MenuItem>        <MenuItem as="item" value="shenzhen">Shenzhen</MenuItem>    </Listbox></Select>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

默认内置模式 / 显式组合模式

• 默认内置模式（推荐）：传入 options，Select 自动生成 Listbox 与 MenuItem；搜索框默认关闭，通过 parts.Listbox.search=true 开启；通过 parts.Button、parts.Listbox、parts.Input、parts.MenuItem 配置隐藏实例。

• options 中同一 value 的 label 或 disabled 更新时，当前选择的显示标签、搜索与键盘选项按新数据更新；调用方负责提供目标语言的业务文案。

• 显式组合模式：显式书写 Listbox / Input / MenuItem，用于复杂内容或逐项差异；子组件 Props 直接写在实例上。

• 显式 children 存在时替换默认内置 Listbox，不同时激活两套选项。

Select 内的 Listbox 默认 search=false。显式组合时使用 <Listbox search> 开启；默认内置模式使用 parts={{ Listbox: { search: true } }} 开启。独立 Listbox 的默认值不受影响。

<Select    options={[{ value: "a", label: "A" }]}/>

buttonTrigger 可将字段型 trigger 切换为真正的 bare Button；优先使用 triggerContent snippet，未提供时依次回退到选中项、placeholder、ariaLabel。适合 TableToolbar 的排序、筛选等图标操作。按钮保持 aria-haspopup="listbox"、aria-expanded、键盘导航和选中后焦点恢复。该模式的 Select 外层是无视觉 wrapper，不接入独立字段的 .snowui-field-bordered 外壳，最终背景、边框、尺寸与圆角只由真实 Button 宿主拥有。

2026-04-20 更新: 新增搜索 + 自定义值支持 — filterText / customOptions 状态由 Select 持有，内嵌 <Input as="search"> 可连接过滤逻辑；内嵌 Input 的 allowCustomValue prop 允许用户添加自定义选项；该属性不属于 Select。Combobox 已废弃。

2026-04-18 架构升级: Select v3.0.0 — Listbox 拆分为独立组件，API 从 <option> 切换到 <Listbox> + <MenuItem> 组合模式，表单提交改用 hidden <input>，不再依赖隐藏 <select> + MutationObserver。

2026-04-04 补充: 参考 Figma 9996:17631，Select 单独使用时默认保持 12 / 16 padding 与 8px gap；进入 Field 后，只看有没有 as="segment"。未标 segment 时由外层 Field 处理 12 / 16 与 gap = 8，Select 去掉自身 padding，但保留自身 gap；标了 segment 时保留 Select 自身的 padding 与 gap，并作为连续字段表面的一段参与分割线。

继承: 复用 Frame.svelte 的所有通用能力（状态、动效、响应式、Skeleton、样式编排）。 推荐容器: Field.svelte。 默认能力开关: enableResponsive=false, enableContext=true, enableScaleObserver=false。 自动布局协议: Select 根元素为 <Frame row>，trigger（content/fill）+ indicator（trailing/hug）由自动布局协议管理。

字段型原生 trigger 显式接入 layout.css 的 .snowui-native-control，只归一化 box sizing、margin 并继承消费环境的字体与颜色；Select 自身字号、行高、Padding、边框和状态视觉不依赖可选的 snowui-base.css。buttonTrigger 模式由 Button / Frame 的同一宿主基线承接。

2026-04-27 更新: Select v3.1.0 — 支持直系复杂 leading / trailing 槽位；自定义 trailing 替换默认 indicator。

显式内容与默认槽位

• 直系 Frame as="leading" / Frame as="trailing" 支持复杂结构；图形与短标签并排时使用 singleLine 和 Text lines={1}，内部单行与最小间距由附件 Frame 管理。

• Select 根布局为 leading: auto、trigger: minmax(0, 1fr)、trailing: auto。

• 存在自定义直系 as="trailing" 时，默认 indicator 隐藏，由自定义 trailing 替换末位槽。

槽位组合边界

复杂附件需要为可编辑／可选内容保留宽度；下例显式设置最小240 CSS px，并用ScrollArea在更窄容器中局部横向滚动。

• 支持直系复杂 leading / trailing 槽位。

• 自定义 trailing 替换默认 indicator。

表单组合与间距

• 基础节奏统一：Field 默认 padding = 12 / 16，gap = 8

• Select 单独使用时：组件自身带 12 / 16 padding 和 8 gap

• 放进 Field 后，先看有没有 as="segment"

• 没有 as="segment"：由外层 Field 负责 12 / 16 padding 与 8 gap；Select 去掉自身 padding，但保留自身 gap

• 有 as="segment"：这是连续字段表面的一段；保留 Select 自身的 padding 与 gap

• segment 之间才有分割线：横向是左右分割线，纵向是上下分割线

• 相邻 segment 之间只能有一条分割线，不能重复画线

• label / description / error 不负责 padding、gap、分割线，它们只是内容元素

• 普通 label + host + error：不作为 padding、gap 的判断依据，只负责文字内容

• Field row 或 Field column 里，如果是连续输入段，子项要显式写 as="segment"

组件定位

Select 是自定义下拉选择框，采用 Trigger + Listbox 组合架构：

• 自身渲染 Trigger 按钮 + ArrowLineUpDown 指示器

• 子内容为 <Listbox> + <MenuItem> 组合，Listbox 自行 portal 到 body

• 通过 ListboxOwnerContext（setContext）与子组件通信

• 表单提交通过 hidden <input type="hidden"> 桥接

• 标签、错误提示与连续字段段逻辑建议通过 Field 容器组合完成

• 单独使用时可保持兼容性的默认输入框表现

Frame 能力继承

Select 仍然通过外层 Frame 继承：

• responsive / stateStyle / customStates / variants / styles

• Hover / Click / Focus / whileAppear / timeline / orchestrate

• loading / skeleton / renderHints

• as / use / layoutId / itemId / scope / access

因此 Select 不是一个单纯的裸 <select>，而是 Frame + 原生 select host。

错误反馈 Shake

Select invalid / aria-invalid 默认自动播放错误 shake。单独使用时由 Select 自身反馈；进入 Field 后，嵌入态 Select 不单独抖动，由外层 Field 汇总后整体反馈。

错误态与 shake 不会自动聚焦，也不会模拟 focus-within；焦点态只来自用户真实聚焦、显式 autofocus 或业务代码主动调用 focus()。

布局模型

主布局模型：槽位宿主布局。定义见 ../../../specs/maintainers/LayoutProtocol.md §12.3（源码参考：specs/maintainers/LayoutProtocol.md）。

普通字段模式的根宿主固定采用单行内容协议，选中值可收缩，图标与标签的有效间距至少为 4 CSS px；gap={0}、根字号或间距缩放不压低下限，较大首选间距保持。buttonTrigger 模式由真实 Button 拥有图文内容，Select 的无视觉定位外壳不增加空白间距。自定义 children 保留原结构，弹层与表单协议不变。

Select 的根布局固定按 Leading / Trigger / Trailing 三段组织：

• 根节点是 Frame row，并在组件内部固定启用 enableAutoLayout；外部传入 enableAutoLayout={false} 不关闭 Select 的内部槽位协议。

• trigger 是 Content / Fill 槽，负责显示选中值或 placeholder，必须保持 min-width: 0 与文本截断能力。

• 默认 indicator 是 Trailing / Hug 槽。

• 存在直系自定义 as="trailing" 时，默认 indicator 隐藏，由自定义 trailing 替换末位槽。

• Listbox / MenuItem 是 Select 的弹层内容协议，不参与 Select 根三槽位布局。

能力边界

Select 负责：

• 单选下拉选择（Trigger + Listbox 组合架构）

• value / defaultValue 解析

• ARIA combobox + listbox 完整语义

• 键盘导航（↑↓ / Enter / Space / Escape / Tab）

• 通过 hidden <input> 桥接表单提交

• 通过 ListboxOwnerContext 驱动子 Listbox / MenuItem

• 持有 filterText 与 filteredOptions 状态，为内嵌 Input as="search" 提供过滤能力

• 持有 customOptions 列表，支持用户在运行时添加 / 删除自定义选项

Select 不负责：

• 业务级选项获取与远程联想

• 多选模式（未来可扩展）

使用示例

 <Field>  <Select placeholder="请选择状态">    <Listbox>      <MenuItem value="todo">待处理</MenuItem>      <MenuItem value="doing">处理中</MenuItem>      <MenuItem value="done">已完成</MenuItem>    </Listbox>  </Select></Field>  <Select placeholder="请选择城市">  <Listbox>    <Input as="search" placeholder="搜索..." />    <MenuItem value="beijing">北京</MenuItem>    <MenuItem value="shanghai">上海</MenuItem>    <MenuItem value="hangzhou">杭州</MenuItem>  </Listbox></Select>  <Select placeholder="请选择或输入">  <Listbox>    <Input as="search" allowCustomValue placeholder="搜索或输入新选项..." />    <MenuItem value="tag-a">Tag A</MenuItem>    <MenuItem value="tag-b">Tag B</MenuItem>  </Listbox></Select>  <Select name="priority" required placeholder="请选择优先级">  <Listbox>    <MenuItem value="low">低</MenuItem>    <MenuItem value="medium">中</MenuItem>    <MenuItem value="high">高</MenuItem>  </Listbox></Select>  <ScrollArea axis="horizontal" ariaLabel="Select with attachments" width="100%"><Select minWidth={240} placeholder="Tags">  <Frame as="leading" singleLine>    <Icon as="leading" icon={Resource.Tag} />    <Text lines={1}>Tags</Text>  </Frame>  <Frame as="trailing" singleLine>    <Text class="text-black-40" lines={1}>Multi-Select</Text>    <Icon as="trailing" icon={Resource.CaretRight} class="text-black-20" />  </Frame>  <Listbox>    <MenuItem as="item" value="design">Design</MenuItem>    <MenuItem as="item" value="code">Code</MenuItem>  </Listbox></Select></ScrollArea>

无障碍与表单建议

• Trigger 使用 role="combobox" + aria-haspopup="listbox" + aria-expanded + aria-controls

• Listbox 使用 role="listbox"，每个选项 role="option" + aria-selected

• 键盘导航完整支持：↑↓ 移动焦点，Enter/Space 确认，Escape 关闭，Tab 关闭

• 如果需要错误提示，建议通过 aria-describedby 关联 Field 内错误节点

• 如果需要搜索型下拉或异步联想，应使用 Combobox 组件