sc_flutter_component_library 0.0.5

A Flutter component library with rich text input widgets supporting multiple input types and automatic format validation.

SC Flutter Component Library

一个通用的 Flutter 组件库，提供了丰富实用的 UI 组件，支持多种输入类型、搜索功能和自动格式验证。专为提高开发效率和用户体验而设计。

项目概述

本组件库专注于提供高质量、易用的通用组件，特别适用于需要数据录入、搜索和表单处理的应用场景。所有组件都经过精心设计，确保在不同平台上都能提供一致的用户体验。

组件简介

🔤 TextFieldWidget

功能丰富的文本输入框组件，支持多种输入类型（文本、重量、单价、金额、数量）和自动格式验证。

快速使用：

TextFieldWidget(
  labelText: '金额',
  inputType: TextFieldInputType.amount,
  onChanged: (value) => print('输入: $value'),
)

🗑️ QuickFilterTextFieldWithClearWidget

继承自 TextFieldWidget 的增强版本，添加了智能清除按钮功能，提供更好的用户交互体验。

快速使用：

QuickFilterTextFieldWithClearWidget(
  labelText: '搜索',
  hintText: '请输入关键词',
  onClear: () => print('已清除'),
)

🔍 FilterSearchWidget

通用的搜索组件，支持泛型数据类型，提供实时搜索、自定义过滤和结果显示功能。

快速使用：

FilterSearchWidget<String>(
  config: FilterSearchConfig<String>(
    itemBuilder: (context, item, isSelected) => ListTile(title: Text(item)),
  ),
  items: ['苹果', '香蕉', '橙子'],
  onSelectionChanged: (item) => print('选中: $item'),
)

📅 DateRangeSearchWidget

专业的日期范围选择组件，支持单选和范围选择模式，提供快捷选择和精度控制功能。

快速使用：

DateRangeSearchWidget(
  hintText: '请选择日期范围',
  onDateRangeChanged: (startDate, endDate) {
    print('选择的日期范围: $startDate - $endDate');
  },
)

平台支持

本组件库支持所有Flutter平台：

平台	支持状态	说明
📱 Android	✅ 完全支持	支持所有Android版本
🍎 iOS	✅ 完全支持	支持iOS 9.0+
🐧 Linux	✅ 完全支持	支持现代Linux发行版
🍎 macOS	✅ 完全支持	支持macOS 10.11+
🪟 Windows	✅ 完全支持	支持Windows 7+
🌐 Web	✅ 完全支持	支持现代浏览器

使用场景

• 📱 移动应用: Android和iOS原生体验
• 💻 桌面应用: Windows、macOS、Linux桌面应用
• 🌐 Web应用: 响应式Web界面
• 🔄 跨平台: 一套代码，多端运行

详细介绍

TextFieldWidget

功能丰富的文本输入框组件，支持多种输入类型和自动格式验证。

主要特性：

• 🎯 多种输入类型支持（文本、重量、单价、金额、数量）
• ✅ 自动输入格式验证和限制
• 🎨 可自定义样式和尺寸
• 🔧 支持前缀图标和后缀图标
• 📱 焦点管理和回调事件
• 🔄 启用/禁用状态控制

输入类型：

• text: 普通文本输入
• weight: 重量输入（小数点后3位）
• price: 单价输入（小数点后4位）
• amount: 金额输入（小数点后2位）
• quantity: 数量输入（仅整数）

FilterSearchWidget

通用的搜索组件，提供实时搜索功能和可配置的过滤选项。

主要特性：

• 🔍 实时搜索功能
• 🎯 泛型支持，适用于任何数据类型
• ⚙️ 可配置的搜索行为（延迟、最小长度等）
• 🎨 自定义结果显示和过滤逻辑
• 📱 选择状态管理
• ⚡ 防抖搜索，避免频繁调用

DateRangeSearchWidget

专业的日期范围选择组件，支持单选和范围选择模式，提供快捷选择和精度控制功能。

主要特性：

• 📅 支持单选和范围选择模式
• ⚡ 提供快捷日期选择（今天、昨天、本周、本月等）
• 🎯 精度控制（精确到日或分钟）
• 🎨 可自定义样式和格式
• 📱 移动端友好的交互体验
• 🔧 灵活的配置选项

QuickFilterTextFieldWithClearWidget

继承自 TextFieldWidget 的增强版本，添加了清除按钮功能。

额外特性：

• 🗑️ 智能清除按钮（有内容时显示）
• 🔄 清除按钮回调事件
• ⚡ 一键清空功能

快速开始

安装

在你的 pubspec.yaml 文件中添加依赖：

dependencies:
  sc_flutter_component_library: ^0.0.4

导入

import 'package:sc_flutter_component_library/sc_flutter_component_library.dart';

基础使用示例

// 1. 文本输入框 - 支持多种输入类型
TextFieldWidget(
  labelText: '用户名',
  hintText: '请输入用户名',
  inputType: TextFieldInputType.text,
  onChanged: (value) => print('输入值: $value'),
)

// 2. 金额输入框（限制小数点后2位）
TextFieldWidget(
  labelText: '金额 (元)',
  inputType: TextFieldInputType.amount,
  prefixIcon: Icon(Icons.attach_money),
)

// 3. 带清除按钮的搜索框
QuickFilterTextFieldWithClearWidget(
  labelText: '搜索',
  hintText: '请输入关键词',
  onClear: () => print('清除按钮被点击'),
)

// 4. 通用搜索组件
FilterSearchWidget<String>(
  config: FilterSearchConfig<String>(
    itemBuilder: (context, item, isSelected) {
      return ListTile(
        title: Text(item),
        selected: isSelected,
      );
    },
    hintText: '搜索项目...',
  ),
  items: ['苹果', '香蕉', '橙子', '葡萄'],
  onSelectionChanged: (selectedItem) {
    print('选中项目: $selectedItem');
  },
)

// 5. 日期范围选择组件
DateRangeSearchWidget(
  hintText: '请选择日期范围',
  onDateRangeChanged: (startDate, endDate) {
    print('选择的日期范围: $startDate - $endDate');
  },
)

高级使用

class MyForm extends StatefulWidget {
  @override
  _MyFormState createState() => _MyFormState();
}

class _MyFormState extends State<MyForm> {
  final TextEditingController _controller = TextEditingController();
  final FocusNode _focusNode = FocusNode();

  @override
  void dispose() {
    _controller.dispose();
    _focusNode.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return TextFieldWidget(
      controller: _controller,
      focusNode: _focusNode,
      labelText: '金额',
      inputType: TextFieldInputType.amount,
      width: 300,
      height: 40,
      enabled: true,
      prefixIcon: Icon(Icons.attach_money),
      onChanged: (value) {
        // 处理值变化
        setState(() {
          // 更新UI
        });
      },
      onSubmitted: (value) {
        // 处理提交事件
        print('提交的值: $value');
      },
    );
  }
}

示例项目

项目包含了完整的示例应用，展示了所有组件的功能和用法。

运行示例

# 进入示例目录
cd example

# 获取依赖
flutter pub get

# 运行示例
flutter run

示例功能

示例应用包含以下演示：

1. 基础文本输入 - 普通文本输入演示
2. 重量输入 - 小数点后3位限制演示
3. 单价输入 - 小数点后4位限制演示
4. 金额输入 - 小数点后2位限制演示
5. 数量输入 - 整数输入限制演示
6. 清除功能 - 带清除按钮的输入框演示
7. 搜索功能 - 实时搜索和过滤演示
8. 日期选择 - 日期范围选择和快捷选择演示
9. 多行输入 - 多行文本输入演示
10. 交互功能 - 状态监控、批量操作等

API 文档

TextFieldWidget

参数	类型	默认值	说明
labelText	String	""	输入框标签文本
hintText	String?	null	提示文本
controller	TextEditingController?	null	文本控制器
onChanged	ValueChanged	null	输入值变化回调
onSubmitted	ValueChanged	null	输入完成回调
width	double?	null	组件宽度
height	double?	32	组件高度
enabled	bool	true	是否启用
inputType	TextFieldInputType	text	输入类型
maxLines	int?	1	最大行数
prefixIcon	Widget?	null	前缀图标
suffixIcon	Widget?	null	后缀图标
focusNode	FocusNode?	null	焦点节点

QuickFilterTextFieldWithClearWidget

继承 TextFieldWidget 的所有参数，额外增加：

参数	类型	默认值	说明
onClear	VoidCallback?	null	清除按钮回调
showClearButton	bool	true	是否显示清除按钮

TextFieldInputType 枚举

• text: 普通文本输入
• weight: 重量输入（小数点后3位）
• price: 单价输入（小数点后4位）
• amount: 金额输入（小数点后2位）
• quantity: 数量输入（仅整数）

项目结构

sc_flutter_component_library/
├── lib/
│   ├── src/
│   │   └── text_field_widget.dart    # 主要组件实现
│   └── sc_flutter_component_library.dart  # 库导出文件
├── example/                          # 示例项目
│   ├── lib/
│   │   └── main.dart                # 示例应用
│   ├── pubspec.yaml                 # 示例项目配置
│   └── README.md                    # 示例说明
├── pubspec.yaml                      # 项目配置
├── README.md                         # 本文件
└── CHANGELOG.md                      # 更新日志

开发指南

添加新组件

1. 在 lib/src/ 目录下创建新的组件文件
2. 在 lib/sc_flutter_component_library.dart 中导出新组件
3. 在示例项目中添加使用演示
4. 更新文档和测试

代码规范

• 遵循 Flutter/Dart 官方代码规范
• 使用有意义的变量和函数命名
• 添加适当的注释和文档
• 确保资源正确释放（dispose）

测试

# 运行测试
flutter test

# 运行测试覆盖率
flutter test --coverage

版本历史

查看 CHANGELOG.md 了解详细的版本更新信息。

许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。

贡献步骤

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

支持

如果你觉得这个项目有用，请给它一个 ⭐️！

如有问题或建议，请通过 Issue 联系我们。