sc_flutter_component_library 0.0.3

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

SC Flutter Component Library

一个自定义的 Flutter 组件库，提供了丰富的文本输入框组件，支持多种输入类型和自动格式验证。

项目概述

本组件库专注于提供高质量、易用的文本输入组件，特别适用于需要数据录入和表单处理的应用场景。

平台支持

本组件库支持所有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

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

主要特性：

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

QuickFilterTextFieldWithClearWidget

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

额外特性：

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

快速开始

安装

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

dependencies:
  sc_flutter_component_library:
    path: path/to/sc_flutter_component_library

导入

import 'package:sc_flutter_component_library/sc_flutter_component_library.dart';

基础使用

// 基础文本输入框
TextFieldWidget(
  labelText: '用户名',
  hintText: '请输入用户名',
  inputType: TextFieldInputType.text,
  onChanged: (value) {
    print('输入值: $value');
  },
)

// 重量输入框（限制小数点后3位）
TextFieldWidget(
  labelText: '重量 (kg)',
  inputType: TextFieldInputType.weight,
  prefixIcon: Icon(Icons.fitness_center),
)

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

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

高级使用

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. 交互功能 - 状态监控、批量操作等

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 联系我们。