excel2003 - Dart API docs

A lightweight, pure‑Dart library for reading legacy Excel .xls files (Excel 97‑2003/BIFF8). Use it in command‑line, server, or Flutter apps; no native code required.

❗ Note: this package does not support the newer .xlsx format. If you need OOXML support please look elsewhere.

Features

✅ Read BIFF8‑formatted .xls workbooks (Excel 97‑2003)
✅ Navigate sheets by index or name; list sheetCount / sheetNames
✅ Iterate rows and columns; sparse storage skips blanks for efficiency
✅ Access cell values as Dart types (String, num, bool, DateTime, …)
✅ Convert worksheets to List<Map<String,dynamic>> using headers
✅ Constructors from file path or in‑memory bytes
✅ Zero external dependencies – works on Dart CLI, server, and Flutter

Out of scope

Does not read .xlsx, CSV, or other spreadsheet formats
No write support – read‑only library
Limited formula evaluation (only cached values are returned)

Getting started
Usage
Examples
Additional information
中文说明

Getting started

Prerequisites

Dart SDK 3.7.2 or later (see environment: in pubspec.yaml).
A .xls file produced by Excel 97‑2003 or any compatible BIFF8 exporter.

Installing

Add the package to your project by running:

dart pub add excel2003

If you are using Flutter, run the same command from the top of your flutter project; the dependency is pure Dart and works just fine on mobile and desktop.

Example project

The example/ directory in this repository contains a command‑line utility (xls_reader_example.dart) that prints the contents of a workbook. Run it as follows:

# use your own .xls file or copy one into the repo root
dart run example/xls_reader_example.dart path/to/book.xls

The example source is a good starting point for your own tooling.

Usage

The API surface is small and intentionally easy to remember. Here are the typical steps:

Opening a workbook

import 'package:excel2003/excel2003.dart';

void main() {
  // Create reader from file path. You can also call
  // `XlsReader.fromBytes(bytes)` if you already have the workbook data.
  final reader = XlsReader('path/to/workbook.xls');
  reader.open(); // throws if file is missing or not a valid BIFF8 stream

  print('Opened workbook with ${reader.sheetCount} sheets');
}

Iterating sheets and cells

// list sheet names
print(reader.sheetNames);

// grab sheet 0 (first sheet)
final sheet = reader.sheet(0);

// iterate the used range; firstRow/firstCol are inclusive, lastRow/lastCol
// are exclusive (similar to Dart ranges)
for (int r = sheet.firstRow; r < sheet.lastRow; r++) {
  for (int c = sheet.firstCol; c < sheet.lastCol; c++) {
    final v = sheet.cell(r, c);
    if (v != null) print('Cell($r,$c): $v');
  }
}

Converting a sheet to maps

Treat the first non‑empty row as column headers and get a list of maps:

final rows = sheet.toMaps();
for (final map in rows) {
  print(map['Name']);
}

Remember to import package:excel2003/excel2003.dart and call reader.open() before accessing sheets.

Related terms you may search for in this README: .xls, BIFF8, SST, OLE2, sheetCount, cell, toMaps, XlsReader.

API reference generated by dart doc is available on pub.dev under the Documentation tab once the package is published.
Learn about the internal BIFF parsing by reading the source under lib/src/biff/ and lib/src/ole2/.
Want formula support? open an issue or PR; currently only cached formula values are returned.
Repository: https://github.com/ubuntu2204/excel2003
Issues: File bugs or feature requests on the GitHub issue tracker.
Contributing: Feel free to open pull requests, add tests under test/, and follow the existing style. The package uses standard Dart formatting (dart format) and static analysis (dart analyze).
License: Apache‑2.0 (see LICENSE).

中文说明

这是一个用于读取旧版 Excel .xls 文件(97‑2003)的 Dart 库。提供简洁的 API 来打开工作簿、列出工作表、读取单元格内容。

特性

支持 BIFF8 格式的 .xls 文件。
遍历工作表、行和列；按索引访问单元格。
将工作表转换为 Map 列表，首行可作为表头。
纯 Dart 实现，无需本机依赖，适用于 Dart 命令行、Flutter 和服务端。

快速开始

需要 Dart SDK 3.7.2 或更高版本。将依赖添加到项目：

dart pub add excel2003

或者在 Flutter 项目中运行同样的命令。

使用示例

import 'package:excel2003/excel2003.dart';

void main() {
  final reader = XlsReader('路径/到/文件.xls');
  reader.open();
  print('工作表：${reader.sheetNames}');

  final sheet = reader.sheet(0);
  for (int row = sheet.firstRow; row < sheet.lastRow; row++) {
    for (int col = sheet.firstCol; col < sheet.lastCol; col++) {
      final value = sheet.cell(row, col);
      if (value != null) {
        print('Cell($row,$col)=$value');
      }
    }
  }
}

例子项目见 example/ 目录，可通过 dart run example/xls_reader_example.dart path/to/book.xls 运行。

其他信息

仓库地址：github.com/ubuntu2204/excel2003
问题报告请使用 GitHub issue。
欢迎贡献：添加测试、修复 bug、改进说明。
许可证：Apache‑2.0。