菜单

下拉菜单组件

相关源文件

Semantic UI 中的下拉菜单组件是一个多功能的UI元素,允许用户从列表中选择一个或多个项目。它支持各种配置,包括标准选择下拉菜单、可搜索下拉菜单、多选和远程数据加载。

有关下拉菜单的表单验证信息,请参见表单验证

组件概览

来源:src/definitions/modules/dropdown.js11-49 src/definitions/modules/dropdown.less24-34

下拉菜单组件是作为一个jQuery插件实现的,可将HTML元素转换为交互式下拉菜单。它提供了一种灵活的方式来管理选项列表中的选择,具有广泛的配置选项和全面的API。

初始化和结构

下拉菜单组件可以在任何元素上初始化,但通常在带有类ui dropdown<div>元素上,或在被转换为自定义下拉菜单的本地<select>元素上进行。

DOM结构

来源:src/definitions/modules/dropdown.js60-73 src/definitions/modules/dropdown.less44-71

下拉菜单结构包括:

  • 根元素 (.ui.dropdown)
  • 文本元素 (.text) - 显示当前选择项
  • 图标元素 (.dropdown.icon) - 视觉指示器
  • 菜单元素 (.menu) - 包含可选择的项目
  • 项目元素 (.item) - 菜单中的单个选项

对于搜索下拉菜单,还包含一个额外的搜索输入框。

初始化流程

当下拉菜单初始化时,会发生以下过程:

来源:src/definitions/modules/dropdown.js91-118 src/definitions/modules/dropdown.js299-406

选择下拉菜单

用于从列表中选择单个项目的标准下拉菜单。

来源:src/definitions/modules/dropdown.less356-376 src/definitions/modules/dropdown.js356-376

搜索下拉菜单

允许用户通过输入进行选项搜索。

来源:src/definitions/modules/dropdown.less543-571 src/definitions/modules/dropdown.js890-900

多选

支持选择多个项目。

来源:src/definitions/modules/dropdown.less639-647 src/definitions/modules/dropdown.js228-253

可清除下拉菜单

在2.4.0版本中添加,此变体增加了一个X图标以清除当前选择。

来源:RELEASE-NOTES.md62-63 src/definitions/modules/dropdown.js932-950

下拉菜单组件拥有一套丰富的可配置选项。以下是关键设置表:

设置类型默认描述
on字符串'click'显示菜单的事件('click'、'hover'、'focus'、'manual')
allowAdditions布尔值false允许用户添加自己的项目
allowCategorySelection布尔值false是否允许选择类别
apiSettings对象{}如果使用远程数据,则为API调用设置
clearable布尔值false允许清除下拉菜单的值
transition字符串'auto'显示菜单时使用的动画
fullTextSearch布尔值/字符串false是否搜索全文或仅搜索开头。可以是'exact'
match字符串'both'匹配算法('both'、'value'、'text')
placeholder字符串'auto'为空时显示的文本
forceSelection布尔值true当字段失去焦点时强制选择一个项目

来源:src/definitions/modules/dropdown.js42-90 RELEASE-NOTES.md45-62

事件处理

来源:src/definitions/modules/dropdown.js534-590 src/definitions/modules/dropdown.js251-333

下拉菜单组件通过一个全面的事件系统处理各种用户交互:

  1. 点击/悬停事件:显示或隐藏下拉菜单
  2. 搜索事件:根据用户输入过滤下拉菜单项
  3. 项目选择:设置值并触发回调
  4. 键盘导航:允许用户使用箭头键导航,并使用Enter键选择

API 接口

下拉菜单组件提供了丰富的API用于编程控制:

来源:src/definitions/modules/dropdown.js22-37 src/definitions/modules/dropdown.js452-525

关键 API 方法

  • show:显示下拉菜单
  • hide:隐藏下拉菜单
  • toggle:切换下拉菜单的可见性
  • refresh:刷新下拉菜单状态
  • clear:移除所有选择
  • set value:将下拉菜单设置为特定值
  • set selected:将指定值设置为选中状态
  • set text:设置下拉菜单文本而不改变值
  • set selected:设置项目的选中状态
  • remove selected:移除项目的选中状态
  • get value:获取当前下拉菜单值
  • get text:获取当前下拉菜单文本
  • get item:按值获取特定项目

来源: src/definitions/modules/dropdown.js452-525 src/definitions/modules/dropdown.js1242-1350

远程数据集成

下拉菜单组件可以通过 AJAX 请求从远程 API 端点加载选项

远程数据支持的关键特性

  1. 自动 API 设置,支持可配置的端点
  2. 支持缓存 API 响应
  3. 客户端远程数据过滤(2.2.8 版本新增)
  4. 请求节流,防止过多的 API 调用

来源: src/definitions/modules/dropdown.js739-782 RELEASE-NOTES.md370-371

与其他组件的集成

表单和验证

下拉菜单可以与表单组件无缝协作进行验证

来源: src/definitions/behaviors/form.js185-196 src/definitions/behaviors/form.js420-437

下拉菜单可以在 UI 菜单中使用,并考虑特殊样式

来源: src/definitions/modules/dropdown.less304-322 dist/components/menu.css52-56

让我们看看下拉菜单组件中一些关键行为是如何实现的

搜索功能

来源: src/definitions/modules/dropdown.js256-268 src/definitions/modules/dropdown.js784-846 src/definitions/modules/dropdown.js847-881

搜索功能

  1. 捕获搜索字段中的用户输入
  2. 使用各种匹配方法根据搜索查询过滤项目
  3. 更新菜单以仅显示匹配项目
  4. 未找到结果时显示适当的消息

选择行为

来源: src/definitions/modules/dropdown.js270-297 src/definitions/modules/dropdown.js1112-1170

特殊功能和增强

可清除下拉菜单

此功能在 2.4.0 版本中添加,它为下拉菜单添加了一个 (X) 图标,允许用户一键清除当前选择。

来源: RELEASE-NOTES.md62-63 src/definitions/modules/dropdown.less932-938

远程数据过滤

在 2.2.8 版本中添加,filterRemoteData 设置允许在客户端过滤远程数据

来源: RELEASE-NOTES.md370-371 src/definitions/modules/dropdown.js723-736

用户添加选项

用户添加自定义选项的功能由 allowAdditions 设置控制

启用后,用户可以通过输入并按回车键添加新选项。

来源: src/definitions/modules/dropdown.js208-226 src/definitions/modules/dropdown.js709-711

性能和最佳实践

  1. 基础情况下使用原生 select:对于没有高级功能的简单选择,原生 <select> 元素可能性能更好。

  2. 限制项目数量:大量项目可能会影响性能,尤其是在启用搜索时。

  3. 搜索防抖:下拉菜单会自动处理搜索输入的防抖,以防止过多的过滤操作。

  4. 使用适当的事件委托:下拉菜单使用事件委托来高效处理动态创建项目上的事件。

  5. 考虑缓存设置:使用远程数据时,启用缓存以在多次执行相同搜索时提高性能。

来源: src/definitions/modules/dropdown.js739-782 src/definitions/modules/dropdown.js147-154

浏览器兼容性

Dropdown 组件兼容所有现代浏览器,并为旧版浏览器提供兼容性支持

  • 使用特性检测 MutationObserver
  • 实现移动设备的触摸事件处理
  • 为可访问性提供适当的键盘导航

来源: src/definitions/modules/dropdown.js147-154 src/definitions/modules/dropdown.js543-556

结论

Semantic UI 的下拉菜单组件是一款功能丰富、多才多艺的控件,适用于选择任务。它提供了广泛的自定义选项和全面的 API,同时保持了简洁直观的用户体验。从简单的选择下拉菜单到可搜索的带有远程数据的多选控件,该组件可以适应许多不同的使用场景。