搜索插件、代码仓与 APP 分类

multi_dropdown 封面
插件详情v4.0.0

multi_dropdown

功能强大且可高度自定义的流式 Flutter 小部件,适用于多种多选场景。

AndroidiOSmacOSWindowsLinux
近 30 天下载
4.8万
喜欢数
386
Pub 分数
160

安装插件

flutter pub add multi_dropdown

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

一个经过优化的 Flutter 小部件,专为多功能多选设计,提供广泛的自定义选项。它允许用户从下拉列表中选择多个项目,具有流畅的动画效果和灵活的样式设置。该包支持 Android、iOS、macOS、Windows 和 Linux 等多种平台,非常适合跨平台应用。凭借直观的 API 和响应式设计,它可显著提升表单、筛选器和设置界面中的用户体验。该组件注重性能与易用性,可无缝集成到现有的 Flutter 项目中。

适合场景

  • 具有多个选项的表单输入
  • 使用多个条件过滤数据
  • 用户偏好设置
  • 仪表板中的标签选择
  • 动态表单字段

主要特点

  • 可自定义的下拉菜单外观
  • 对平台特定行为的支持
  • 平滑过渡动画
  • 丰富的主题选项
  • 灵活的项目选择处理
  • 可访问性支持

适合对象

  • 开发复杂表单的开发者
  • 需要多选 UI 的应用
  • 跨平台 Flutter 应用程序
  • 需要可重用组件的设计系统
  • 注重用户体验一致性的团队

使用建议

  • 需要仔细管理大型数据集的状态
  • 可能需要额外的逻辑来过滤/搜索
  • 超长列表对性能的影响
  • 有限的内置搜索功能
  • 自定义样式可能需要对 Flutter 小部件有更深入的理解

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

MultiSelect Dropdown

Pub Version License GitHub issues Very Good Analysis Flutter Dart

A powerful and highly customizable multi-select dropdown widget for Flutter. Supports single & multi-select, search, form validation, programmatic control, and extensive visual customization.

Preview

Features

  • ✅ Multi-select & single-select modes
  • ✅ Searchable dropdown with customizable search field
  • ✅ Form validation support with autovalidateMode
  • ✅ Programmatic control via MultiSelectController
  • ✅ Async data loading with MultiDropdown.future()
  • ✅ Extensive decoration classes (chips, field, dropdown, items, search)
  • ✅ Pre-selected & disabled items
  • ✅ Max selection limit with maxSelections
  • ✅ Chip overflow control with maxDisplayCount
  • ✅ Custom item builders & selected item builders
  • ✅ Header & footer widgets in the dropdown
  • ✅ Expand direction control (auto, up, down)
  • ✅ Close on back button support
  • ✅ Full InputDecoration override for form consistency
  • ✅ Grouped items with customizable section headers
  • ✅ Select All / Deselect All toggle with customizable labels
  • ✅ Custom search filter for fuzzy matching and multi-field search
  • ✅ Bottom sheet mode for mobile-friendly item selection

Installation

Add to your pubspec.yaml:

dependencies:
  multi_dropdown: ^3.2.1

Quick Start

Basic Multi-Select
MultiDropdown<String>(
  items: [
    DropdownItem(label: 'Australia', value: 'AU'),
    DropdownItem(label: 'Canada', value: 'CA'),
    DropdownItem(label: 'India', value: 'IN'),
    DropdownItem(label: 'United States', value: 'US'),
  ],
  onSelectionChange: (selectedItems) {
    debugPrint('Selected: $selectedItems');
  },
);
Single Select
MultiDropdown<String>(
  items: items,
  singleSelect: true,
  fieldDecoration: FieldDecoration(
    hintText: 'Choose a role',
    suffixIcon: const Icon(Icons.keyboard_arrow_down_rounded),
  ),
  onSelectionChange: (values) {
    debugPrint('Selected: ${values.first}');
  },
);
Searchable Dropdown
MultiDropdown<String>(
  items: items,
  searchEnabled: true,
  searchDecoration: SearchFieldDecoration(
    hintText: 'Type to search...',
  ),
);
With Form Validation
MultiDropdown<String>(
  items: items,
  maxSelections: 4,
  autovalidateMode: AutovalidateMode.onUserInteraction,
  validator: (selectedItems) {
    if (selectedItems == null || selectedItems.isEmpty) {
      return 'Please select at least one item';
    }
    return null;
  },
);
Async Data Loading
MultiDropdown<int>.future(
  future: () async {
    final response = await http.get(Uri.parse('https://api.example.com/users'));
    final data = jsonDecode(response.body) as List;
    return data.map((e) => DropdownItem(
      label: e['name'] as String,
      value: e['id'] as int,
    )).toList();
  },
);

Controller

Use MultiSelectController to programmatically control the dropdown:

final controller = MultiSelectController<String>();

controller.setItems(items);       // Set/replace items
controller.addItem(item);         // Add a single item
controller.addItems(items);       // Add multiple items

controller.selectAll();           // Select all items
controller.clearAll();            // Deselect all items
controller.selectAtIndex(0);      // Select item at index
controller.selectWhere((i) => i.value == 'dart');   // Select by predicate
controller.unselectWhere((i) => i.value == 'dart'); // Deselect by predicate
controller.toggleWhere((i) => i.value == 'dart');   // Toggle by predicate
controller.disableWhere((i) => i.value == 'admin'); // Disable by predicate

controller.openDropdown();        // Open the dropdown
controller.closeDropdown();       // Close the dropdown
controller.clearSearch();         // Clear search query

controller.items;                 // All items
controller.selectedItems;         // Selected items
controller.disabledItems;         // Disabled items
controller.isOpen;                // Dropdown open state

Examples

The example app contains 8 dedicated examples, each in its own file:

Example File Description
🌍 Country Picker basic_example.dart Multi-select with flag emojis and chip wrapping
🎯 Task Priority single_select_example.dart Single-select with color-coded result card
👥 Team Members searchable_example.dart Search with custom itemBuilder (avatars)
🏷️ Issue Labels custom_style_example.dart Color-coded chips, maxDisplayCount, disabled items
🍳 Recipe Ingredients controller_example.dart All MultiSelectController methods
💼 Job Application form_validation_example.dart Form validation, maxSelections, submit flow
🌐 Async Loading future_example.dart MultiDropdown.future() with loading spinner
♿ Accessibility accessibility_example.dart Font scaling slider, high contrast, Semantics

Run the example:

cd example
flutter run

API Reference

MultiDropdown
Parameter Type Description Default
items List<DropdownItem<T>> The list of dropdown items Required
singleSelect bool Single-select mode false
chipDecoration ChipDecoration Chip styling configuration ChipDecoration()
fieldDecoration FieldDecoration Field styling configuration FieldDecoration()
dropdownDecoration DropdownDecoration Dropdown panel configuration DropdownDecoration()
searchDecoration SearchFieldDecoration Search field configuration SearchFieldDecoration()
dropdownItemDecoration DropdownItemDecoration Item styling configuration DropdownItemDecoration()
itemBuilder DropdownItemBuilder<T>? Custom item widget builder null
selectedItemBuilder SelectedItemBuilder<T>? Custom selected item builder null
itemSeparator Widget? Separator between items null
validator String? Function(...) Form validation callback null
autovalidateMode AutovalidateMode When to auto-validate .disabled
controller MultiSelectController<T>? Programmatic controller null
maxSelections int Max selectable items (0 = unlimited) 0
enabled bool Whether the dropdown is enabled true
searchEnabled bool Whether search is enabled false
focusNode FocusNode? Custom focus node null
future FutureRequest<T>? Async item loading null
onSelectionChange OnSelectionChanged<T>? Selection change callback null
onSearchChange ValueChanged<String>? Search text change callback null
closeOnBackButton bool Close on back button press false
DropdownItem
Parameter Type Description Default
label String Display label Required
value T Associated value Required
disabled bool Whether item is disabled false
selected bool Whether item is pre-selected false
ChipDecoration
Parameter Type Description Default
deleteIcon Widget? Chip delete icon Icon(Icons.close)
backgroundColor Color? Chip background color Color(0xFFE0E0E0)
labelStyle TextStyle? Chip label text style null
padding EdgeInsets Chip padding EdgeInsets.symmetric(horizontal: 12, vertical: 4)
border BoxBorder Chip border Border()
spacing double Spacing between chips 8.0
runSpacing double Spacing between chip rows 12.0
borderRadius BorderRadiusGeometry Chip border radius BorderRadius.circular(12)
wrap bool Wrap chips or scroll horizontally true
maxDisplayCount int? Max visible chips (shows "+N more") null
FieldDecoration
Parameter Type Description Default
labelText String? Label text above the field null
hintText String? Hint text in the field 'Select'
border InputBorder? Field border null
focusedBorder InputBorder? Border when focused null
disabledBorder InputBorder? Border when disabled null
errorBorder InputBorder? Border on validation error null
suffixIcon Widget? Trailing icon Icon(Icons.arrow_drop_down)
prefixIcon Widget? Leading icon null
labelStyle TextStyle? Label text style null
hintStyle TextStyle? Hint text style null
borderRadius double Border radius 12.0
animateSuffixIcon bool Animate suffix icon rotation true
padding EdgeInsets? Content padding EdgeInsets.symmetric(horizontal: 12, vertical: 8)
backgroundColor Color? Background fill color null
showClearIcon bool Show clear/deselect icon true
selectedItemTextStyle TextStyle? Selected item text style (single-select) null
inputDecoration InputDecoration? Full InputDecoration override null
DropdownDecoration
Parameter Type Description Default
backgroundColor Color Dropdown background color Colors.white
elevation double Dropdown elevation 1.0
maxHeight double Maximum dropdown height 400.0
borderRadius BorderRadius Dropdown border radius BorderRadius.circular(12)
marginTop double Gap between field and dropdown 0.0
header Widget? Header widget inside dropdown null
footer Widget? Footer widget inside dropdown null
noItemsFoundText String Text when no items match search 'No items found'
expandDirection ExpandDirection Dropdown expand direction ExpandDirection.auto
SearchFieldDecoration
Parameter Type Description Default
hintText String Search hint text 'Search'
border InputBorder? Search field border OutlineInputBorder(...)
focusedBorder InputBorder? Border when focused OutlineInputBorder(...)
searchIcon Icon Search icon Icon(Icons.search)
textStyle TextStyle? Search input text style null
hintStyle TextStyle? Search hint text style null
fillColor Color? Search field fill color null
filled bool? Whether search field is filled null
cursorColor Color? Cursor color null
showClearIcon bool Show clear button in search true
autofocus bool Auto-focus search on open false
DropdownItemDecoration
Parameter Type Description Default
backgroundColor Color? Item background color null
disabledBackgroundColor Color? Disabled item background color null
selectedBackgroundColor Color? Selected item background color null
selectedTextColor Color? Selected item text color null
textColor Color? Item text color null
disabledTextColor Color? Disabled item text color null
selectedIcon Widget? Selected item trailing icon Icon(Icons.check)
disabledIcon Widget? Disabled item trailing icon null
textStyle TextStyle? Item label text style null
selectedTextStyle TextStyle? Selected item label text style null

Migration from v2.x

See the CHANGELOG for details on breaking changes in v3.0.0.

Key changes:

  • MultiSelectDropDown → MultiDropdown
  • ValueItem → DropdownItem
  • .network() → .future()
  • onOptionsSelected → onSelectionChange

License

MIT License

所属分类

依赖

依赖清单 1 项

源码仓库

使用此插件的项目