表单 · 4 / 21
Select st-select
单选下拉框。选项写在 light DOM：原生 option 或 st-option 富内容；也支持 :options 动态数组。键盘、弹层翻转和 change 回显都已内建。
基础用法与两种 variant
选项直接写在组件内部，组件只把它们当数据源，读取后自绘下拉列表。placeholder 只在未选中时显示；初始选中用 default-value，不要给 option 写 selected。
LIVE
st-select / option
outlined
filled + 初始选中
无 value 的 option
示例代码
<st-select placeholder="请选择水果" on:change="onFruit">
<option value="apple">苹果</option>
<option value="banana">香蕉</option>
</st-select>
<st-select variant="filled" default-value="banana">...</st-select>disabled 与校验色
disabled 会降到 0.38 透明度并关闭弹层，点击与键盘都不再响应。color 控制 focus 描边 / 底线色，用来表达 error、success 等校验结果；未设置时回退 primary。
LIVE
disabled / color
disabled
disabled + filled
color="error"
color="success"
示例代码
<st-select placeholder="禁用状态" disabled>...</st-select>
<st-select color="error" placeholder="必选项">...</st-select>长列表与键盘
列表最高 15em，超出内部滚动。打开后 ↑↓ 循环移动激活项并自动滚到可见，Home / End 跳首尾，Enter / Space 选中，Escape / Tab 关闭；下方空间不足时弹层会自动向上翻转。
LIVE
键盘 / 滚动示例代码
<st-select placeholder="长列表">
<option value="1">选项 01</option>
<option value="2">选项 02</option>
<option value="3">选项 03</option>
</st-select>富内容选项与 st-option
原生 option 内可嵌 span / b，子元素会被克隆到下拉项；闭合态默认只显示纯文本。复杂或双语内容推荐 st-option：插槽负责下拉项，label 属性决定闭合态文字；插槽里的图标（svg / img / iconify-icon / slot="icon"）会同步显示在闭合态。
LIVE
st-option / label
原生 option 富内容
st-option + label
缺省 value 演示
示例代码
<st-select default-value="relay">
<st-option value="direct" label="直连"><iconify-icon icon="mdi:flash"></iconify-icon> 直连 Direct</st-option>
<st-option value="relay" label="邀请码"><iconify-icon icon="mdi:key-variant"></iconify-icon> 邀请码 Invite code</st-option>
</st-select>:options 动态选项
数据驱动时优先用 :options 绑定数组（[{ value, label }]），组件会重建列表并保留当前选中值。数组内容变化时给 data 赋新数组即可；纯 JS 场景也可以用 el.options = [...]。
LIVE
:options
cities
extendedCities
修改数据源
换一组城市
示例代码
<st-select :options="cities" placeholder="请选择城市"></st-select>
<script>
export default async () => ({
data: {
cities: [
{ value: "bj", label: "北京" },
{ value: "sh", label: "上海" },
],
},
});
</script>宽度、字号与 change 回显
尺寸默认值都以 em 计，改 font-size 等比缩放；宽度、高度、圆角直接用原生 CSS。change 只在用户选中时派发，回调里 e.target.value 已是新值。
LIVE
style / change
font-size: 12px
width: 280px
height + 圆角
示例代码
<st-select style="font-size: 12px;" placeholder="小号">...</st-select>
<st-select style="width: 280px;" placeholder="固定宽度">...</st-select>
<st-select style="height: 48px; border-radius: 12px;">...</st-select>属性
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
variant | "outlined" | "filled" | "outlined" | M3 两种输入框类型 |
default-value | string | 无 | 初始选中项的 value |
placeholder | string | 无 | 未选中时的占位文本 |
color | M3 角色名 / 自定义变量名 | 无 | focus 描边 / 底线色 |
disabled | boolean | 无 | 0.38 透明度，阻断交互并关闭弹层 |
options | Array<{ value, label }> | 无 | 动态选项入口：:options 或 el.options = [] |
插槽 / 事件 / 注意
- 选项：
<option>或<st-option>（value/label+ 富内容插槽）。 - 事件：
change（用户选中时派发，composed）；程序改el.value不派发。 - 方法：
focus()/blur()；键盘 ↑↓ / Enter / Space / Home / End / Escape / Tab。 value是运行时 property；初始选中用default-value，不要写 selected。- 弹层渲染在 shadow 内，
overflow: hidden祖先会裁剪它；组件只负责上下翻转。