选择器

选择器提供经过设计的单选列表，适合需要一致浮层或丰富选项内容的场景。需要搜索或创建值时应使用组合框。

尚未选择水果。

安装Terminal

npm install @a3s-lab/ui@0.4.1

<div id="select-theme" class="select" data-placeholder="主题">
  <button type="button" role="combobox" class="w-[180px]" id="select-theme-trigger" aria-label="主题" aria-haspopup="listbox" aria-autocomplete="none" aria-expanded="false" aria-controls="select-theme-listbox">
    <span class="truncate">主题</span>
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down text-muted-foreground opacity-50 shrink-0"><path d="m6 9 6 6 6-6" /></svg>
  </button>
  <div id="select-theme-popover" data-popover aria-hidden="true">
    <div role="listbox" id="select-theme-listbox" aria-orientation="vertical" aria-labelledby="select-theme-trigger">
      <div role="option" data-value="light">浅色</div>
      <div role="option" data-value="dark">深色</div>
      <div role="option" data-value="system">跟随系统</div>
    </div>
  </div>
  <input type="hidden" name="theme" value="" />
</div>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

用法

引入 CSS

导入 Tailwind 和一个完整的 A3S UI 样式包。

@import "tailwindcss";
@import "@a3s-lab/ui/a3s.css";

或者只导入基本 CSS、选择 CSS 组件和一个样式包。

@import "tailwindcss";
@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/select.css";
@import "@a3s-lab/ui/styles/a3s.css";

使用CDN或批量程序导入？请参见安装页。

引入 JavaScript

复制或提供完整的 A3S UI JavaScript 包。

<script src="/assets/js/all.min.js" defer></script>

或者复制或提供 A3S UI 运行时和选择脚本。

<script src="/assets/js/runtime.min.js" defer></script>
<script src="/assets/js/select.min.js" defer></script>

使用CDN或批量程序导入？请参见安装页。

添加选择器 HTML

<div id="select-theme" class="select" data-placeholder="主题">
  <button type="button" role="combobox" class="w-[180px]" id="select-theme-trigger" aria-label="主题" aria-haspopup="listbox" aria-autocomplete="none" aria-expanded="false" aria-controls="select-theme-listbox">
    <span class="truncate">主题</span>
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down text-muted-foreground opacity-50 shrink-0"><path d="m6 9 6 6 6-6" /></svg>
  </button>
  <div id="select-theme-popover" data-popover aria-hidden="true">
    <div role="listbox" id="select-theme-listbox" aria-orientation="vertical" aria-labelledby="select-theme-trigger">
      <div role="option" data-value="light">浅色</div>
      <div role="option" data-value="dark">深色</div>
      <div role="option" data-value="system">跟随系统</div>
    </div>
  </div>
  <input type="hidden" name="theme" value="" />
</div>

HTML 结构

<div class="select">

选择器根节点。使用 data-placeholder 显示未选择时的提示文本；多选模式支持 data-close-on-select="true"，对象序列化支持 data-format="object"。

<button type="button">

只读选择组合框的触发器。必须通过关联的 <label>、aria-label 或 aria-labelledby 提供稳定的无障碍名称；占位文本只是值提示，不能替代标签。使用 role="combobox"、aria-haspopup="listbox"、aria-autocomplete="none"、aria-expanded 和 aria-controls。控制器会为选项补充稳定 ID，并通过 aria-activedescendant 暴露当前选项。

<div data-popover aria-hidden="true">

浮层内容。通过共享 Popover 规则支持 data-side 和 data-align；运行时会根据可视视口翻转并限制列表位置。

<div role="listbox">

选项容器。多选模式添加 aria-multiselectable="true"。

<div role="option" data-value="..." data-label="...">: 可选择的选项。提交值来自 data-value。可选的 data-label 控制已选显示文本和 data-format="object" 中的标签；省略时使用去除首尾空白后的文本内容。
<hr role="separator"> Optional: 分隔选项组或相邻选项。
<div role="group"> Optional: 选项组。使用 aria-labelledby 关联组标题。
<span role="heading"> Optional: 选项组标题。

<input type="hidden">

提交值。根节点存在 data-placeholder 时，空值表示尚未选择。单选保存字符串，多选保存 JSON 数组；设置 data-format="object" 后，值序列化为 { value, label } 对象。

JavaScript API

应用程序编程接口	类型	描述
`change`	活动	在 `event.detail.value` 和 `event.detail.selected` 的选择发生更改时调度。
`select.refresh()`	方法	在现有 `role="listbox"` 元素内的子项发生更改后重新扫描选项。

示例

组

<div id="select-groups" class="select" data-placeholder="选择水果">
  <button type="button" role="combobox" class="w-[180px]" id="select-groups-trigger" aria-label="水果" aria-haspopup="listbox" aria-autocomplete="none" aria-expanded="false" aria-controls="select-groups-listbox">
    <span class="truncate">选择水果</span>
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down text-muted-foreground opacity-50 shrink-0"><path d="m6 9 6 6 6-6" /></svg>
  </button>
  <div id="select-groups-popover" data-popover aria-hidden="true">
    <div role="listbox" id="select-groups-listbox" aria-orientation="vertical" aria-labelledby="select-groups-trigger">
      <div role="group" aria-labelledby="select-groups-fruits">
        <span role="heading" id="select-groups-fruits">水果</span>
        <div role="option" data-value="apple">苹果</div>
        <div role="option" data-value="banana">香蕉</div>
        <div role="option" data-value="blueberry">蓝莓</div>
      </div>
      <hr role="separator" />
      <div role="group" aria-labelledby="select-groups-vegetables">
        <span role="heading" id="select-groups-vegetables">蔬菜</span>
        <div role="option" data-value="carrot">胡萝卜</div>
        <div role="option" data-value="broccoli">西兰花</div>
        <div role="option" data-value="spinach">菠菜</div>
      </div>
    </div>
  </div>
  <input type="hidden" name="select-groups-value" value="" />
</div>

可滚动

包含许多滚动项目的选择。

<div id="select-scrollable" class="select" data-placeholder="选择时区">
  <button type="button" role="combobox" class="w-[280px]" id="select-scrollable-trigger" aria-label="时区" aria-haspopup="listbox" aria-autocomplete="none" aria-expanded="false" aria-controls="select-scrollable-listbox">
    <span class="truncate">选择时区</span>
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down text-muted-foreground opacity-50 shrink-0"><path d="m6 9 6 6 6-6" /></svg>
  </button>
  <div id="select-scrollable-popover" data-popover aria-hidden="true">
    <div role="listbox" id="select-scrollable-listbox" class="scrollbar-sm max-h-70 overflow-y-auto" aria-orientation="vertical" aria-labelledby="select-scrollable-trigger">
      <div role="group" aria-labelledby="select-scrollable-north-america">
        <span role="heading" id="select-scrollable-north-america">北美</span>
        <div role="option" data-value="est">Eastern Standard Time (EST)</div>
        <div role="option" data-value="cst">Central Standard Time (CST)</div>
        <div role="option" data-value="mst">Mountain Standard Time (MST)</div>
        <div role="option" data-value="pst">Pacific Standard Time (PST)</div>
        <div role="option" data-value="akst">Alaska Standard Time (AKST)</div>
        <div role="option" data-value="hst">Hawaii Standard Time (HST)</div>
      </div>
      <div role="group" aria-labelledby="select-scrollable-europe-africa">
        <span role="heading" id="select-scrollable-europe-africa">欧洲与非洲</span>
        <div role="option" data-value="gmt">Greenwich Mean Time (GMT)</div>
        <div role="option" data-value="cet">Central European Time (CET)</div>
        <div role="option" data-value="eet">Eastern European Time (EET)</div>
        <div role="option" data-value="west">Western European Summer Time (WEST)</div>
        <div role="option" data-value="cat">Central Africa Time (CAT)</div>
        <div role="option" data-value="eat">East Africa Time (EAT)</div>
      </div>
      <div role="group" aria-labelledby="select-scrollable-asia">
        <span role="heading" id="select-scrollable-asia">亚洲</span>
        <div role="option" data-value="msk">Moscow Time (MSK)</div>
        <div role="option" data-value="ist">India Standard Time (IST)</div>
        <div role="option" data-value="cst_china">China Standard Time (CST)</div>
        <div role="option" data-value="jst">Japan Standard Time (JST)</div>
        <div role="option" data-value="kst">Korea Standard Time (KST)</div>
        <div role="option" data-value="ist_indonesia">Indonesia Central Standard Time (WITA)</div>
      </div>
      <div role="group" aria-labelledby="select-scrollable-australia-pacific">
        <span role="heading" id="select-scrollable-australia-pacific">澳大利亚与太平洋地区</span>
        <div role="option" data-value="awst">Australian Western Standard Time (AWST)</div>
        <div role="option" data-value="acst">Australian Central Standard Time (ACST)</div>
        <div role="option" data-value="aest">Australian Eastern Standard Time (AEST)</div>
        <div role="option" data-value="nzst">New Zealand Standard Time (NZST)</div>
        <div role="option" data-value="fjt">Fiji Time (FJT)</div>
      </div>
      <div role="group" aria-labelledby="select-scrollable-south-america">
        <span role="heading" id="select-scrollable-south-america">南美</span>
        <div role="option" data-value="art">Argentina Time (ART)</div>
        <div role="option" data-value="bot">Bolivia Time (BOT)</div>
        <div role="option" data-value="brt">Brasilia Time (BRT)</div>
        <div role="option" data-value="clt">Chile Standard Time (CLT)</div>
      </div>
    </div>
  </div>
  <input type="hidden" name="select-scrollable-value" value="" />
</div>

整体禁用

<div id="select-disabled" class="select" data-placeholder="选择水果">
  <button type="button" role="combobox" class="w-[180px]" id="select-disabled-trigger" aria-label="水果" aria-haspopup="listbox" aria-autocomplete="none" aria-expanded="false" aria-controls="select-disabled-listbox" disabled>
    <span class="truncate">选择水果</span>
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down text-muted-foreground opacity-50 shrink-0"><path d="m6 9 6 6 6-6" /></svg>
  </button>
  <div id="select-disabled-popover" data-popover aria-hidden="true">
    <div role="listbox" id="select-disabled-listbox" aria-orientation="vertical" aria-labelledby="select-disabled-trigger">
      <div role="option" data-value="apple">苹果</div>
      <div role="option" data-value="banana">香蕉</div>
      <div role="option" data-value="blueberry">蓝莓</div>
      <div role="option" data-value="grapes" aria-disabled="true">葡萄</div>
      <div role="option" data-value="pineapple">菠萝</div>
    </div>
  </div>
  <input type="hidden" name="select-disabled-value" value="" />
</div>

禁用选项

禁用选项仍保留在列表中提供上下文，但指针、方向键、Home、End 和键入匹配都会跳过它。

<div id="select-disabled-option" class="select" data-placeholder="选择水果">
  <button type="button" role="combobox" class="w-[180px]" id="select-disabled-option-trigger" aria-label="水果" aria-haspopup="listbox" aria-autocomplete="none" aria-expanded="false" aria-controls="select-disabled-option-listbox">
    <span class="truncate">选择水果</span>
    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down text-muted-foreground opacity-50 shrink-0"><path d="m6 9 6 6 6-6" /></svg>
  </button>
  <div id="select-disabled-option-popover" data-popover aria-hidden="true">
    <div role="listbox" id="select-disabled-option-listbox" aria-orientation="vertical" aria-labelledby="select-disabled-option-trigger">
      <div role="option" data-value="apple">苹果</div>
      <div role="option" data-value="grapes" aria-disabled="true">葡萄（暂不可用）</div>
      <div role="option" data-value="pineapple">菠萝</div>
    </div>
  </div>
  <input type="hidden" name="select-disabled-option-value" value="" />
</div>

无效

水果

请选择有效的水果后继续。

<div class="field" data-invalid="true">
  <label for="select-invalid-trigger">水果</label>
  <div id="select-invalid" class="select" data-placeholder="选择水果">
    <button type="button" role="combobox" class="w-[180px]" id="select-invalid-trigger" aria-haspopup="listbox" aria-autocomplete="none" aria-expanded="false" aria-controls="select-invalid-listbox" aria-invalid="true">
      <span class="truncate">选择水果</span>
      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down text-muted-foreground opacity-50 shrink-0"><path d="m6 9 6 6 6-6" /></svg>
    </button>
    <div id="select-invalid-popover" data-popover aria-hidden="true">
      <div role="listbox" id="select-invalid-listbox" aria-orientation="vertical" aria-labelledby="select-invalid-trigger">
        <div role="option" data-value="apple">苹果</div>
        <div role="option" data-value="banana">香蕉</div>
        <div role="option" data-value="blueberry">蓝莓</div>
        <div role="option" data-value="grapes">葡萄</div>
        <div role="option" data-value="pineapple">菠萝</div>
      </div>
    </div>
    <input type="hidden" name="fruit" value="" />
  </div>
  <p role="alert">请选择有效的水果后继续。</p>
</div>

RTL

<div dir="rtl">
  <div id="select-rtl" class="select" data-placeholder="اختر فاكهة">
    <button type="button" role="combobox" class="w-[180px]" id="select-rtl-trigger" aria-label="الفاكهة" aria-haspopup="listbox" aria-autocomplete="none" aria-expanded="false" aria-controls="select-rtl-listbox">
      <span class="truncate">اختر فاكهة</span>
      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down text-muted-foreground opacity-50 shrink-0"><path d="m6 9 6 6 6-6" /></svg>
    </button>
    <div id="select-rtl-popover" data-popover aria-hidden="true">
      <div role="listbox" id="select-rtl-listbox" aria-orientation="vertical" aria-labelledby="select-rtl-trigger">
        <div role="group" aria-labelledby="select-rtl-fruits">
          <span role="heading" id="select-rtl-fruits">الفواكه</span>
          <div role="option" data-value="apple">تفاح</div>
          <div role="option" data-value="banana">موز</div>
          <div role="option" data-value="blueberry">توت أزرق</div>
          <div role="option" data-value="grapes">عنب</div>
          <div role="option" data-value="pineapple">أناناس</div>
        </div>
      </div>
    </div>
    <input type="hidden" name="select-rtl-value" value="" />
  </div>
</div>

无障碍

每个触发器都必须通过关联标签、aria-label 或 aria-labelledby 获得稳定的无障碍名称；占位文本和当前值不能替代字段标签。焦点始终保留在只读选择组合框触发器上，当前选项由 aria-activedescendant 标识。方向键只在可用选项间移动，Home 和 End 到达首尾可用选项，可打印字符执行忽略重音符号的键入匹配，Enter 或空格提交，Escape 在不改变值的情况下关闭并把焦点还给触发器。

#选择器

#用法

引入 CSS

引入 JavaScript

添加选择器 HTML

#HTML 结构

#JavaScript API

#示例

#组

#可滚动

#整体禁用

#禁用选项

#无效

#RTL

#无障碍

选择器

用法

HTML 结构

JavaScript API

示例

组

可滚动

整体禁用

禁用选项

无效

RTL

无障碍