Flutter高级选择组件插件flutter_awesome_select_nw的使用

Flutter高级选择组件插件flutter_awesome_select_nw的使用

特点

• 可以通过样式配置或小部件构建器自定义每个部分（头部、尾部、搜索栏、确认按钮、搜索栏切换）
• 在确认前进行验证
• 输入时自动搜索
• 搜索时处理重音符号
• 高亮搜索结果
• 芯片小部件
• 网格选择布局
• 水平或垂直选择列表滚动方向
• 简化类名和枚举
• 配置支持 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,
    );
  },
);

预览

	单选	多选
模态类型
芯片小部件
开关小部件	无
自定义瓷砖
模态过滤器
模态确认
模态验证
模态选择器
模态形状
选择项
分组选择
选择构建器
下载APK

特点

• 可以选择单个或多个选项
• 打开选择模态对话框可以全屏、底部抽屉或弹出对话框
• 各种选择输入（单选按钮、复选框、开关、芯片或自定义小部件）
• 各种选择布局（列表、换行、网格）
• 使用简单支持分组选择和粘性头部
• 可搜索的选择并高亮显示结果
• 可禁用或隐藏选择
• 可定制触发/瓷砖小部件
• 可定制模态风格
• 可定制模态头部风格
• 可定制模态尾部
• 可定制选择风格
• 从任何 List 构建选择项目
• 简单加载异步选择项目
• 更多功能

使用

要查看完整的使用示例，请参阅示例。

要了解有关 smart_select 使用的类和其他参考信息，请参阅API 参考。

单选

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

  // 当值为空时显示的文本
  String placeholder = '选择一个',

  // 单选小部件的当前值
  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: '框架',
    value: value,
    choiceItems: options,
    onChange: (state) => setState(() => value = state.value)
  );
}

多选

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

  // 当值为空时显示的文本
  String placeholder = '选择一个',

  // 单选小部件的当前值
  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: '框架',
    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/smart_select/latest/smart_select/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': '星期一' },
  { 'value': 'tue', 'title': '星期二' },
  { 'value': 'wed', 'title': '星期三' },
  { 'value': 'thu', 'title': '星期四' },
  { 'value': 'fri', 'title': '星期五' },
  { 'value': 'sat', 'title': '星期六' },
  { 'value': 'sun', 'title': '星期日' },
];

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,

  // 头部是否使用 automaticallyImplyLeading
  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,
      ),
    );
  },
);

许可证

版权所有 © 2021 Akbar Pulatov

特此免费授予任何获得本软件副本及相关文档文件（“软件”）的人，无需限制地使用、复制、修改、合并、发布、分发、再许可和/或出售软件的副本的权利，以及允许他人以上述方式使用软件的权利，但受以下条件约束：

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

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