搜尋套件、儲存庫與 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.

所屬分類

原始碼儲存庫

使用此套件的專案