Flutter智能选择插件smart_select的使用

Flutter智能选择插件smart_select的使用

重要信息

大家好，

很抱歉地宣布，我将不再维护 smart_select 包。这是一个很棒的项目，但现在已经变得难以维护。

取而代之的是，我发布了一个新包叫做 choice。这个包结合了 smart_select 和 chips_choice 的功能，并提供了更干净、更灵活且可组合的 API 来创建带有单选或多选的内联或提示选择小部件。

希望大家能试试 choice。我相信你会觉得它是一个很好的替代品。

感谢你的理解。

smart_select 简介

SmartSelect 可以让你轻松地将普通的表单选择或下拉菜单转换为动态页面、弹出对话框或滑动底部面板，具有各种输入选项如单选按钮、复选框、开关、芯片甚至自定义输入。支持单选和多选。灵感来自于 Framework7 的 Smart Select 组件。

版本 4.x.x 中的新特性

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

待办事项

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

从 4.0.0 到 4.2.0 的迁移

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

从 3.0.x 到 4.0.0 的迁移

• 参数 options 已被移除，改为使用 choiceItems。
• 简化类名和枚举。
• 参数 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 = '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: options,
    onChange: (state) => setState(() => value = state.value),
  );
}

选择项

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

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

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

choiceItems 可以直接输入，如下所示，更多关于 S2Choice 的信息可以在 API 参考文档 中找到。

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,

  // 是否使用 `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(
      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] 为 null 时显示的 [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,
      ),
    );
  },
);

许可证

版权所有 © 2020 Irfan Vigma Taufik

特此免费授予任何获得软件副本的人，允许其不受限制地使用、复制、修改、合并、发布、分发、再许可和/或出售该软件副本，并允许他人同样这样做，但须遵守以下条件：

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

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