Select 下拉选择器

super-select 是一款手绘风下拉选择器。它直接读取默认 Slot 中的原生 option 与 optgroup，同时覆盖单选、搜索、多选标签、分组、清空、校验、空状态和加载状态。

筛选提示先让选项值保持唯一、稳定，再组合搜索、多选或级联逻辑；图标和自定义触发内容均由 Slot 提供。

类型

基础选择器

带前缀

城市

可搜索

多选标签

分组选项

可清空

前缀图标

自定义触发内容

选择项 →

html

<super-select searchable clearable aria-label="选择城市">
  <optgroup label="华东">
    <option value="shanghai">上海</option>
    <option value="hangzhou">杭州</option>
  </optgroup>
  <optgroup label="华南">
    <option value="shenzhen">深圳</option>
  </optgroup>
</super-select>

trigger Slot 只替换触发区域的展示内容，选择状态和点击行为仍由 super-select 管理。请放入 span、图标等非交互内容，不要在其中嵌套按钮或另一个表单控件。

尺寸与外观

尺寸会同步调整高度、间距和字号；variant 用于改变轮廓，不改变选择行为。

大

中

小

默认

圆角

填充

幽灵

状态

readonly 允许聚焦和查看面板，但不能新增、移除或清空选择；disabled 则同时禁止聚焦与交互。loading 打开后展示加载面板，并暂时禁止改变值。

默认悬停聚焦禁用只读基础

搜索

下拉面板

面板复用原生 option / optgroup 作为数据源。disabled、hidden、label、selected 和文本变化会被同步；仅通过 JavaScript 修改 option.selected 属性后，应调用 refreshOptions()。

分组选项

空状态

加载状态

空状态和加载状态也可以完全自定义：

html

<super-select open loading aria-label="加载成员">
  <span slot="loading">正在同步成员列表…</span>
</super-select>

<super-select open aria-label="空成员列表">
  <span slot="empty">还没有可选成员</span>
</super-select>

校验与提示

validation 表达结果语义，helper-text 提供说明。错误状态会给内部组合框设置 aria-invalid="true"，错误提示使用 role="alert"；其他提示使用礼貌播报。

成功

警告

错误

帮助提示

三级联动组合

省、市、区级联由三个 super-select 和业务数据组合完成。本组件库没有额外提供 Select Group、Cascader 或 Date 组件，也不会把业务层级规则内置进基础选择器。

const province = document.querySelector("#province");
const city = document.querySelector("#city");
const district = document.querySelector("#district");

province.addEventListener("super-select-change", (event) => {
  replaceOptions(city, regions[event.detail.value].cities);
  replaceOptions(district, []);
});

city.addEventListener("super-select-change", (event) => {
  replaceOptions(district, districts[event.detail.value]);
});

function replaceOptions(select, items) {
  select.replaceChildren(
    ...items.map(({ value, label }) => new Option(label, value)),
  );
  select.value = "";
  select.refreshOptions();
}

值与选项约束

单选的 value 是字符串；多选的 value 是 string[]，必须通过 JavaScript property 传入数组，HTML attribute 只能表达字符串。
多选的初始 HTML 可以在多个原生 option 上使用 selected；后续读取和写入仍应使用组件的 value property。
每个 option 的 value 必须非空并在同一选择器内唯一。空值会被忽略，重复值无法形成可靠的一一映射。
程序化修改 value 不会派发用户事件。只有用户选择、移除标签或清空时才会触发 super-select-change。

const tags = document.querySelector("#tags");

tags.multiple = true;
tags.value = ["food", "travel"];
await tags.updateComplete;

无障碍与键盘

组件内部使用 combobox + listbox / option 语义，并通过 aria-expanded、aria-activedescendant、aria-multiselectable、aria-busy 与帮助文本关联描述状态。无明确可见标签时，应提供 aria-label；内置按钮的中文名称可通过对应的 *-label 属性本地化。

按键	行为
`Enter` / `Space`	非搜索模式打开面板或选择当前选项
`ArrowDown` / `ArrowUp`	打开面板，并在可用选项间循环移动
`Home` / `End`	非搜索模式移到第一个 / 最后一个可用选项；搜索输入中保留文本光标行为
`Escape`	关闭面板并把焦点留在组合框
`Tab`	关闭面板并继续正常焦点导航
字符键	非搜索模式按选项标签进行前缀定位

API

Attributes / Properties

名称	类型	默认值	说明
`value`	`string \| string[]`	`""`	当前值；`multiple` 时必须使用 JS 数组 property
`multiple`	`boolean`	`false`	开启多选与标签展示
`searchable`	`boolean`	`false`	使用可输入的搜索触发器，仅过滤当前已有选项
`clearable`	`boolean`	`false`	有可编辑值时显示清空按钮；已选中的禁用选项会被保留
`disabled`	`boolean`	`false`	禁止聚焦、打开和选择
`readonly`	`boolean`	`false`	可聚焦和查看，但禁止修改选择
`required`	`boolean`	`false`	向内部组合框提供 `aria-required`，不代表表单校验契约
`loading`	`boolean`	`false`	面板打开时显示加载状态并禁止改值
`open`	`boolean`	`false`	控制面板是否展开；程序化写入不会触发 open-change 事件
`name`	`string`	`""`	写入 change 事件详情，不参与原生表单提交
`size`	`large \| medium \| small`	`medium`	组件尺寸
`variant`	`default \| pill \| filled \| ghost`	`default`	外观变体
`validation`	`none \| success \| warning \| error \| info`	`none`	校验视觉与辅助语义
`placeholder`	`string`	`请选择`	未选择时的占位内容
`helper-text`	`string`	`""`	组件下方的帮助或错误信息
`aria-label`	`string`	`""`	内部组合框与列表的可访问名称
`clear-label`	`string`	`清空选择`	清空按钮的可访问名称
`remove-label`	`string`	`移除`	标签移除按钮的名称前缀
`search-label`	`string`	`搜索选项`	未显式提供 `aria-label` 时搜索框的名称
`search-placeholder`	`string`	`搜索并选择`	面板展开时搜索输入的占位内容
`empty-text`	`string`	`暂无可选项`	默认空状态文案
`loading-text`	`string`	`加载中...`	默认加载状态文案

原生 option 支持 value、label、selected、disabled 与 hidden；原生 optgroup 支持 label、disabled 与 hidden。

Events

所有自定义事件均支持冒泡，并能穿过 Shadow DOM。

名称	`detail`	说明
`super-select-change`	`{ value, values, name, selectedOptions, originalEvent }`	用户选择、移除标签或清空后触发
`super-select-clear`	`{ previousValue, originalEvent }`	用户点击清空按钮时触发，随后还会触发 change
`super-select-open-change`	`{ open, reason, originalEvent }`	用户打开或关闭面板时触发；`reason` 为 `trigger \| keyboard \| search \| selection \| escape \| outside`
`super-select-search`	`{ query, originalEvent }`	搜索输入内容变化时触发

Methods

名称	说明
`click()`	模拟点击触发区域；禁用时无操作
`focus(options?)`	聚焦内部组合框
`blur()`	移除内部组合框焦点
`refreshOptions()`	重新读取原生选项及其选中状态

Slots

名称	说明
默认 Slot	原生 `option` / `optgroup` 数据源，不接受自定义 Option 组件
`prefix`	触发器左侧标签、文字或图标
`trigger`	触发区域的展示内容；只放非交互内容
`indicator`	替换默认下拉箭头
`empty`	自定义空状态内容
`loading`	自定义加载状态内容

CSS Parts

名称	说明
`control`	手绘边框触发容器
`prefix` / `trigger` / `search` / `search-icon`	前缀与两类组合框触发区域
`value` / `placeholder`	当前值容器与占位内容
`tags` / `tag` / `tag-remove`	多选标签区域、单个标签及移除按钮
`clear-button` / `validation-icon` / `indicator`	内置操作与状态指示
`popup` / `listbox`	下拉浮层与列表容器
`group` / `group-label`	选项分组与分组标题
`option` / `option-check`	单个选项与选择标记
`empty` / `loading`	空状态与加载状态容器
`helper`	帮助或错误文本

CSS Custom Properties

css

super-select {
  --super-select-width: 240px;
  --super-select-height: 38px;
  --super-select-padding-inline: 12px;
  --super-select-gap: 8px;
  --super-select-font-size: 15px;
  --super-select-background: #fffef9;
  --super-select-color: #292524;
  --super-select-placeholder-color: #64748b;
  --super-select-border-color: #34445f;
  --super-select-hover-color: #3f9b68;
  --super-select-focus-color: #356df3;
  --super-select-shadow-color: #a8b3bf;
  --super-select-validation-color: #34445f;
  --super-select-panel-background: #fffef9;
  --super-select-panel-max-height: 260px;
  --super-select-option-hover-background: #eef5ff;
  --super-select-option-selected-background: #dfeaff;
  --super-select-option-selected-color: #174ea6;
  --super-select-tag-background: #edf4ff;
  --super-select-tag-border-color: #9fb7dc;
  --super-select-z-index: 30;
  --super-select-rotation: -0.16deg;
}

表单限制

super-select 当前不是 form-associated Custom Element。required 和 name 只增强内部可访问语义与事件详情，组件不会自动进入 FormData，也不支持原生表单 reset 或外部 constraint validation。需要提交时，请监听 super-select-change，把值同步到应用状态或隐藏表单字段。

Select 下拉选择器 ​

类型 ​

尺寸与外观 ​

状态 ​

下拉面板 ​

校验与提示 ​

三级联动组合 ​

值与选项约束 ​

无障碍与键盘 ​

API ​

Attributes / Properties ​

Events ​

Methods ​

Slots ​

CSS Parts ​

CSS Custom Properties ​

表单限制 ​