excel_to_json 2.0.0
excel_to_json: ^2.0.0 copied to clipboard
Convert Excel (.xlsx) and CSV spreadsheets to JSON or Dart maps, in pure Dart. Formula results, dates, merged cells, any header row.
Changelog #
2.0.0 - 2026-11-04 #
Breaking #
- Pure Dart: the package no longer depends on Flutter or
file_picker, so it runs in CLIs and servers and imposes no plugin or minimum iOS version on your app. convert(), which opened a file picker, is gone. Pick the file yourself and pass its bytes totoJson(bytes)(JSON string) ortoMap(bytes)(Dart map). See "Migrating from 1.x" in the README.ExcelToJsonConfig.verboseandExcelToJsonConfig.dateFormat(never applied) are removed.- Formula cells give the result Excel saved instead of the formula text
(
formulaResults: falserestores the text). - A column with data but a blank header keeps its values under its column
letter (
C) instead of being dropped.
Added #
- CSV files, detected from the content:
,,;or tab delimiter (decimal commas and title lines do not confuse it), quoted fields, UTF-8 (with BOM) or Windows-1252. Fields come as text. headerRow: the row with the column names, for files with a title above them;nullfor files with no header, keyed by column letter.fillMergedCells: repeat a merged cell's value in every cell it covers.sheets: convert only the named sheets;includeHiddenSheets: falseleaves out the sheets hidden in Excel.keyStyle:KeyStyle.snakeCaseandKeyStyle.camelCasekeys, without accents. Keys are always trimmed, and repeated names becomeName_2.- Times of day and elapsed times (
[h]:mm) from their number format; dates in the 1904 date system and the East Asian built-in date formats; ISO date cells (t="d"); Excel's_x000D_text escapes. - Legacy
.xlsfiles get a clear error instead of a generic one. excel-to-jsoncommand line tool (dart pub global activate excel_to_json), with the same options asExcelToJsonConfig.
Changed #
- Spreadsheets are read by the package itself, streaming the sheet XML, instead
of through
package:excel. A 20,000-row sheet converts about 4x faster and with a fraction of the memory, and filespackage:excelcould not open now work: built-in number formats declared again (common in files written by Apache POI), currency formats, and repeated entries in the shared string table, which shifted or crashed every text cell after them.
Fixed #
- Text cells crashed the conversion:
package:excelreturns them as aTextSpan, whichjsonEncodecannot write. - A blank header cell shifted every column after it.
useDateTimeStrings: falsecrashed withJsonUnsupportedObjectError; dates now come asDateTime(and times asDuration) intoMap, and as strings intoJson.- Empty rows were never skipped; now they are unless
includeEmptyRowsis set. - Unreadable files always throw
ExcelToJsonException.
Internal #
- Tests convert real spreadsheets: written by
package:excel, hand-written XML for what it cannot produce, and CSV. CI runs them with the lowestarchiveandxmlversions too.
1.5.1 August 6, 2025 #
๐ Documentation Changes #
- Updated package description in pubspec.yaml as requested by pub.dev for better compliance with publishing guidelines
1.5.0 August 6, 2025 #
๐ Major Improvements & New Features #
โจ New Features
- Configuration System: Added
ExcelToJsonConfigclass for customizable conversion options - Custom Exception Handling: Introduced
ExcelToJsonExceptionfor better error reporting - Enhanced Logging: Optional verbose logging during conversion process
- Empty Row Handling: Configurable option to include or exclude empty rows
- Better Type Safety: Improved cell value conversion with comprehensive type handling
๐ง Code Improvements
- Complete API Refactor: More intuitive and flexible API design
- Comprehensive Documentation: Added detailed inline documentation for all public APIs
- Better Error Messages: More descriptive error messages with contextual information
- Performance Optimization: Streamlined conversion process with better memory usage
- Code Quality: Enhanced code structure with better separation of concerns
๐ Documentation Enhancements
- Comprehensive README: Complete rewrite with examples, configuration options, and troubleshooting
- API Documentation: Detailed documentation for all classes and methods
- Usage Examples: Multiple usage patterns from basic to advanced
- Platform Support: Clear documentation of supported platforms and limitations
๐งช Testing Improvements
- Unit Tests: Added comprehensive unit tests for all major components
- Widget Tests: Improved example app tests with better coverage
- Example App: Complete redesign with modern Material Design 3 UI
- Interactive Demo: Enhanced example with configuration options and result display
๐ ๏ธ Technical Improvements
- Better File Handling: Enhanced file picker integration with proper error handling
- Type Safety: Improved type definitions and null safety
- Memory Management: Better handling of large Excel files
- Cross-Platform: Verified compatibility across all supported platforms
๐ Breaking Changes #
- Constructor now accepts optional
ExcelToJsonConfigparameter - Enhanced error handling may require updating catch blocks to handle
ExcelToJsonException - Some internal methods have been refactored (private APIs)
๐ Migration Guide #
// Old usage (still supported)
final converter = ExcelToJson();
final result = await converter.convert();
// New usage with configuration
final converter = ExcelToJson(
config: ExcelToJsonConfig(
includeEmptyRows: true,
verbose: true,
),
);
final result = await converter.convert();
1.4.0 26 June 2024 #
What's Changed #
- Update excel dependency to version 4.0.3 by @vitoramaral10 in https://github.com/vitoramaral10/excel_to_json/pull/15
- Update contributing guidelines and code of conduct by @vitoramaral10 in https://github.com/vitoramaral10/excel_to_json/pull/15
1.3.0 25 June 2024 #
What's Changed #
- Merge tag 'v1.2.0' into develop by @vitoramaral10 in https://github.com/vitoramaral10/excel_to_json/pull/13
- Update flutter by @vitoramaral10 in https://github.com/vitoramaral10/excel_to_json/pull/14
- Fixed CVE-2024-4068 by @vitoramaral10 in https://github.com/vitoramaral10/excel_to_json/security/dependabot/2
