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和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 #

FilterSearchWidget #

DateRangeSearchWidget #

TagSectionWidget #

状态控制: TagSectionWidget使用内部状态管理，如需重置可通过改变组件的key值重新创建组件。

FilterSectionWidget (已弃用) #

此组件已被 TagSectionWidget 替代，建议使用新的 TagSectionWidget。

CustomPaginationWidget #

枚举类型 #

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               # 升级指南

🛠️ 开发指南 #

添加新组件 #

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

代码规范 #

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

测试 #

# 运行测试
flutter test

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

# 运行示例项目测试
cd example && flutter test

构建和发布 #

# 检查代码质量
flutter analyze

# 格式化代码
dart format .

# 发布到 pub.flutter-io.cn
flutter pub publish

📈 版本历史 #

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

🤝 贡献 #

欢迎提交 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

贡献指南 #

• 确保代码通过所有测试
• 添加适当的测试用例
• 更新相关文档
• 遵循现有的代码风格

📄 许可证 #

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

🙏 致谢 #

感谢所有为这个项目做出贡献的开发者。

📞 支持 #

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

获取帮助 #

• 📖 查看文档和示例
• 🐛 提交 Issue 报告问题
• 💬 参与 Discussions 讨论
• 📧 联系维护者

相关链接 #

• Flutter 官方文档
• Dart 语言指南
• pub.flutter-io.cn 包管理

SC Flutter Component Library - 让 Flutter 开发更高效 🚀