搜尋套件、儲存庫與 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 項

原始碼儲存庫

使用此套件的專案