SC Flutter Component Library
一个功能丰富的 Flutter 组件库，提供了完整的 UI 组件集合，支持多种输入类型、搜索功能、日期选择和筛选组件。专为提高开发效率和用户体验而设计，支持全平台部署。
🚀 项目概述
本组件库专注于提供高质量、易用的通用组件，特别适用于需要数据录入、搜索、筛选和表单处理的应用场景。所有组件都经过精心设计，确保在不同平台上都能提供一致的用户体验。
✨ 主要特性
- 🎯 多种输入类型支持 - 文本、重量、单价、金额、数量等专业输入
- 🔍 智能搜索功能 - 实时搜索、过滤和结果展示
- 📅 专业日期选择 - 单选、范围选择、快捷选择
- 🏷️ 灵活筛选组件 - 多选、单选、自定义样式
- 📄 分页导航 - 页码跳转、每页数量选择、总数显示
- 📱 全平台支持 - Android、iOS、Web、Desktop
- 🎨 高度可定制 - 样式、主题、交互行为
- ⚡ 性能优化 - 防抖搜索、资源管理、状态优化
📦 组件简介
🔤 TextFieldWidget
功能丰富的文本输入框组件，支持多种输入类型和自动格式验证。
快速使用：
TextFieldWidget(
labelText: '金额',
inputType: TextFieldInputType.amount,
onChanged: (value) => print('输入: $value'),
)
🔍 FilterSearchWidget
通用的搜索组件，支持实时搜索、自定义过滤和结果显示功能。
快速使用：
FilterSearchWidget(
availableFilters: [
{'title': '电子产品', 'dataIndex': 'electronics', 'filterType': 'select'},
{'title': '服装鞋帽', 'dataIndex': 'clothing', 'filterType': 'select'},
],
hintText: '请选择分类',
onSelectFilter: (title, dataIndex, filterType) {
print('选中: $title');
},
)
📅 DateRangeSearchWidget
专业的日期范围选择组件，支持单选和范围选择模式，提供快捷选择和精度控制功能。
快速使用：
DateRangeSearchWidget(
hintText: '请选择日期范围',
selectionMode: DateSelectionMode.range,
onDateRangeChanged: (startDate, endDate) {
print('选择的日期范围: $startDate - $endDate');
},
)
🏷️ TagSectionWidget
内部状态管理的标签选择组件，支持单选和多选模式，无需外部状态控制。
🆕 重大更新 (StatefulWidget)：
- ✅ 内部状态管理，无需外部状态控制
- ✅ 自动默认选择"全部"选项
- ✅ 智能选择逻辑处理
- ✅ 提供手动控制方法
- ✅ 完全向后兼容
快速使用：
// 推荐用法：完全内部管理
TagSectionWidget(
optionMaps: [
{'title': '全部', 'value': 'all', 'enable': true},
{'title': '选项1', 'value': 'option1', 'enable': true},
{'title': '选项2', 'value': 'option2', 'enable': true},
],
color: Colors.blue,
onChanged: (selectedOptions) {
// 可选：处理选择变化
print('选择变化: $selectedOptions');
},
)
// 带初始值
TagSectionWidget(
initialSelectedOptions: ['option1'],
optionMaps: [...],
color: Colors.blue,
selectionMode: TagSelectionMode.single, // 单选模式
)
📄 CustomPaginationWidget
功能完整的分页组件，支持页码导航、每页数量选择和总数显示。现已修复生命周期管理问题，支持动态参数更新。
快速使用：
CustomPaginationWidget(
totalRecords: 1000,
initialPage: 1,
pageSize: 20,
onPageChanged: (page) => print('当前页: $page'),
onPageSizeChanged: (size) => print('每页: $size'),
)
重要更新 (v0.1.5):
- ✅ 修复了
initialPage参数不更新的问题 - ✅ 支持动态更新
totalRecords和pageSize参数 - ✅ 增强了页面边界验证和错误处理
- ✅ 新增了全面的测试覆盖
🌲 TreeLevel3Widget
功能完整的三级树形组件，支持展开收起、选择、自定义样式等功能。
🆕 新功能:
- 支持
GeneralTableData自定义参数类型，可为节点关联表格数据和操作 - 支持
rawData参数，自动解析原始数据结构，无需手动转换
快速使用：
TreeLevel3Widget(
data: [
TreeLevel3Item(
id: '1',
title: '根节点',
level: 1,
icon: Icons.folder,
children: [
TreeLevel3Item(
id: '1-1',
title: '子节点',
level: 2,
parentId: '1',
icon: Icons.folder_open,
),
],
),
],
onNodeTap: (item) => print('点击: ${item.title}'),
multiSelect: false,
showConnectingLines: true,
customData: {
'theme': 'default',
'allowDrag': false,
'showTooltips': true,
},
)
🎯 FastContextMenu
快速响应的现代化右键菜单组件，支持自定义菜单项和智能位置计算。
快速使用：
FastContextMenu.show(
context: context,
position: Offset(100, 100),
menuItems: [
MenuItemConfig(
title: '编辑',
icon: Icons.edit,
onTap: () => print('编辑'),
),
MenuItemConfig(
title: '删除',
icon: Icons.delete,
onTap: () => print('删除'),
),
],
);
📏 HResizableContainerWidget
水平可调整大小的容器组件，支持拖动调整宽度和智能约束计算。
快速使用：
HResizableContainerWidget(
defaultWidth: 300,
minWidthRatio: 0.2,
maxWidthRatio: 0.8,
onWidthChanged: (width) => print('宽度: $width'),
child: Container(
color: Colors.blue[50],
child: Text('可调整宽度的内容'),
),
)
📐 VResizableContainerWidget
垂直可调整大小的容器组件，支持拖动调整高度和智能约束计算。
快速使用：
Column(
children: [
// 主要内容区域
Expanded(
child: Container(
color: Colors.blue[50],
child: Text('主要内容区域'),
),
),
// 可调整高度的底部面板
VResizableContainerWidget(
defaultHeight: 200,
minHeightRatio: 0.1,
maxHeightRatio: 0.6,
onHeightChanged: (height) => print('高度: $height'),
child: Container(
color: Colors.green[50],
width: double.infinity,
child: Text('可调整高度的底部面板'),
),
),
],
)
🌐 平台支持
本组件库支持所有Flutter平台：
| 平台 | 支持状态 | 说明 |
|---|---|---|
| 📱 Android | ✅ 完全支持 | 支持所有Android版本 |
| 🍎 iOS | ✅ 完全支持 | 支持iOS 9.0+ |
| 🐧 Linux | ✅ 完全支持 | 支持现代Linux发行版 |
| 🍎 macOS | ✅ 完全支持 | 支持macOS 10.11+ |
| 🪟 Windows | ✅ 完全支持 | 支持Windows 7+ |
| 🌐 Web | ✅ 完全支持 | 支持现代浏览器 |
使用场景
- 📱 移动应用: Android和iOS原生体验
- 💻 桌面应用: Windows、macOS、Linux桌面应用
- 🌐 Web应用: 响应式Web界面
- 🔄 跨平台: 一套代码，多端运行
🚀 快速开始
安装
在你的 pubspec.yaml 文件中添加依赖：
dependencies:
sc_flutter_component_library: ^0.0.6
导入
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. 筛选搜索组件
FilterSearchWidget(
availableFilters: [
{'title': '电子产品', 'dataIndex': 'electronics', 'filterType': 'select'},
{'title': '服装鞋帽', 'dataIndex': 'clothing', 'filterType': 'select'},
],
hintText: '请选择商品分类',
labelText: '分类',
onSelectFilter: (title, dataIndex, filterType) {
print('选中分类: $title');
},
)
// 4. 日期范围选择组件
DateRangeSearchWidget(
hintText: '请选择日期范围',
selectionMode: DateSelectionMode.range,
precision: DateTimePrecision.day,
onDateRangeChanged: (startDate, endDate) {
print('选择的日期范围: $startDate - $endDate');
},
)
// 5. 筛选区域组件
FilterSectionWidget(
optionMaps: [
{'title': '全部', 'value': 'all', 'enable': true},
{'title': '价格0-100', 'value': '0-100', 'enable': true},
{'title': '价格100-500', 'value': '100-500', 'enable': true},
],
selectedOptions: ['all'],
onChanged: (selectedValues) {
print('选中的筛选项: $selectedValues');
},
color: Colors.blue,
selectionMode: FilterSelectionMode.multiple,
)
// 6. 分页组件
CustomPaginationWidget(
totalRecords: 1000,
initialPage: 1,
pageSize: 20,
pageSizes: [10, 20, 50, 100],
showPageSizeSelector: true,
onPageChanged: (page) {
print('切换到第 $page 页');
},
onPageSizeChanged: (size) {
print('每页显示 $size 条记录');
},
)
📚 详细介绍
TextFieldWidget
功能丰富的文本输入框组件，支持多种输入类型和自动格式验证。
主要特性：
- 🎯 多种输入类型支持（文本、重量、单价、金额、数量）
- ✅ 自动输入格式验证和限制
- 🎨 可自定义样式和尺寸
- 🔧 支持前缀图标和后缀图标
- 📱 焦点管理和回调事件
- 🔄 启用/禁用状态控制
输入类型：
text: 普通文本输入weight: 重量输入（小数点后3位）price: 单价输入（小数点后4位）amount: 金额输入（小数点后2位）quantity: 数量输入（仅整数）
FilterSearchWidget
通用的搜索组件，提供实时搜索功能和可配置的过滤选项。
主要特性：
- 🔍 下拉选择搜索功能
- 🎯 支持自定义过滤选项数据
- ⚙️ 可配置的显示样式和尺寸
- 🎨 自定义标签和提示文本
- 📱 选择状态管理和回调
- ⚡ 支持不同的过滤类型
DateRangeSearchWidget
专业的日期范围选择组件，支持单选和范围选择模式。
主要特性：
- 📅 支持单选和范围选择模式
- ⚡ 提供快捷日期选择（今天、昨天、本周、本月等）
- 🎯 精度控制（精确到日或分钟）
- 🎨 可自定义样式和格式
- 📱 移动端友好的交互体验
- 🔧 灵活的配置选项
- 🗑️ 支持清除选择功能
FilterSectionWidget
通用的筛选区域组件，用于显示标题和可选择的选项列表。
主要特性：
- 🏷️ 支持多选和单选模式
- 🎨 可自定义主题色和样式
- 📏 灵活的间距和字体大小配置
- 🔧 支持禁用选项显示
- ⚡ 智能的"全部"选项处理逻辑
- 📱 触摸友好的交互设计
CustomPaginationWidget
功能完整的分页组件，支持页码导航、每页数量选择和总数显示。
主要特性：
- 📄 完整的分页导航功能（首页、上一页、下一页、末页）
- 🔢 智能页码显示和跳转
- 📊 总记录数和当前页信息显示
- ⚙️ 可配置的每页显示数量选择
- 🎨 可自定义样式和主题色
- 📱 响应式设计，适配不同屏幕尺寸
- ⚡ 高性能渲染和状态管理
- 🔄 动态参数更新支持 - 支持
initialPage、pageSize、totalRecords参数的实时更新 - 🛡️ 增强的边界验证 - 智能处理页码边界和异常情况
- ✅ 完整的生命周期管理 - 正确响应组件参数变化
🎯 示例项目
项目包含了完整的示例应用，展示了所有组件在不同平台上的功能和用法。
运行示例
# 克隆项目
git clone https://github.com/your-username/sc_flutter_component_library.git
# 进入示例目录
cd sc_flutter_component_library/example
# 获取依赖
flutter pub get
# 运行示例
flutter run
示例功能
示例应用包含以下平台演示：
📱 移动端应用演示
展示移动购物应用中的典型使用场景：
- 商品搜索和筛选
- 订单信息填写
- 收货地址和配送时间选择
- 支付方式选择
- 价格区间和评分筛选
💻 桌面端应用演示
展示企业管理系统中的使用场景：
- 复杂的查询过滤条件
- 商品信息录入表单
- 部门和优先级筛选
- 批量操作和数据导出
- 高级功能演示
🌐 Web应用演示
展示内容管理系统中的使用场景：
- 文章内容编辑
- 分类和标签管理
- 发布时间设置
- 状态筛选和搜索
🔄 平台对比演示
并排展示所有组件在不同平台上的表现，便于对比和测试。
📖 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 | 焦点节点 |
FilterSearchWidget
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| availableFilters | List<Map<String, dynamic>> | [] | 可选择的过滤选项 |
| hintText | String | "" | 提示文本 |
| labelText | String | "" | 标签文本 |
| width | double? | null | 组件宽度 |
| height | double? | null | 组件高度 |
| onSelectFilter | Function(String, String, String)? | null | 选择过滤项回调 |
DateRangeSearchWidget
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| hintText | String | "" | 提示文本 |
| width | double? | null | 组件宽度 |
| height | double? | null | 组件高度 |
| selectionMode | DateSelectionMode | range | 选择模式（单选/范围） |
| precision | DateTimePrecision | day | 时间精度 |
| isShowDeleteIcon | bool | false | 是否显示清除图标 |
| onDateRangeChanged | Function(DateTime?, DateTime?)? | null | 日期范围变化回调 |
TagSectionWidget
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| optionMaps | List<Map<String, dynamic>> | required | 选项数据列表 |
| initialSelectedOptions | List | null | 初始选中的选项值列表 |
| onChanged | Function(List | null | 选项变化回调 |
| color | Color | required | 主题色 |
| padding | EdgeInsets? | null | 容器内边距 |
| spacing | double | 6 | 选项间距 |
| runSpacing | double | 6 | 行间距 |
| optionFontSize | double | 12 | 选项字体大小 |
| selectionMode | TagSelectionMode | multiple | 选择模式 |
状态控制: TagSectionWidget使用内部状态管理，如需重置可通过改变组件的key值重新创建组件。
FilterSectionWidget (已弃用)
此组件已被 TagSectionWidget 替代，建议使用新的 TagSectionWidget。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| optionMaps | List<Map<String, dynamic>> | required | 选项数据列表 |
| selectedOptions | List | required | 已选择的选项值列表 |
| onChanged | Function(List | required | 选项变化回调 |
| color | Color | required | 主题色 |
| padding | EdgeInsets? | null | 容器内边距 |
| spacing | double | 6 | 选项间距 |
| runSpacing | double | 6 | 行间距 |
| optionFontSize | double | 12 | 选项字体大小 |
| selectionMode | FilterSelectionMode | multiple | 选择模式 |
CustomPaginationWidget
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| totalRecords | int | 100000 | 总记录数 |
| initialPage | int | 1 | 初始页码 |
| pageSize | int | 100 | 每页显示数量 |
| onPageChanged | ValueChanged | required | 页码变化回调 |
| pageSizes | List | 20, 50, 100, 1000, 2000 |
可选择的每页数量 |
| onPageSizeChanged | ValueChanged | null | 每页数量变化回调 |
| showPageSizeSelector | bool | true | 是否显示每页数量选择器 |
枚举类型
TextFieldInputType
text: 普通文本输入weight: 重量输入（小数点后3位）price: 单价输入（小数点后4位）amount: 金额输入（小数点后2位）quantity: 数量输入（仅整数）
DateSelectionMode
single: 单选模式range: 范围选择模式
DateTimePrecision
day: 精确到日minute: 精确到分钟
FilterSelectionMode
multiple: 多选模式single: 单选模式
🏗️ 项目结构
sc_flutter_component_library/
├── lib/
│ ├── src/
│ │ ├── common/ # 通用组件
│ │ │ ├── common.dart # 通用组件导出
│ │ │ ├── text_field_widget.dart # 文本输入组件
│ │ │ └── filter_section_widget.dart # 筛选区域组件
│ │ ├── desktop/ # 桌面端组件
│ │ │ ├── desktop.dart # 桌面端组件导出
│ │ │ ├── filter_search_widget.dart # 筛选搜索组件
│ │ │ └── date_range_search_widget.dart # 日期范围选择组件
│ │ └── mobile/ # 移动端组件
│ │ └── mobile.dart # 移动端组件导出
│ │ ├── pagination/ # 分页组件
│ │ │ ├── pagination.dart # 分页组件导出
│ │ │ └── custom_pagination_widget.dart # 分页组件
│ └── sc_flutter_component_library.dart # 主库导出文件
├── example/ # 示例项目
│ ├── lib/
│ │ ├── main.dart # 示例应用主入口
│ │ ├── simple_test.dart # 简单测试页面
│ │ └── platforms/ # 平台示例
│ │ ├── desktop_application_page.dart # 桌面端示例
│ │ ├── mobile_application_page.dart # 移动端示例
│ │ ├── web_application_page.dart # Web端示例
│ │ └── platform_comparison_page.dart # 平台对比示例
│ └── pubspec.yaml # 示例项目配置
├── test/ # 测试文件
├── pubspec.yaml # 项目配置
├── README.md # 本文件
├── CHANGELOG.md # 更新日志
├── LICENSE # 许可证
├── PUBLISH_GUIDE.md # 发布指南
└── UPGRADE_GUIDE.md # 升级指南
🛠️ 开发指南
添加新组件
- 在
lib/src/对应平台目录下创建新的组件文件 - 在对应的导出文件中添加新组件导出
- 在示例项目中添加使用演示
- 更新文档和测试
代码规范
- 遵循 Flutter/Dart 官方代码规范
- 使用有意义的变量和函数命名
- 添加适当的注释和文档
- 确保资源正确释放（dispose）
- 支持可访问性（Accessibility）
测试
# 运行测试
flutter test
# 运行测试覆盖率
flutter test --coverage
# 运行示例项目测试
cd example && flutter test
构建和发布
# 检查代码质量
flutter analyze
# 格式化代码
dart format .
# 发布到 pub.flutter-io.cn
flutter pub publish
📈 版本历史
| 版本 | 发布日期 | 主要更新 |
|---|---|---|
| 0.0.6 | 2024-01-XX | 添加FilterSectionWidget组件，完善平台示例 |
| 0.0.5 | 2024-01-XX | 添加DateRangeSearchWidget组件 |
| 0.0.4 | 2024-01-XX | 添加FilterSearchWidget组件 |
| 0.0.3 | 2024-01-XX | 完善TextFieldWidget功能 |
| 0.0.2 | 2024-01-XX | 添加多种输入类型支持 |
| 0.0.1 | 2024-01-XX | 初始版本，基础TextFieldWidget |
查看 CHANGELOG.md 了解详细的版本更新信息。
🤝 贡献
欢迎提交 Issue 和 Pull Request 来改进这个项目。
贡献步骤
- Fork 本项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
贡献指南
- 确保代码通过所有测试
- 添加适当的测试用例
- 更新相关文档
- 遵循现有的代码风格
📄 许可证
本项目采用 MIT 许可证，详见 LICENSE 文件。
🙏 致谢
感谢所有为这个项目做出贡献的开发者。
📞 支持
如果你觉得这个项目有用，请给它一个 ⭐️！
获取帮助
- 📖 查看文档和示例
- 🐛 提交 Issue 报告问题
- 💬 参与 Discussions 讨论
- 📧 联系维护者
相关链接
SC Flutter Component Library - 让 Flutter 开发更高效 🚀