跳到主要内容
输入关键词开始搜索，↑ ↓ 选择，Enter 打开
没有找到匹配的文档

组合框

一个可自定义的类似下拉选择的组件，使用以标记为先的 HTML 构建，由 Menu 组件提供定位和键盘导航支持。

层级：components
查看原文
本页目录

概览

组合框组件使用标准的 HTML 标记提供了一个样式化的选择体验——一个切换按钮配合一个 .menu 覆盖层。与传统的选择增强不同，组合框是以标记为先：你可以直接在 HTML 中编写切换按钮和菜单项。JavaScript 处理显示/隐藏、选择状态、通过隐藏输入提交表单，以及键盘导航。

  • 对菜单项内容的完全控制（图标、描述、徽章、图片——任何内容）
  • 实时搜索/筛选
  • 已选项目的勾选标记
  • 单选和多选模式
  • 完整的键盘导航和可访问性
  • 通过自动创建的隐藏输入提交表单

示例

添加 data-bs-toggle="combobox" 到一个 <button> 元素，后跟一个 .menu 与 .menu-item 按钮。每个可选择的项目都需要一个 data-bs-value 属性

HTML
<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-name="option"
      data-bs-placeholder="Select an item…">
  <span class="combobox-value">Select an item…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="1">Option one</button>
  <button class="menu-item" type="button" data-bs-value="2">Option two</button>
  <button class="menu-item" type="button" data-bs-value="3">Option three</button>
</div>

占位符

在切换按钮上设置占位符文本为 data-bs-placeholder。当未选择任何内容时，.combobox-value 元素显示此文本，样式为 .combobox-placeholder。

HTML
<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-name="country"
      data-bs-placeholder="Pick a country…">
  <span class="combobox-value">Pick a country…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="us">United States</button>
  <button class="menu-item" type="button" data-bs-value="uk">United Kingdom</button>
  <button class="menu-item" type="button" data-bs-value="ca">Canada</button>
</div>

预选值

将 .selected 类和 aria-selected="true" 添加到菜单项以预先选择它。在初始化时，切换文本会自动更新。

HTML
<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-name="role"
      data-bs-placeholder="Choose a role…">
  <span class="combobox-value">Choose a role…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="admin">Admin</button>
  <button class="menu-item selected" type="button" data-bs-value="editor" aria-selected="true">Editor</button>
  <button class="menu-item" type="button" data-bs-value="viewer">Viewer</button>
</div>

带表单字段

使用 表单字段 组件，将下拉组合框与标签、描述和验证反馈信息垂直排列封装。

HTML
<div class="form-field">
  <label for="exampleCombobox" class="form-label">Combobox</label>
  <button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-name="country"
      data-bs-placeholder="Pick a country…">
    <span class="combobox-value">Pick a country…</span>
    <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
  </button>
  <div class="menu">
    <button class="menu-item" type="button" data-bs-value="us">United States</button>
    <button class="menu-item" type="button" data-bs-value="uk">United Kingdom</button>
    <button class="menu-item" type="button" data-bs-value="ca">Canada</button>
  </div>
</div>

自定义内容

由于菜单项是标准的 HTML，你可以在其中放置任何内容——SVG 图标、图片、描述文本、徽章或任何其他标记。

图标

将 .menu-item-icon 直接添加到菜单项内的 <svg> 元素中以显示前置图标。

HTML
<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-name="language"
      data-bs-placeholder="Choose a language…">
  <span class="combobox-value">Choose a language…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="html">
    <svg class="menu-item-icon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M14 4.5V14a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V2a2 2 0 0 1 2-2h5.5zm-3 0A1.5 1.5 0 0 1 9.5 3V1H4a1 1 0 0 0-1 1v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1V4.5z"/></svg>
    <span>HTML</span>
  </button>
  <button class="menu-item" type="button" data-bs-value="css">
    <svg class="menu-item-icon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M14 4.5V14a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V2a2 2 0 0 1 2-2h5.5zm-3 0A1.5 1.5 0 0 1 9.5 3V1H4a1 1 0 0 0-1 1v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1V4.5z"/></svg>
    <span>CSS</span>
  </button>
  <button class="menu-item" type="button" data-bs-value="js">
    <svg class="menu-item-icon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M14 4.5V14a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V2a2 2 0 0 1 2-2h5.5zm-3 0A1.5 1.5 0 0 1 9.5 3V1H4a1 1 0 0 0-1 1v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1V4.5z"/></svg>
    <span>JavaScript</span>
  </button>
</div>

描述

使用 .menu-item-content 进行弹性列布局，使用 .menu-item-description 作为辅助文本。

HTML
<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-name="role"
      data-bs-placeholder="Select a role…">
  <span class="combobox-value">Select a role…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="admin">
    <span class="menu-item-content">
      <span>Admin</span>
      <small class="menu-item-description">Full access to all resources</small>
    </span>
  </button>
  <button class="menu-item" type="button" data-bs-value="editor">
    <span class="menu-item-content">
      <span>Editor</span>
      <small class="menu-item-description">Can edit and publish content</small>
    </span>
  </button>
  <button class="menu-item" type="button" data-bs-value="viewer">
    <span class="menu-item-content">
      <span>Viewer</span>
      <small class="menu-item-description">Read-only access</small>
    </span>
  </button>
</div>

勾选图标

添加 .menu-item-check 直接在一个 <svg> 在每个菜单项内部显示一个勾选标记指示器。默认情况下它是隐藏的，当该项被选择时，它会变为可见。 .selected 班级

HTML
<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-name="status"
      data-bs-placeholder="Choose a status…">
  <span class="combobox-value">Choose a status…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item selected" type="button" data-bs-value="active" aria-selected="true">
    <span class="menu-item-content">
      <span>Active</span>
      <small class="menu-item-description">Visible to users</small>
    </span>
    <svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
  </button>
  <button class="menu-item" type="button" data-bs-value="draft">
    <span class="menu-item-content">
      <span>Draft</span>
      <small class="menu-item-description">Not yet published</small>
    </span>
    <svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
  </button>
  <hr class="menu-divider">
  <button class="menu-item" type="button" data-bs-value="archived">
    <span>Archived</span>
    <svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
  </button>
</div>

全部在一起

将三者结合，打造丰富的菜单项布局。

HTML
<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-name="priority"
      data-bs-placeholder="Set priority…">
  <span class="combobox-value">Set priority…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="low">
    <svg class="menu-item-icon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14m0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16"/></svg>
    <span class="menu-item-content">
      <span>Low</span>
      <small class="menu-item-description">No rush</small>
    </span>
    <svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
  </button>
  <button class="menu-item" type="button" data-bs-value="medium">
    <svg class="menu-item-icon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0M6.79 5.093A.5.5 0 0 0 6 5.5v5a.5.5 0 0 0 .79.407l3.5-2.5a.5.5 0 0 0 0-.814z"/></svg>
    <span class="menu-item-content">
      <span>Medium</span>
      <small class="menu-item-description">Normal priority</small>
    </span>
    <svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
  </button>
  <button class="menu-item" type="button" data-bs-value="high">
    <svg class="menu-item-icon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0M8 4a.905.905 0 0 0-.9.995l.35 3.507a.552.552 0 0 0 1.1 0l.35-3.507A.905.905 0 0 0 8 4m.002 6a1 1 0 1 0 0 2 1 1 0 0 0 0-2"/></svg>
    <span class="menu-item-content">
      <span>High</span>
      <small class="menu-item-description">Needs attention</small>
    </span>
    <svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
  </button>
</div>

搜索菜单项

在切换按钮上使用 data-bs-search="true" 启用筛选。在 .menu 内、项目之前添加搜索输入框和可选的无结果消息。项目通过将其 textContent 与查询匹配来进行筛选。

未找到结果
HTML
<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-name="country"
      data-bs-placeholder="Select a country…"
      data-bs-search="true">
  <span class="combobox-value">Select a country…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <div class="combobox-search">
    <input type="text" class="form-control combobox-search-input" placeholder="Search…" autocomplete="off" aria-label="Search…">
  </div>
  <button class="menu-item" type="button" data-bs-value="us">United States</button>
  <button class="menu-item" type="button" data-bs-value="uk">United Kingdom</button>
  <button class="menu-item" type="button" data-bs-value="ca">Canada</button>
  <button class="menu-item" type="button" data-bs-value="au">Australia</button>
  <button class="menu-item" type="button" data-bs-value="de">Germany</button>
  <button class="menu-item" type="button" data-bs-value="fr">France</button>
  <button class="menu-item" type="button" data-bs-value="jp">Japan</button>
  <button class="menu-item" type="button" data-bs-value="br">Brazil</button>
  <button class="menu-item" type="button" data-bs-value="in">India</button>
  <button class="menu-item" type="button" data-bs-value="mx">Mexico</button>
  <div class="combobox-no-results d-none">No results found</div>
</div>

群组

使用.menu-header元素在菜单中创建带标签的分组。

前端
后端
HTML
<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-name="language"
      data-bs-placeholder="Select a language…">
  <span class="combobox-value">Select a language…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <div class="menu-header">Frontend</div>
  <button class="menu-item" type="button" data-bs-value="html">HTML</button>
  <button class="menu-item" type="button" data-bs-value="css">CSS</button>
  <button class="menu-item" type="button" data-bs-value="js">JavaScript</button>
  <div class="menu-header">Backend</div>
  <button class="menu-item" type="button" data-bs-value="python">Python</button>
  <button class="menu-item" type="button" data-bs-value="ruby">Ruby</button>
  <button class="menu-item" type="button" data-bs-value="go">Go</button>
</div>

多选

将data-bs-multiple="true"添加到多选行为的切换按钮。选中的项目在点击时会切换，菜单保持打开状态。当选择多个项目时，切换按钮会显示数量。

HTML
<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-name="skills"
      data-bs-placeholder="Select skills…"
      data-bs-multiple="true">
  <span class="combobox-value">Select skills…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="html">
    HTML
    <svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
  </button>
  <button class="menu-item" type="button" data-bs-value="css">
    CSS
    <svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
  </button>
  <button class="menu-item" type="button" data-bs-value="js">
    JavaScript
    <svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
  </button>
  <button class="menu-item" type="button" data-bs-value="python">
    Python
    <svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
  </button>
  <button class="menu-item" type="button" data-bs-value="ruby">
    Ruby
    <svg class="menu-item-check" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 16 16"><path d="m2 7 4 5 8-8"/></svg>
  </button>
</div>

尺寸

使用切换按钮上的 .form-control-sm 或 .form-control-lg 来更改大小。

HTML
<button class="form-control form-control-sm combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-placeholder="Small select…">
  <span class="combobox-value">Small select…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="1">Option one</button>
  <button class="menu-item" type="button" data-bs-value="2">Option two</button>
</div>

<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-placeholder="Default select…">
  <span class="combobox-value">Default select…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="1">Option one</button>
  <button class="menu-item" type="button" data-bs-value="2">Option two</button>
</div>

<button class="form-control form-control-lg combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-placeholder="Large select…">
  <span class="combobox-value">Large select…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="1">Option one</button>
  <button class="menu-item" type="button" data-bs-value="2">Option two</button>
</div>

残疾

将 disabled 添加到切换按钮或单独的菜单项。

HTML
<button class="form-control combobox-toggle" type="button"
      data-bs-toggle="combobox"
      data-bs-placeholder="Cannot interact…"
      disabled>
  <span class="combobox-value">Cannot interact…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="1">Option one</button>
  <button class="menu-item" type="button" data-bs-value="2">Option two</button>
</div>

<button class="form-control combobox-toggle mt-3" type="button"
      data-bs-toggle="combobox"
      data-bs-placeholder="Select an option…">
  <span class="combobox-value">Select an option…</span>
  <svg class="combobox-caret" width="10" height="16" viewBox="0 0 10 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.46967 5.46967C0.762563 5.17678 1.23744 5.17678 1.53033 5.46967L5 8.93934L8.46967 5.46967C8.76256 5.17678 9.23744 5.17678 9.53033 5.46967C9.82322 5.76256 9.82322 6.23744 9.53033 6.53033L5.53033 10.5303C5.23744 10.8232 4.76256 10.8232 4.46967 10.5303L0.46967 6.53033C0.176777 6.23744 0.176777 5.76256 0.46967 5.46967Z" fill="currentcolor"/></svg>
</button>
<div class="menu">
  <button class="menu-item" type="button" data-bs-value="1">Available</button>
  <button class="menu-item" type="button" data-bs-value="2" disabled>Unavailable</button>
  <button class="menu-item" type="button" data-bs-value="3">Available</button>
</div>

表单提交

组合框创建了一个隐藏的 <input> 用于表单提交时 data-bs-name 设置在切换上。隐藏输入的 name 匹配属性值及其 value 每当选择更改时更新。

HTML
          <!-- What you write -->
<button class="form-control combobox-toggle" type="button"
        data-bs-toggle="combobox"
        data-bs-name="country">
  ...
</button>
<div class="menu">...</div>

<!-- What the JS creates (inserted before the toggle) -->
<input type="hidden" name="country" value="us">

对于多选，隐藏输入的值是以逗号分隔的所选值列表。

JavaScript

通过数据属性

属性描述
data-bs-toggle="combobox"在切换按钮上初始化组合框。
data-bs-value在一个 .menu-item当选择该选项时，提交并显示的值。
data-bs-search启用菜单中的搜索/筛选字段。
data-bs-multiple启用多选行为。
data-bs-namename 自动创建的用于表单提交的隐藏输入项。
data-bs-placeholder当未选择任何内容时，切换显示的占位文本。

依赖项

如果你是从源代码构建 Bootstrap 的 JS，则下列 JavaScript 文件是 combobox 插件所必需的：

文件描述
js/src/combobox.ts主组合框组件
js/src/base-component.ts基础组件类
js/src/menu.ts菜单组件
js/src/dom/data.ts元素数据存储
js/src/dom/event-handler.ts事件处理工具
js/src/dom/manipulator.ts数据属性操作
js/src/dom/selector-engine.tsDOM 选择器工具
js/src/util/config.ts配置基类
js/src/util/floating-ui.ts响应式布局工具
js/src/util/index.ts核心实用功能
@floating-ui/dom第三方定位库

选项

选项可以通过切换按钮上的数据属性传递（例如，data-bs-search="true"），也可以在通过 JavaScript 初始化时作为配置对象传递。

名称类型默认描述
multiplebooleanfalse启用多选模式。选择可以切换，菜单保持打开状态。
name字符串 | 空null自动创建的隐藏输入的名称。也可以通过设置 data-bs-name.
placeholderstring''切换的占位文本。也可以通过设置 data-bs-placeholder.
searchbooleanfalse在菜单中启用搜索输入。也可以通过设置 data-bs-search.
searchNormalizebooleanfalse将带重音的字符标准化以进行搜索匹配。
placementstring'bottom-start'菜单位置（使用浮动界面）。
offsetarray[0, 2]与切换开关的偏移 [skidding, distance].
boundary字符串 | 元素'clippingParents'菜单的溢出边界。

方法

方法描述
toggle切换菜单。
show显示菜单。
hide隐藏菜单。
dispose销毁组合框实例并移除隐藏输入。
getInstance从DOM元素获取组合框实例的静态方法。
getOrCreateInstance获取或创建组合框实例的静态方法。

事件

事件会在切换按钮元素上触发。

事件描述
show.bs.combobox当调用 show 方法时立即触发。
shown.bs.combobox当菜单被显示时触发。
hide.bs.combobox当调用 hide 方法时立即触发。
hidden.bs.combobox当菜单被隐藏时触发。
change.bs.combobox当做出选择时触发。事件详情包括 value 和 item。

无障碍访问

下拉组合框组件遵循 WAI-ARIA 下拉组合框模式：

  • 切换按钮有 aria-haspopup="listbox" 和 aria-expanded。
  • 每个可选择的项目都应该有 role="option" 和 aria-selected。
  • 完整的键盘导航：箭头键、Home、End、Enter、Space、Escape 和 Tab。
  • 禁用的项目具有 disabled 属性和 aria-disabled="true"。

CSS 自定义属性

下拉组合框使用以 --combobox-* 为前缀的 CSS 自定义属性来控制切换按钮，并从菜单组件继承 --menu-* 属性用于菜单覆盖层。完整的可用标记列表请参见 源 SCSS。