FluentNPOI 2.3.0

FluentNPOI

FluentNPOI is a fluent wrapper for NPOI that provides an intuitive and easy-to-use API for reading and writing Excel files.

繁體中文

🚀 Features

• ✅ Fluent API - Chained method calls for simpler, readable code
• ✅ Strongly Typed Mapping - Use FluentMapping for type-safe data binding
• ✅ Modular Packages - Install only what you need: Core, PDF, Streaming, Charts
• ✅ Direct Styling - Configure styles directly within Mapping or FluentCell API
• ✅ Style Management - Smart caching to handle duplicate styles
• ✅ Comprehensive I/O - Read/Write, Images, Formulas, Merging
• ✅ HTML/PDF Export - Convert Excel to HTML or PDF
• ✅ Chart Generation - Generate charts using ScottPlot and embed in Excel
• ✅ Hot Reload - Live preview changes with dotnet watch and LibreOffice (requires LibreOffice)

📦 Installation

Core Package

dotnet add package FluentNPOI

Optional Modules

🎯 Quick Start

1. Basic Write

using FluentNPOI;
using NPOI.XSSF.UserModel;

var workbook = new XSSFWorkbook();
var fluent = new FluentWorkbook(workbook);

fluent.UseSheet("Sheet1")
      .SetCellPosition(ExcelCol.A, 1)
      .SetValue("Hello World!")
      .SetBackgroundColor(IndexedColors.Yellow)
      .SetFont(isBold: true, fontSize: 14);

fluent.SaveToPath("output.xlsx");

2. Table Binding with FluentMapping (Recommended)

var mapping = new FluentMapping<Student>();

mapping.Map(x => x.Name)
    .ToColumn(ExcelCol.A)
    .WithTitle("Name")
    .WithBackgroundColor(IndexedColors.LightCornflowerBlue);

mapping.Map(x => x.Score)
    .ToColumn(ExcelCol.B)
    .WithTitle("Score")
    .WithNumberFormat("0.0");

fluent.UseSheet("Report")
      .SetTable(data, mapping)
      .BuildRows()
      .SetAutoFilter()
      .FreezeTitleRow();

3. Streaming for Large Files

using FluentNPOI.Streaming;

StreamingBuilder<DataModel>.FromFile("large_input.xlsx")
    .Transform(x => x.Value *= 2)
    .WithMapping(mapping)
    .SaveAs("output.xlsx");

4. Chart Generation

using FluentNPOI.Charts;

// Integrated chaining API
fluent.UseSheet("Charts")
    .SetCellPosition(ExcelCol.A, 1)
    .AddBarChart(data, chart => {
        chart.X(d => d.Category)
             .Y(d => d.Value)
             .WithTitle("Sales Report");
    }, width: 400, height: 300);

// Or generate manually
var chartBytes = ChartBuilder.Bar(data)
    .X(d => d.Category)
    .Y(d => d.Value)
    .Configure(plot => {
        // Full access to ScottPlot API
        plot.FigureBackground.Color = ScottPlot.Colors.White;
    })
    .ToPng(400, 300);

5. PDF Export

using FluentNPOI.Pdf;

PdfConverter.ConvertSheetToPdf(fluent.UseSheet("Report"), "report.pdf");

6. Live Preview (Hot Reload)

Ensure FluentNPOI.HotReload and LibreOffice are installed.

Code Implementation

Wrap your generation logic with FluentLivePreview.Run:

using FluentNPOI.HotReload;

// ... inside your Main method or setup
FluentLivePreview.Run("output/report.xlsx", fluent =>
{
    // Your FluentNPOI code goes here
    fluent.UseSheet("Sheet1")
          .SetCellPosition(ExcelCol.A, 1)
          .SetValue("Live Update!")
          .SetBackgroundColor(IndexedColors.LightGreen);
});

Run with dotnet watch

# Run in your Console project directory
dotnet watch run

Changes to your code will automatically trigger a reload and show the latest result in LibreOffice.

📖 API Overview

🤝 Contribution

Issues and Pull Requests are welcome!

📄 License

MIT License - See LICENSE file.