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

Package	Purpose	Install
FluentNPOI.Pdf	PDF Export (QuestPDF)	dotnet add package FluentNPOI.Pdf
FluentNPOI.Streaming	Large File Streaming	dotnet add package FluentNPOI.Streaming
FluentNPOI.Charts	Chart Generation (ScottPlot)	dotnet add package FluentNPOI.Charts
FluentNPOI.HotReload	Live Preview (Dev only)	dotnet add package FluentNPOI.HotReload
FluentNPOI.All	Full Features (All modules)	dotnet add package FluentNPOI.All

🎯 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

Area	Key Methods
Mapping	Map, ToColumn, WithTitle, WithNumberFormat, WithBackgroundColor
Cell	SetValue, SetFormula, SetBackgroundColor, SetBorder, SetFont
Table	SetTable, BuildRows, SetAutoFilter, FreezeTitleRow, AutoSizeColumns
Streaming	StreamingBuilder.FromFile, Transform, SaveAs
Charts	AddBarChart, AddLineChart, AddPieChart, ChartBuilder
HotReload	FluentLivePreview.Run

---

🤝 Contribution

Issues and Pull Requests are welcome!

📄 License

MIT License - See LICENSE file.