Flutter高级选择器插件awesome_select_plus的使用

Flutter 高级选择器插件 awesome_select_plus 的使用

关于

awesome_select_plus 插件允许你轻松地将普通的表单选择或下拉菜单转换为动态页面、弹出对话框或滑动底部面板，并且支持多种输入方式，如单选按钮、复选框、开关、芯片或自定义输入。它支持单选和多选。灵感来自 Framework7 的 Smart Select 组件。

特性

• 可以定制模态窗口的每个部分（头部、尾部、搜索栏、确认按钮、搜索栏切换）使用样式配置或小部件构建器。
• 在确认前进行验证。
• 键入时自动搜索。
• 搜索时处理重音符号。
• 高亮搜索结果。
• 芯片瓷砖小部件。
• 网格选择布局。
• 横向或纵向的选择列表滚动方向。
• 简化类名和枚举。
• 配置支持 copyWith 和 merge。
• 使用 StatefulWidget 作为状态管理。
• 提供简单的快捷方式来定义配置。
• 对其他包有软依赖。

待办事项

• 支持从右到左参数，目前可以通过小部件构建器实现。
• 内部处理异步选择项加载器。
• 自定义搜索处理器。
• 选择项分页（下拉刷新和加载更多）。
• 添加更多测试。

从 4.0.0 迁移到 4.2.0

• modalValidation 函数现在应该返回一个 String 来表示更改值无效，返回 null 或空字符串表示更改值有效。
• 要显示带有芯片的瓦片，请使用参数 S2Tile.body 和 S2TileChips，而不是 S2ChipsTile。

从 3.0.x 迁移到 4.0.0

• 参数 options 已移除，改用 choiceItems。
• 简化类名和枚举：
  • SmartSelectTile 更改为 S2Tile
  • SmartSelectOption 更改为 S2Choice
  • SmartSelectChoiceConfig 更改为 S2ChoiceConfig
  • SmartSelectChoiceStyle 更改为 S2ChoiceStyle
  • SmartSelectChoiceType 更改为 S2ChoiceType
  • SmartSelectModalConfig 更改为 S2ModalConfig
  • SmartSelectModalStyle 更改为 S2ModalStyle
  • SmartSelectModalHeaderStyle 更改为 S2ModalHeaderStyle
  • SmartSelectModalType 更改为 S2ModalType
• 参数 builder 现在是一组构建器 (S2SingleBuilder 或 S2MultiBuilder)，应使用 tileBuilder 创建触发瓦片小部件。
• 参数 dense, enabled, isLoading, isTwoLine, leading, loadingText, padding, selected, trailing 已从 SmartSelect 类中移除，应使用 builder.tile 或 tileBuilder 并返回 S2Tile 小部件，它具有所有这些参数。
• 参数 onChange 现在返回 S2SingleState state 或 S2MultiState state 而不是 T value 或 List<T> value。
• 参数 choiceConfig.useWrap 已移除，应使用 choiceConfig.layout = S2ChoiceLayout.wrap。
• 参数 choiceConfig.builder 移至 builder.choice 或 choiceBuilder。
• 参数 choiceConfig.titleBuilder 移至 builder.choiceTitle 或 choiceTitleBuilder。
• 参数 choiceConfig.subtitleBuilder 移至 builder.choiceSubtitle 或 choiceSubtitleBuilder。
• 参数 choiceConfig.secondaryBuilder 移至 builder.choiceSecondary 或 choiceSecondaryBuilder。
• 参数 choiceConfig.dividerBuilder 移至 builder.choiceDivider 或 choiceDividerBuilder。
• 参数 choiceConfig.emptyBuilder 移至 builder.choiceEmpty 或 choiceEmptyBuilder。
• 参数 choiceConfig.glowingOverscrollIndicatorColor 已移除，应使用 choiceConfig.overscrollColor。
• 参数 choiceConfig.spacing 和 choiceConfig.runSpacing 移至 choiceConfig.style.spacing 和 choiceConfig.style.runSpacing。
• 参数 choiceConfig.useCheckmark 移至 choiceConfig.style.showCheckmark。
• 参数 choiceConfig.padding 移至 choiceConfig.style.wrapperPadding。
• 默认情况下，不使用粘性标题的分组选择现在应使用 groupBuilder，如下所示：

dependencies:
  sticky_headers: "^0.1.8"

import 'package:sticky_headers/sticky_headers.dart';

SmartSelect<T>.single/multiple(
  ...,
  ...,
  choiceGroupBuilder: (context, header, choices) {
    return StickyHeader(
      header: header,
      content: choices,
    );
  },
);

功能

• 单选或多选
• 打开选择项模态窗口全屏、底部面板或弹出对话框
• 各种选择输入（单选按钮、复选框、开关、芯片或自定义小部件）
• 各种选择布局（列表、包装、网格）
• 分组选择并轻松支持粘性标题
• 可搜索的选择项并高亮显示结果
• 禁用或隐藏选择项
• 可定制的触发/瓦片小部件
• 可定制的模态样式
• 可定制的模态头部样式
• 可定制的模态尾部
• 可定制的选择项样式
• 从任何 List 构建选择项
• 简单加载异步选择项
• 等等

使用

完整的使用方法，请参见示例。

有关 awesome_select_plus 中使用的类和其他引用的更多信息，请参阅API 参考。

单选

// 单选可用配置
SmartSelect<T>.single({
  // 小部件的主要内容。
  // 用于触发小部件和头部选项
  String title,

  // 值为空时显示的文本
  String placeholder = 'Select one',

  // 单选小部件的当前值。
  required T value,

  // 当单选值更改时调用
  required ValueChanged<S2SingleState<T>> onChange,

  // 选择项列表
  List<S2Choice<T>> choiceItems,

  // 其他可用配置
  ...,
  ...,
})

// 简单用法

String value = 'flutter';
List<S2Choice<String>> options = [
  S2Choice<String>(value: 'ion', title: 'Ionic'),
  S2Choice<String>(value: 'flu', title: 'Flutter'),
  S2Choice<String>(value: 'rea', title: 'React Native'),
];

@override
Widget build(BuildContext context) {
  return SmartSelect<String>.single(
    title: 'Frameworks',
    value: value,
    choiceItems: options,
    onChange: (state) => setState(() => value = state.value)
  );
}

多选

// 多选可用配置
SmartSelect<T>.multiple({
  // 小部件的主要内容。
  // 用于触发小部件和头部选项
  String title,

  // 值为空时显示的文本
  String placeholder = 'Select one',

  // 多选小部件的当前值。
  required List<T> value,

  // 当多选值更改时调用
  required ValueChanged<S2MultiState<T>> onChange,

  // 选择项列表
  List<S2Choice<T>> choiceItems,

  // 其他可用配置
  ...,
  ...,
})

// 简单用法

List<int> value = [2];
List<S2Choice<int>> frameworks = [
  S2Choice<int>(value: 1, title: 'Ionic'),
  S2Choice<int>(value: 2, title: 'Flutter'),
  S2Choice<int>(value: 3, title: 'React Native'),
];

@override
Widget build(BuildContext context) {
  return SmartSelect<int>.multiple(
    title: 'Frameworks',
    value: value,
    choiceItems: frameworks,
    onChange: (state) => setState(() => value = state.value),
  );
}

选择项

// 配置
SmartSelect<T>.[single|multiple]({
  // 其他配置
  ...,
  ...,

  // 选择项列表
  List<S2Choice<T>> choiceItems,

  // 其他配置
  ...,
  ...,
});

// `choiceItems` 可以直接输入，如下所示。关于 `S2Choice` 的更多信息可以在[API 参考](https://pub.dev/documentation/awesome_select_plus/latest/awesome_select_plus/S2Choice-class.html)中找到。

SmartSelect<T>.[single|multiple](
  ...,
  ...,
  choiceItems: <S2Choice<T>>[
    S2Choice<T>(value: 1, title: 'Ionic'),
    S2Choice<T>(value: 2, title: 'Flutter'),
    S2Choice<T>(value: 3, title: 'React Native'),
  ],
);

// `choiceItems` 也可以从任何列表创建，如下所示

List<Map<String, String>> days = [
  { 'value': 'mon', 'title': 'Monday' },
  { 'value': 'tue', 'title': 'Tuesday' },
  { 'value': 'wed', 'title': 'Wednesday' },
  { 'value': 'thu', 'title': 'Thursday' },
  { 'value': 'fri', 'title': 'Friday' },
  { 'value': 'sat', 'title': 'Saturday' },
  { 'value': 'sun', 'title': 'Sunday' },
];

SmartSelect<String>.[single|multiple](
  ...,
  ...,
  choiceItems: S2Choice.listFrom<String, Map<String, String>>(
    source: days,
    value: (index, item) => item['value'],
    title: (index, item) => item['title'],
  ),
);

异步加载选择项

请参阅示例。

模态配置

更多关于 S2ModalConfig 的信息可以在API 参考中找到。

// 可用配置
SmartSelect<T>.[single|multiple]({
  // 其他配置
  ...,
  ...,

  // 单选小部件的模态验证
  ValidationCallback<T> modalValidation,

  // 模态配置
  S2ModalConfig modalConfig,

  // 配置模态样式
  // 快捷方式到 [modalConfig.style]
  S2ModalStyle modalStyle,

  // 配置模态头部样式
  // 快捷方式到 [modalConfig.headerStyle]
  S2ModalHeaderStyle modalHeaderStyle,

  // 显示选择项的模态类型
  // 快捷方式到 [modalConfig.type]
  S2ModalType modalType,

  // 是否使用与触发小部件标题不同的标题
  // 快捷方式到 [modalConfig.title]
  String modalTitle,

  // 选项列表是否需要确认
  // 返回更改的值
  // 快捷方式到 [modalConfig.useConfirm]
  bool modalConfirm,

  // 选项列表模态是否使用头部
  // 快捷方式到 [modalConfig.useHeader]
  bool modalHeader,

  // 选项列表是否可过滤
  // 快捷方式到 [modalConfig.useFilter]
  bool modalFilter,

  // 过滤器是否为自动完成还是需要确认
  // 快捷方式到 [modalConfig.filterAuto]
  bool modalFilterAuto,

  // 自定义搜索栏提示
  // 快捷方式到 [modalConfig.filterHint]
  String modalFilterHint,

  // 其他配置
  ...,
  ...,
});

模态类型

默认情况下，SmartSelect 将选择项模态窗口打开为全屏。你可以通过更改以下值来改变它：

// 可用选项
enum S2ModalType {
  // 全屏打开
  fullPage,

  // 弹出对话框打开
  popupDialog,

  // 滑动底部面板打开
  bottomSheet,
}

模态样式

// 可用选项配置模态样式
S2ModalStyle({
  // 模态边框形状
  // 用于弹出对话框和底部面板
  ShapeBorder shape,

  // 模态提升
  // 用于弹出对话框和底部面板
  double elevation,

  // 模态背景色
  Color backgroundColor,

  // 模态剪裁行为
  Clip clipBehavior,
})

模态头部样式

// 可用选项配置模态头部样式
S2ModalHeaderStyle({
  // 头部边框形状
  ShapeBorder shape,

  // 头部提升
  double elevation,

  // 头部背景色
  Color backgroundColor,

  // 头部亮度
  Brightness brightness,

  // 是否将头部标题居中
  bool centerTitle,

  // 是否使用自动推断引导
  bool useLeading,

  // 头部文本样式
  // 用于标题和搜索字段
  TextStyle textStyle,

  // 头部图标主题
  IconThemeData iconTheme,

  // 头部动作图标主题
  IconThemeData actionsIconTheme,
})

选择项配置

更多关于 S2ChoiceConfig 的信息可以在API 参考中找到。

// 可用选项配置选择项
SmartSelect<T>.[single|multiple]({
  // 其他配置
  ...,
  ...,

  // 选择项配置
  S2ChoiceConfig choiceConfig,

  // 配置选择项样式
  // 快捷方式到 [choiceConfig.style]
  S2ChoiceStyle choiceStyle,

  // 配置选择项分组头部样式
  // 快捷方式到 [choiceConfig.headerStyle]
  S2ChoiceHeaderStyle choiceHeaderStyle,

  // 选择项小部件类型
  // 快捷方式到 [choiceConfig.type]
  S2ChoiceType choiceType,

  // 选择项布局以显示项目
  // 快捷方式到 [choiceConfig.layout]
  S2ChoiceLayout choiceLayout,

  // 选择项列表滚动方向
  // 目前仅支持当
  // [layout] 是 [S2ChoiceLayout.wrap] 时
  // 快捷方式到 [choiceConfig.direction]
  Axis choiceDirection,

  // 选择项列表是否分组
  // 快捷方式到 [choiceConfig.isGrouped]
  bool choiceGrouped,

  // 选择项列表是否使用分割线
  // 快捷方式到 [choiceConfig.useDivider]
  bool choiceDivider,

  // 对于网格选择布局
  // 快捷方式到 [choiceConfig.gridDelegate]
  SliverGridDelegate choiceGrid,

  // 其他配置
  ...,
  ...,
});

选择项类型

默认情况下，SmartSelect 将使用 radios 用于单选，checkboxes 用于多选，但可以更改为此值：

// 选择项输入类型
enum S2ChoiceType {
  // 使用单选小部件
  // 用于单选
  radios,

  // 使用复选框小部件
  // 用于多选
  checkboxes,

  // 使用开关小部件
  // 用于多选
  switches,

  // 使用芯片小部件
  // 用于单选和多选
  chips,
}

选择项布局

默认情况下，SmartSelect 将使用 list，但可以更改为此值：

// 选择项布局
enum S2ChoiceLayout {
  // 使用列表视图小部件
  list,

  // 使用包装视图小部件
  wrap,

  // 使用网格视图小部件
  grid,
}

选择项样式

// 可用选项配置选择项样式
S2ChoiceStyle({
  // 在主轴上放置子元素之间的空间量。
  // 当使用 [SmartSelectChoiceType.chips] 或 [useWrap] 为 [true] 时
  double spacing,

  // 在交叉轴上放置运行之间的空间量。
  // 当使用 [SmartSelectChoiceType.chips] 或 [useWrap] 为 [true] 时
  double runSpacing,

  // 选择项包装器填充
  EdgeInsetsGeometry wrapperPadding,

  // 选择项填充
  EdgeInsetsGeometry padding,

  // 选择项标题样式
  TextStyle titleStyle,

  // 选择项副标题样式
  TextStyle subtitleStyle,

  // 芯片是否使用检查标记
  bool showCheckmark,

  // 位置控件在使用
  // [ListTile] 与标签相邻放置控件的位置。
  S2ChoiceControl control,

  // 高亮颜色
  Color highlightColor,

  // 选中选择项的主色
  Color activeColor,

  // 未选中选择项的主色
  Color color,

  // 选中选择项的次色
  Color activeAccentColor,

  // 未选中选择项的次色
  Color accentColor,

  // 选中芯片的亮度
  Brightness activeBrightness,

  // 未选中芯片的亮度
  Brightness brightness,

  // 选中芯片边框的不透明度
  // 仅在 [activeBrightness] 为 [Brightness.light] 时生效
  double activeBorderOpacity,

  // 未选中芯片边框的不透明度
  // 仅在 [brightness] 为 [Brightness.light] 时生效
  double borderOpacity,

  // 形状剪裁行为
  Clip clipBehavior,
})

选择项头部样式

// 可用选项配置选择项分组头部样式
S2ChoiceHeaderStyle({
  // 分组头部背景色
  Color backgroundColor,

  // 高亮颜色
  Color highlightColor,

  // 分组头部文本样式
  TextStyle textStyle,

  // 分组头部填充
  EdgeInsetsGeometry padding,

  // 分组头部高度
  double height,
})

构建器小部件

单选构建器

// 可用构建器配置
// 用于单选
SmartSelect<T>.single({
  // 其他配置
  ...,
  ...,

  // 单选小部件构建器集合
  S2SingleBuilder<T> builder,

  // 自定义瓦片小部件构建器
  // 快捷方式到 [builder.tile]
  S2WidgetBuilder<S2SingleState<T>> tileBuilder,

  // 自定义模态小部件构建器
  // 快捷方式到 [builder.modal]
  S2WidgetBuilder<S2SingleState<T>> modalBuilder,

  // 自定义模态头部小部件构建器
  // 快捷方式到 [builder.modalHeader]
  S2WidgetBuilder<S2SingleState<T>> modalHeaderBuilder,

  // 自定义模态操作小部件构建器
  // 快捷方式到 [builder.modalActions]
  S2ListWidgetBuilder<S2SingleState<T>> modalActionsBuilder,

  // 自定义模态确认操作小部件构建器
  // 快捷方式到 [builder.modalConfirm]
  S2WidgetBuilder<S2SingleState<T>> modalConfirmBuilder,

  // 自定义分隔符小部件构建器
  // 快捷方式到 [builder.modalDivider]
  S2WidgetBuilder<S2SingleState<T>> modalDividerBuilder,

  // 自定义模态尾部小部件构建器
  // 快捷方式到 [builder.modalFooter]
  S2WidgetBuilder<S2SingleState<T>> modalFooterBuilder,

  // 其他配置
  ...,
  ...,
});

多选构建器

// 可用构建器配置
// 用于多选
SmartSelect<T>.multiple({
  // 其他配置
  ...,
  ...,

  // 多选小部件构建器集合
  S2MultiBuilder<T> builder,

  // 自定义瓦片小部件构建器
  // 快捷方式到 [builder.tile]
  S2WidgetBuilder<S2MultiState<T>> tileBuilder,

  // 自定义模态小部件构建器
  // 快捷方式到 [builder.modal]
  S2WidgetBuilder<S2MultiState<T>> modalBuilder,

  // 自定义模态头部小部件构建器
  // 快捷方式到 [builder.modalHeader]
  S2WidgetBuilder<S2MultiState<T>> modalHeaderBuilder,

  // 自定义模态操作小部件构建器
  // 快捷方式到 [builder.modalActions]
  S2ListWidgetBuilder<S2MultiState<T>> modalActionsBuilder,

  // 自定义模态确认操作小部件构建器
  // 快捷方式到 [builder.modalConfirm]
  S2WidgetBuilder<S2MultiState<T>> modalConfirmBuilder,

  // 自定义分隔符小部件构建器
  // 快捷方式到 [builder.modalDivider]
  S2WidgetBuilder<S2MultiState<T>> modalDividerBuilder,

  // 自定义模态尾部小部件构建器
  // 快捷方式到 [builder.modalFooter]
  S2WidgetBuilder<S2MultiState<T>> modalFooterBuilder,

  // 其他配置
  ...,
  ...,
});

其他构建器

// 其他构建器配置
SmartSelect<T>.[single|multiple]({
  // 其他配置
  ...,
  ...,

  // 模态过滤器小部件构建器
  // 快捷方式到 [builder.modalFilter]
  S2WidgetBuilder<S2Filter> modalFilterBuilder,

  // 模态过滤器切换小部件构建器
  // 快捷方式到 [builder.modalFilterToggle]
  S2WidgetBuilder<S2Filter> modalFilterToggleBuilder,

  // 每个自定义选择项小部件构建器
  // 快捷方式到 [builder.choice]
  S2ChoiceBuilder<T> choiceBuilder,

  // 每个自定义选择项标题小部件构建器
  // 快捷方式到 [builder.choiceTitle]
  S2ChoiceBuilder<T> choiceTitleBuilder,

  // 每个自定义选择项副标题小部件构建器
  // 快捷方式到 [builder.choiceSubtitle]
  S2ChoiceBuilder<T> choiceSubtitleBuilder,

  // 每个自定义选择项次小部件构建器
  // 快捷方式到 [builder.choiceSecondary]
  S2ChoiceBuilder<T> choiceSecondaryBuilder,

  // 自定义选择项之间分隔符小部件构建器
  // 快捷方式到 [builder.choiceDivider]
  IndexedWidgetBuilder choiceDividerBuilder,

  // 自定义空显示小部件构建器
  // 快捷方式到 [builder.choiceEmpty]
  S2WidgetBuilder<String> choiceEmptyBuilder,

  // 自定义选择项分组小部件构建器
  // 快捷方式到 [builder.choiceGroup]
  S2ChoiceGroupBuilder choiceGroupBuilder,

  // 自定义选择项头部分组小部件构建器
  // 快捷方式到 [builder.choiceHeader]
  S2ChoiceHeaderBuilder choiceHeaderBuilder,

  // 其他配置
  ...,
  ...,
});

瓦片小部件

默认瓦片

// 默认瓦片/触发小部件
S2Tile<T>({
  // 选中的选项值。
  String value,

  // 列表瓦片的主要内容。
  Widget title,

  // 在标题之前显示的小部件。
  // 通常是一个 [Icon] 或 [CircleAvatar] 小部件。
  Widget leading,

  // 在标题之后显示的小部件。
  // 通常是一个 [Icon] 小部件。
  Widget trailing,

  // 是否此列表瓦片旨在显示加载状态。
  bool isLoading,

  // 用于显示加载文本的字符串
  String loadingText,

  // 是否此列表瓦片旨在显示两行文本。
  bool isTwoLine,

  // 此列表瓦片是否可交互。
  bool enabled,

  // 如果此瓦片也是 [enabled]，则图标和文本将使用相同的颜色。
  bool selected,

  // 此列表瓦片是否为垂直密集列表的一部分。
  bool dense,

  // 是否显示 [value]
  bool hideValue,

  // 瓦片的内部填充。
  EdgeInsetsGeometry padding,

  // 当用户点击此列表瓦片时调用。
  GestureTapCallback onTap,

  // 在瓦片下方显示的小部件
  // 通常用于显示带 S2TileChips 的芯片
  Widget body,
})

// 使用示例
SmartSelect<T>.single(
  ...,
  ...,
  tileBuilder: (context, state) {
    return S2Tile<dynamic>(
      title: state.titleWidget,
      value: state.valueDisplay,
      onTap: state.showModal,
      isLoading: true,
    );
  },
);

// 使用示例来自状态
SmartSelect<T>.multiple(
  ...,
  ...,
  tileBuilder: (context, state) {
    return S2Tile.fromState(
      state,
      isLoading: true,
    );
  },
);

带芯片的瓦片

// 芯片瓦片/触发小部件
S2TileChips({
  // 选中的选择项值列表。
  int chipLength,

  // 芯片标签项的构建器
  IndexedWidgetBuilder chipLabelBuilder,

  // 芯片头像项的构建器
  IndexedWidgetBuilder chipAvatarBuilder,

  // 芯片项的构建器
  IndexedWidgetBuilder chipBuilder,

  // 当用户删除芯片项时调用。
  ValueChanged<int> chipOnDelete,

  // 芯片颜色
  Color chipColor,

  // 芯片边框不透明度
  double chipBorderOpacity,

  // 芯片亮度
  Brightness chipBrightness,

  // 芯片删除按钮颜色
  Color chipDeleteColor,

  // 芯片删除按钮图标
  Icon chipDeleteIcon,

  // 芯片间距
  double chipSpacing,

  // 芯片运行间距
  double chipRunSpacing,

  // 芯片形状边框
  ShapeBorder chipShape,

  // 在 [values] 为空时显示的 [Widget]
  Widget placeholder,

  // 芯片列表是否可滚动
  bool scrollable,

  // 芯片列表填充
  EdgeInsetsGeometry padding,
})

// 使用示例
SmartSelect<String>.multiple(
  ...,
  ...,
  value: users,
  tileBuilder: (context, state) {
    return S2Tile.fromState(
      state,
      hideValue: true,
      body: S2TileChips(
        chipLength: state.valueObject.length,
        chipLabelBuilder: (context, i) {
          return Text(state.valueObject[i].title);
        },
        chipAvatarBuilder: (context, i) {
          return CircleAvatar(
            backgroundImage: NetworkImage(state.valueObject[i].meta['picture']['thumbnail'])
          );
        },
        chipOnDelete: (i) {
          setState(() => users.remove(state.valueObject[i].value));
        },
        chipColor: Colors.blue,
        chipBrightness: Brightness.dark,
        chipBorderOpacity: .5,
      ),
    );
  },
);

许可证

版权所有 (c) 2021 Akbar Pulatov

特此免费授予，获得本软件副本的任何人无限制地使用本软件及其关联文档文件的权利（“软件”），包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件的副本，并允许向其提供软件的人这样做，受以下条件约束：

上述版权声明和本许可声明必须包含在所有副本或实质性部分中。

软件按“原样”提供，没有任何形式的明示或暗示保证，包括但不限于适销性、适用于特定用途和非侵权的保证。在任何情况下，作者或版权持有人均不对因使用或无法使用软件或软件的其他用途而引起的任何索赔、损害或其他责任负责。