Flutter底部搜索栏插件bottom_sheet_search的使用

Bottom Sheet Search 演示

目录

• 简介
• 特性
• 安装
• 开始使用
  • 基本用法
  • 高级定制
• API 参考
• 定制
  • 添加后缀图标
  • 主题与样式
• 示例
• 贡献
• 许可
• 联系

简介

Bottom Sheet Search 是一个功能强大的 Flutter 包，提供高度可定制的底部搜索栏小部件。该小部件受 Arc 浏览器优雅设计的启发，无缝地将搜索功能集成到您的应用界面中，为用户提供直观且高效的搜索体验。

特性

• 可定制的外观：可以调整颜色、文本样式、内边距等以匹配您的应用主题。
• 动态搜索：用户输入查询时实时过滤项目。
• 自动完成支持：根据用户输入提供建议的相关项目，增强搜索体验。
• 语义化访问：通过语义标签改善无障碍性，提升用户体验。
• 灵活布局：通过调整边距和内边距轻松集成到现有 UI 中。
• 后缀图标：在搜索栏中添加自定义图标以实现额外功能，如筛选或语音搜索。
• 平滑动画：交互时享受流畅的过渡和动画效果。

安装

要在您的 Flutter 项目中添加 bottom_sheet_search，请将其包含在您的 pubspec.yaml 文件中：

dependencies:
  bottom_sheet_search: ^1.0.0

然后运行以下命令以获取包：

flutter pub get

开始使用

基本用法

以下是一个 BottomSheetSearchWidget 的基本实现示例：

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:bottom_sheet_search/bottom_sheet_search.dart';

/// 使用 Consumer 实现 BottomSheetSearchWidget 示例。
///
/// 展示如何在 Flutter 应用程序中集成 BottomSheetSearchWidget，并利用 Provider 包进行状态管理。
class UserSearchPage extends StatelessWidget {
  /// 创建一个 UserSearchPage 小部件。
  const UserSearchPage({super.key});

  /// 处理从搜索结果中选择用户的逻辑。
  void _handleUserSelection(BuildContext context, User selectedUser) {
    // 在此处实现您的选择逻辑。
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text('Selected user: ${selectedUser.name}')),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('User Search'),
      ),
      body: Consumer<UserProvider>(
        builder: (context, userProvider, child) {
          return BottomSheetSearchWidget<User>(
            items: userProvider.users,
            searchableText: (user) => user.name,
            onItemSelected: (user) => _handleUserSelection(context, user),
            itemBuilder: (context, user) {
              return ListTile(
                title: Text(user.name),
                subtitle: Text(user.email),
              );
            },
            decoration: const BottomSheetDecoration(
              backgroundColor: Colors.white,
              searchBarColor: Colors.grey,
              borderRadius: BorderRadius.only(
                topLeft: Radius.circular(24),
                topRight: Radius.circular(24),
              ),
            ),
            suffixIcons: [
              IconButton(
                icon: const Icon(Icons.filter_list),
                onPressed: () {
                  // 在此处实现筛选功能。
                },
              ),
            ],
            autoCompleteBuilder: (context, suggestion) {
              return ListTile(
                title: Text(suggestion.name),
              );
            },
          );
        },
      ),
    );
  }
}

/// 一个简单的用户模型。
class User {
  /// 用户名称。
  final String name;

  /// 用户电子邮件。
  final String email;

  /// 创建一个 User 实例。
  User({required this.name, required this.email});
}

/// 用于管理用户数据的 Provider。
class UserProvider with ChangeNotifier {
  /// 用户列表。
  final List<User> _users = [
    User(name: 'Alice', email: 'alice@example.com'),
    User(name: 'Bob', email: 'bob@example.com'),
    // 添加更多用户。
  ];

  /// 公开用户列表。
  List<User> get users => _users;

  // 如果需要，添加修改用户列表的方法。
}

高级定制

通过自定义装饰和添加更多功能来增强 BottomSheetSearchWidget：

import 'package:flutter/material.dart';
import 'package:bottom_sheet_search/bottom_sheet_search.dart';

/// 为 BottomSheetSearchWidget 自定义装饰。
const BottomSheetDecoration customDecoration = BottomSheetDecoration(
  backgroundColor: Colors.blueAccent,
  searchBarColor: Colors.white,
  borderRadius: BorderRadius.only(
    topLeft: Radius.circular(16),
    topRight: Radius.circular(16),
  ),
  borderColor: Colors.blue,
  borderWidth: 2.0,
  contentPadding: EdgeInsets.all(20),
  searchBarPadding: EdgeInsets.symmetric(horizontal: 20, vertical: 10),
  cursorColor: Colors.blueAccent,
  searchTextStyle: TextStyle(color: Colors.black, fontSize: 18),
  hintTextStyle: TextStyle(color: Colors.grey, fontSize: 16),
);

API 参考

BottomSheetSearchWidget<T>

一个通用的小部件，显示具有集成搜索功能的底部栏。

参数

• items (List<T>): 要显示和搜索的项目列表。
• searchableText (String Function(T)): 返回每个项目中要搜索的文本的函数。
• onItemSelected (void Function(T)): 项目被选中时触发的回调。
• itemBuilder (Widget Function(BuildContext, T)): 列表中每个项目的构建函数。
• decoration (BottomSheetDecoration): 自定义底部栏和搜索栏的外观。
• suffixIcons (List<Widget>): 显示在搜索栏中的后缀图标列表。
• autoCompleteBuilder (Widget Function(BuildContext, T)): 自动完成建议的构建函数。

BottomSheetDecoration

定义 BottomSheetSearchWidget 的视觉样式。

属性

• backgroundColor (Color): 底部栏的背景色。
• searchBarColor (Color): 搜索栏的背景色。
• borderRadius (BorderRadius): 底部栏的边框半径。
• borderColor (Color): 底部栏周围边框的颜色。
• borderWidth (double): 底部栏周围边框的宽度。
• contentPadding (EdgeInsets): 底部栏内容区域内的填充。
• searchBarPadding (EdgeInsets): 搜索栏内的填充。
• cursorColor (Color): 搜索栏中光标的颜色。
• searchTextStyle (TextStyle): 搜索输入的文本样式。
• hintTextStyle (TextStyle): 搜索栏中提示文本的样式。

定制

添加后缀图标

通过向搜索栏添加自定义后缀图标来增强搜索栏的功能。

import 'package:flutter/material.dart';
import 'package:bottom_sheet_search/bottom_sheet_search.dart';

/// 向搜索栏添加后缀图标的示例。
List<Widget> suffixIcons = [
  IconButton(
    icon: const Icon(Icons.filter_list),
    onPressed: () {
      // 在此处实现筛选功能。
    },
  ),
  IconButton(
    icon: const Icon(Icons.mic),
    onPressed: () {
      // 在此处实现语音搜索功能。
    },
  ),
];

主题与样式

通过自定义底部栏和搜索栏的外观来匹配您的应用主题。

import 'package:flutter/material.dart';
import 'package:bottom_sheet_search/bottom_sheet_search.dart';

/// 为 BottomSheetSearchWidget 自定义主题。
const BottomSheetDecoration themedDecoration = BottomSheetDecoration(
  backgroundColor: Colors.deepPurple,
  searchBarColor: Colors.white,
  borderRadius: BorderRadius.only(
    topLeft: Radius.circular(20),
    topRight: Radius.circular(20),
  ),
  borderColor: Colors.deepPurpleAccent,
  borderWidth: 1.5,
  contentPadding: EdgeInsets.all(16),
  searchBarPadding: EdgeInsets.symmetric(horizontal: 16, vertical: 8),
  cursorColor: Colors.deepPurple,
  searchTextStyle: TextStyle(color: Colors.black87, fontSize: 16),
  hintTextStyle: TextStyle(color: Colors.black54, fontSize: 14),
);

示例

要查看 BottomSheetSearchWidget 的实际效果，请运行示例提供的 main.dart 文件：

flutter run example/lib/main.dart

确保通过导航到 example 目录并运行以下命令来获取必要的依赖项：

flutter pub get

贡献

欢迎贡献！要为 Bottom Sheet Search 做出贡献，请遵循以下步骤：

1. 克隆您的分支：点击存储库页面右上角的“Fork”按钮。
2. 克隆您的分支：

   git clone https://github.com/hberkayozdemir/bottom_sheet_search.git
   

3. 创建新分支 以实现您的功能或修复错误：

   git checkout -b feature/your-feature-name
   

4. 做出更改：实现您的功能或修复错误。
5. 提交您的更改，并附带清晰且描述性的消息：

   git commit -m "添加功能 X"
   

6. 推送至您的分支：

   git push origin feature/your-feature-name