sheet_mapper #

A powerful Flutter package for mapping Excel, CSV, TSV, and PSV files to Dart objects using annotations and code generation, featuring a beautiful drag-and-drop UI widget.

Preview #

Author #

Abdul Waseem Nihaal

• Email: [email protected]
• GitHub: https://github.com/waseemnihaal20-a11y

Features #

• Multiple File Formats - Excel (.xlsx, .xls, .xlsm), CSV, TSV, PSV
• Type-Safe Code Generation - Like json_serializable and freezed
• Beautiful Drag-Drop UI - Customizable widget for file upload
• Flexible Annotations - Optional column mapping
• Default Values - Automatic handling of empty cells
• Type Conversions - String, int, double, bool, DateTime
• Error Handling - Comprehensive validation and error messages
• Zero Dependencies on UI - Use programmatically without the widget
• Cross-Platform - Android, iOS, Web, Windows, macOS, Linux

Installation #

Add to your pubspec.yaml:

dependencies:
  sheet_mapper: ^1.0.0

dev_dependencies:
  build_runner: ^2.4.0
  sheet_mapper_generator: ^1.0.0

Then run:

flutter pub get

Quick Start #

1. Define Your Model #

import 'package:sheet_mapper/sheet_mapper.dart';

part 'user.g.dart';

@SheetTable()
class User with $UserSheetMapper {
  @SheetColumn('Full Name', required: true)
  final String name;

  @SheetColumn('Email', required: true)
  final String email;

  @SheetColumn('Age', defaultValue: '0')
  final int age;
}

2. Generate Code #

dart run build_runner build --delete-conflicting-outputs

3. Initialize (once in your app) #

void main() {
  // Initialize all your sheet mappers
  // This will be available in the generated file like `init<your_model_name>SheetMapper()`, so you can just call it and this is mandatory.
  initUserSheetMapper();

  runApp(MyApp());
}

4. Use the Widget #

SheetMapperWidget<User>(
  onResult: (List<User> users) {
    print('Parsed ${users.length} users');
  },
  onError: (String error) {
    print('Error: $error');
  },
)

That's it! No parser functions or manual registration needed.

5. Or Use Programmatically #

// Parse directly using generated mixin
final users = $UserSheetMapper.fromSheet(rows);

// Or parse from file
final file = File('users.xlsx');
final bytes = await file.readAsBytes();
final rows = SheetParser.parseBytes(bytes, SheetType.xlsx);
final users = $UserSheetMapper.fromSheet(rows);

Annotations #

@SheetTable #

@SheetTable(
  sheetName: 'Users',      // Excel sheet name (optional)
  sheetIndex: 0,           // Sheet index (default: 0)
  hasHeader: true,         // First row is header (default: true)
  startRow: 0,             // Skip rows (optional)
)
class User with _$UserSheetMapper { ... }

@SheetColumn #

@SheetColumn(
  'Column Name',           // Header name
  defaultValue: '0',       // Default if empty (optional)
  dateFormat: 'yyyy-MM-dd',// Date format (optional)
  required: false,         // Throw error if missing (default: false)
  trim: true,              // Trim whitespace (default: true)
)
final String fieldName;

Note: If @SheetColumn is not provided, the field name is used as the column name.

Widget Customization #

SheetMapperWidget<User>(
  supportedSheetTypes: [SheetType.xlsx, SheetType.csv],
  height: 250,
  borderColor: Colors.deepPurple,
  borderWidth: 2.0,
  dashPattern: [10, 5],
  backgroundColor: Colors.purple.withOpacity(0.1),
  instructionText: 'Drop your file here',
  icon: Icons.cloud_upload,
  iconSize: 60,
  iconColor: Colors.deepPurple,
  borderRadius: 16,
  onResult: (data) => print('Success'),
  onError: (error) => print('Error: $error'),
)

Supported Types #

All types support nullable versions (String?, int?, etc.).

Platform Support #

Related Packages #

• sheet_mapper_generator - Code generator for type-safe sheet mapping

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing #

Contributions are welcome! Please read our contributing guidelines and submit pull requests.