搜索插件、代码仓与 APP 分类

插件详情v8.0.0

csv

一个高质量的CSV库。编码和解码CSV字符串,支持流式处理(每行一个事件)、自动检测以及与Excel兼容。字符串必须是逗号分隔(可配置)的值。

AndroidiOSWebmacOSWindowsLinux
近 30 天下载
103万
喜欢数
410
Pub 分数
150

安装插件

flutter pub add csv

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

一个高质量的 Dart 和 Flutter CSV 库,可高效地编码和解码 CSV 字符串,支持流式处理(逐行),自动检测分隔符,并与 Excel 格式兼容。它处理以逗号分隔的值(支持自定义分隔符),适用于在各种平台上读取和写入结构化数据。非常适合数据导入/导出工作流程。

适合场景

  • 高效解析大型CSV文件
  • 将应用数据导出为 CSV
  • 从CSV读取配置或用户数据
  • 与 Excel 兼容的数据集集成
  • 处理实时CSV流

主要特点

  • 基于流的逐行处理
  • 可配置分隔符支持
  • 字段分隔符的自动检测
  • Excel 格式兼容性
  • 强大的错误处理

适合对象

  • 数据密集型应用
  • 需要 CSV I/O 的移动和网页应用
  • 后端服务处理CSV输入
  • 需要轻量级 CSV 解析的工具

使用建议

  • 需要仔细处理格式错误的CSV
  • 仅限CSV特定用例
  • 不适用于复杂的电子表格格式,如 ODS
  • 性能取决于流的大小和复杂性

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

csv

A high-quality, best-practice CSV library for Dart, inspired by PapaParse but built with Dart idioms in mind.

Upgrading from Version 7

Version 8 fixes an issue where using csv.decoder as a stream transformer produced an extra layer of nesting (#77).

  • CsvCodec has been renamed to Csv. A deprecated CsvCodec typedef is available for migration.
  • Csv no longer extends dart:convert's Codec class. If you need a Codec (e.g., for .fuse()), use asCodec().

If you rely on the version 6 API, please consult doc/README-v6.md.

Features

  • Stream-friendly: decoder and encoder are proper StreamTransformers — one row per stream event.
  • Easy Excel Compatibility: Built-in support for Excel-compatible CSVs (UTF-8 BOM, ; separator, \r\n line endings).
  • Auto-detection: Smartly detects delimiters and line endings.
  • Robust Parsing: Handles quoted fields, escaped quotes, and even malformed CSVs graciously (similar to PapaParse).
  • Performance: Optimized for speed and low memory usage.
  • Dynamic Typing: Optional automatic parsing of numbers and booleans (similar to PapaParse).
Delimiters

The Csv class and CsvDecoder support:

  • Field Delimiters: Can be single or multi-character strings (e.g., ,, ::, |).
  • Quote Character: Must be a single character. Defaults to ".
  • Escape Character: Must be a single character (if provided). Defaults to the quote character.
  • Line Delimiters: The decoder automatically handles \r, \n, and \r\n. The encoder allows specifying a custom lineDelimiter (defaults to \r\n).

⚠️ Important: Line Endings & Windows

The default line delimiter is \r\n (CRLF) as specified by RFC 4180.

Be careful on Windows! If you write the CSV string directly to a file using certain methods (like File.writeAsString without specifying strict options or redirecting stdout), Windows file handling might automatically convert \n to \r\n. Since the CSV already contains \r\n, this can result in double carriage returns: \r\r\n.

To avoid this, either:

  1. Use \n as the line delimiter:
    final codec = Csv(lineDelimiter: '\n');
    final csvString = codec.encode(data);
    
  2. Use a binary writer (e.g., File.openWrite()) which writes bytes exactly as they are.

Usage

Simple Example
import 'package:csv/csv.dart';

void main() {
  final data = [
    ['Name', 'Age', 'City'],
    ['Alice', 30, 'New York'],
    ['Bob', 25, 'London'],
  ];

  // Encode
  final String csvString = csv.encode(data);
  print(csvString);

  // Decode
  final List<List<dynamic>> decodedData = csv.decode(csvString);
  print(decodedData);
}
Stream Transformation (e.g., reading a file)

The decoder and encoder are StreamTransformers that emit one row per event, so stream.transform(csv.decoder).toList() gives you a flat List<List<dynamic>>.

import 'dart:convert';
import 'dart:io';
import 'package:csv/csv.dart';

void main() async {
  final file = File('data.csv');

  // Each event in the stream is a single row (List<dynamic>).
  final List<List<dynamic>> rows = await file
      .openRead()
      .transform(utf8.decoder)
      .transform(csv.decoder)
      .toList();

  print(rows.first); // e.g. ['Name', 'Age', 'City']
}
Stream Read-Modify-Write Pipeline
import 'dart:convert';
import 'dart:io';
import 'package:csv/csv.dart';

void main() async {
  final input = File('input.csv');
  final output = File('output.csv');

  await input.openRead()
      .transform(utf8.decoder)
      .transform(csv.decoder)
      .map((row) {
        row.add('Processed');
        return row;
      })
      .transform(csv.encoder)
      .transform(utf8.encoder)
      .pipe(output.openWrite());
}
Excel Compatible CSV

Excel often requires a UTF-8 BOM and ; as a separator to open files correctly in certain locales.

import 'package:csv/csv.dart';

void main() {
  final data = [
    ['Header1', 'Header2'],
    ['Value 1', 'Value 2'],
  ];

  // Use the built-in excel codec
  final String excelCsv = excel.encode(data);
  
  // This automatically adds the BOM and uses ';' as delimiter
}
Custom Configuration
import 'package:csv/csv.dart';

void main() {
  final myCodec = Csv(
    fieldDelimiter: '\t',
    lineDelimiter: '\n',
    quoteMode: QuoteMode.strings, // Only quote strings, not numbers
    escapeCharacter: '\\',       // Use backslash for escaping
  );
  
  final encoded = myCodec.encode([['a', 1, true], ['b', 2.5, false]]);
  // Output: "a"\t1\ttrue\n"b"\t2.5\tfalse
}
Dynamic Typing

Automatically convert values that look like numbers or booleans into their respective Dart types.

[!NOTE] Enabling dynamicTyping adds a small performance overhead (approx. 15% in benchmarks). For maximum performance on large files where you know the schema, using a manual decoderTransform or processing rows after decoding is faster.

import 'package:csv/csv.dart';

void main() {
  final input = 'Name,Age,Active\nAlice,30,true';
  
  // With dynamic typing enabled
  final codec = Csv(dynamicTyping: true);
  final rows = codec.decode(input);
  
  print(rows[0][1].runtimeType); // int (30)
  print(rows[0][2].runtimeType); // bool (true)
}
Advanced: Field Transformations

You can use the encoderTransform and decoderTransform hooks to process fields based on their value, column index, or header name to for example trim text, change decimal separators or format dates.

import 'package:csv/csv.dart';

void main() {
  final customCodec = Csv(
    fieldDelimiter: ';',
    parseHeaders: true, // Required if you want 'header' name in the transform
    decoderTransform: (value, index, header) {
      // Change column 3 (index 2) to uppercase
      if (index == 2) return value.toUpperCase();
      
      // Convert 'Age' column to int
      if (header == 'Age') return int.tryParse(value) ?? value;
      
      return value;
    },
  );

  final input = 'Name;City;Age\nAlice;London;30';
  final decoded = customCodec.decode(input);
  
  print(decoded[0]['Age']);   // 30 (as int)
  print(decoded[0]['City']);  // LONDON
}
Automated Delimiter Detection (including sep=;)

The library automatically detects common delimiters (,, ;, \t, |). It also respects the sep=; header common in some Excel-exported CSV files.

final decoded = csv.decode('sep=;\r\nA;B;C');
// Result: [['A', 'B', 'C']]
Map-like Row Access

If you want to access values by their header names, you can use either decodeWithHeaders() or the parseHeaders option on the codec. Both return CsvRow objects which behave like both a List and a Map.

import 'package:csv/csv.dart';

void main() {
  final fileContents = 'id,name\n1,Alice\n2,Bob';
  
  // Method 1: Using decodeWithHeaders (Recommended)
  // This automatically sets the parseHeaders flag and returns a properly typed List<CsvRow>.
  final rowsWithHeaders = csv.decodeWithHeaders(fileContents);
  
  // Access by header name directly
  print(rowsWithHeaders[0]['name']); // Alice
  
  // Still accessible by index
  print(rowsWithHeaders[0][1]);      // Alice
  
  
  // Method 2: Using Csv(parseHeaders: true)
  // This requires casting the returned rows to CsvRow manually.
  final codec = Csv(parseHeaders: true);
  
  final dynamicRows = codec.decode(fileContents);
  
  final row = dynamicRows[0] as CsvRow;
  // Access by header name
  print(row['name']); // Alice
  
  // The first row of the file was used for headers and is not in the list.
}
Using asCodec() for Fusing

If you need a dart:convert Codec — for example, to use .fuse() — call asCodec():

import 'dart:convert';
import 'package:csv/csv.dart';

// A simple converter that adds a column to every row.
class AddColumnConverter extends Converter<List<List<dynamic>>, List<List<dynamic>>> {
  @override
  List<List<dynamic>> convert(List<List<dynamic>> input) {
    return input.map((row) => [...row, 'Processed']).toList();
  }
}

void main() {
  final processor = AddColumnConverter();

  // Use asCodec() to get a dart:convert Codec, then fuse.
  final codec = csv.asCodec();
  final sanitizingCodec = codec.decoder.fuse(processor).fuse(codec.encoder);

  final inputCsv = 'Name,Age\nAlice,30';
  final outputCsv = sanitizingCodec.convert(inputCsv);

  print(outputCsv);
  // Output:
  // Name,Age,Processed
  // Alice,30,Processed
}

Controlling batch size: When the codec's decoder is used as a stream transformer, rows from the same input chunk are emitted together in a single batch (a List<List<dynamic>>). You can limit the maximum number of rows per batch with maxRowsPerBatch:

// Each stream event contains at most 100 rows.
final codec = csv.asCodec(maxRowsPerBatch: 100);

// For single-row events (one row per stream event), use 1:
final singleRowCodec = csv.asCodec(maxRowsPerBatch: 1);

PapaParse Features

This library incorporates many good ideas from PapaParse, such as:

  • Handling misplaced quotes gracefully.
  • Auto-detecting delimiters based on frequency and consistency.
  • Handling various line ending styles automatically in the decoder.
  • Support for sep= headers.
  • Header Parsing: Efficiently mapping headers to row indices (similar to header: true in PapaParse).

Installation

Add this to your pubspec.yaml:

dependencies:
  csv: ^8.0.0

The Codec Problem & asCodec()

This section explains why Csv does not extend dart:convert's Codec, and what asCodec() provides as an escape hatch.

Background

Dart's Codec<S, T> provides two converters:

Component Type
decoder Converter<T, S>
encoder Converter<S, T>

A Converter<S, T> has two roles:

  1. Batch: T convert(S input) — convert an entire input at once.
  2. Stream: Stream<T> bind(Stream<S>) — transform a stream, where each event is of type T.

The type parameter T must serve both roles. For most codecs this is fine. For example, utf8 is a Codec<String, List<int>>: batch conversion produces a List<int>, and each stream event is also a List<int> (a chunk of bytes). Concatenating chunks of bytes is natural.

Why CSV breaks this

For a CSV decoder, the two roles need different types:

Role Needs
Batch (convert()) Returns List<List<dynamic>> — all rows at once
Stream (each event) Should be List<dynamic> — one row at a time

There is no single type T that works for both. If we use Converter<String, List<List<dynamic>>> (as version 7 did), then:

  • convert("a,b\nc,d") → [['a','b'], ['c','d']] ✓ correct
  • stream.transform(decoder).toList() → List<List<List<dynamic>>> ✗ extra nesting!

Each stream event is a batch of rows, and .toList() collects those batches into yet another list — the "extra []" reported in #77.

This is a fundamental limitation of dart:convert's type system, not a bug in this library. Versions 3.2 through 6 worked around it by not being a Codec at all (see commit 235d898). Version 7 reintroduced Codec and the problem came back.

The solution in version 8

Version 8 takes a hybrid approach:

  • By default, CsvDecoder and CsvEncoder are StreamTransformerBase subclasses. Stream usage works correctly — one row per event.
  • asCodec() returns a real Codec<List<List<dynamic>>, String> adapter for when you need .fuse() or other Codec-specific APIs. The returned codec wraps the same parsing/encoding logic, but follows Dart's Converter type contract (with the inherent stream nesting trade-off).
// Default: stream works correctly
final rows = await file.openRead()
    .transform(utf8.decoder)
    .transform(csv.decoder)
    .toList();
// rows is List<List<dynamic>> ✓

// asCodec(): for fuse() and other Codec APIs
final fused = csv.asCodec().decoder.fuse(someConverter);

// asCodec() with batch size limit
final codec = csv.asCodec(maxRowsPerBatch: 100);

If you use asCodec().decoder as a stream transformer, you will get the extra nesting — that is inherent to Dart's Converter type contract and cannot be avoided. Rows from the same input chunk are grouped together into a single batch. Use maxRowsPerBatch to limit the batch size, or use csv.decoder directly for streams.

所属分类

源码仓库

使用此插件的项目