https://github.com/fivefish130/html2excel-richtext

A production-ready Java library for converting HTML to Excel rich text with full styling support (colors, fonts, hyperlinks, images). Extracted from enterprise applications with clean architecture.
https://github.com/fivefish130/html2excel-richtext

apache-poi data-export excel html-converter html-to-excel java jsoup poi rich-text spreadsheet xlsx

Last synced: 3 months ago
JSON representation

A production-ready Java library for converting HTML to Excel rich text with full styling support (colors, fonts, hyperlinks, images). Extracted from enterprise applications with clean architecture.

Host: GitHub
URL: https://github.com/fivefish130/html2excel-richtext
Owner: fivefish130
License: apache-2.0
Created: 2025-11-08T12:09:11.000Z (3 months ago)
Default Branch: main
Last Pushed: 2025-11-08T13:23:33.000Z (3 months ago)
Last Synced: 2025-11-08T15:11:35.553Z (3 months ago)
Topics: apache-poi, data-export, excel, html-converter, html-to-excel, java, jsoup, poi, rich-text, spreadsheet, xlsx
Language: Java
Size: 45.9 KB
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

          # 📊 HTML to Excel Rich Text Converter



  English | 简体中文





  Features •

  Quick Start •

  Modules •

  Examples •

  Contributing



---

## 🌟 Why This Library?

Apache POI is great for creating Excel files, but converting HTML to rich text with proper styling is surprisingly difficult. This library fills that gap with:

- ✅ **Production-Ready**: Refactored from real enterprise applications

- ✅ **Feature-Complete**: Supports colors, fonts, backgrounds, hyperlinks, images, lists, tables

- ✅ **High Performance**: Font/style caching, async image downloading

- ✅ **Fault-Tolerant**: Auto-fixes malformed HTML using Jsoup

- ✅ **Well-Architected**: Clean code with SOLID principles

- ✅ **Well-Tested**: Comprehensive unit tests

## 🎯 Features

### Rich Text Styling

- **Bold/Italic/Underline**: ``, ``, ``, ``, ``

- **Colors**: `#hex`, `rgb()`, named colors (red, blue, etc.)

- **Fonts**: Font family and size support

- **CSS Parsing**: Inline `style` attribute support


### Advanced Features

- **List Support**: `
`, ``, `` with automatic bullets/numbers

- **Table Support**: ``, ``, `` converted to text table format

- **Cell Backgrounds**: Maps `background-color` to Excel fill

- **Hyperlinks**: Auto-extract `` tags

- **Image Embedding**: Download and embed images from `` (async/parallel)

- **Long Text Handling**: Auto-truncate texts >32,767 characters

### Enterprise-Grade

- **Caching**: Font/style caching to control Excel object count

- **Thread-Safe**: Concurrent maps for caching

- **Configurable**: Flexible timeout, truncation, and cache settings

- **Pure Java**: No native dependencies

## 📦 Installation

### Maven

```xml

    io.github.fivefish130

    html2excel-richtext-core

    1.0.0

    io.github.fivefish130

    html2excel-richtext-jxls

    1.0.0

    io.github.fivefish130

    html2excel-richtext-easyexcel

    1.0.0

```

### Gradle

```gradle

// Core module

implementation 'io.github.fivefish130:html2excel-richtext-core:1.0.0'

// JXLS integration (optional)

implementation 'io.github.fivefish130:html2excel-richtext-jxls:1.0.0'

// EasyExcel integration (optional)

implementation 'io.github.fivefish130:html2excel-richtext-easyexcel:1.0.0'

```

## 🚀 Quick Start

### Basic Usage (Core)

```java

import io.github.fivefish130.html2excel.richtext.HtmlToExcelConverter;

import org.apache.poi.xssf.usermodel.*;

// Create workbook

XSSFWorkbook workbook = new XSSFWorkbook();

XSSFSheet sheet = workbook.createSheet("Demo");

XSSFCell cell = sheet.createRow(0).createCell(0);

// Convert HTML to Excel

HtmlToExcelConverter converter = new HtmlToExcelConverter(workbook);

String html = "
Bold Italic Red";

converter.applyHtmlToCell(cell, html);

// Save

try (FileOutputStream fos = new FileOutputStream("output.xlsx")) {

    workbook.write(fos);

}

```

## 📦 Modules

### Core Module

Core HTML to Excel rich text converter

```xml

    io.github.fivefish130

    html2excel-richtext-core

    1.0.0

```

### JXLS Integration

Use HTML conversion in JXLS templates

```java

// In Excel template comment:

// jx:html(lastCell="A1" value="product.description")

Context context = new Context();

context.putVar("product", product);

JxlsHtmlHelper.processTemplate(

    templateInputStream,

    outputStream,

    context

);

```

### EasyExcel Integration

Auto-convert HTML fields using annotations

```java

public class Product {

    private String name;

    @HtmlCell

    private String description;  // Auto converted from HTML to rich text

    @HtmlCell(enableImageDownload = true)

    private String detailedInfo;

}

// Usage

EasyExcel.write(file, Product.class)

    .registerWriteHandler(new HtmlCellWriteHandler())

    .sheet("Products")

    .doWrite(dataList);

```

## 💡 Examples

### Running Complete Examples

The `html2excel-richtext-examples` module contains **complete, runnable examples** for all features:

```bash

# Clone and build

git clone https://github.com/fivefish130/html2excel-richtext.git

cd html2excel-richtext/html2excel-richtext-examples

# Run Core examples (generates 7 Excel files)

mvn exec:java -Dexec.mainClass="io.github.fivefish130.html2excel.richtext.examples.CoreExample"

# Run EasyExcel examples

mvn exec:java -Dexec.mainClass="io.github.fivefish130.html2excel.richtext.examples.EasyExcelExample"

# Run JXLS examples

mvn exec:java -Dexec.mainClass="io.github.fivefish130.html2excel.richtext.examples.JxlsExample"

```

**See** [html2excel-richtext-examples/README.md](html2excel-richtext-examples/README.md) **for details**

### Code Examples

#### HTML with Lists

```java

String html =

    "
" +

    "  First item" +

    "  Second item" +

    "  Third item" +

    "";

converter.applyHtmlToCell(cell, html);

```

**Result**:

```

• First item

• Second item

• Third item

```

### HTML with Tables

```java

String html =

    "" +

    "  NameAge" +

    "  John25" +

    "";

converter.applyHtmlToCell(cell, html);

```

**Result**:

```

Name | Age

John | 25

```

### With Background Color

```java

String html = "
Highlighted Text";

converter.applyHtmlToCell(cell, html);

```

### With Hyperlinks

```java

String html = "Visit GitHub";

converter.applyHtmlToCell(cell, html);

// Cell becomes clickable link in Excel

```

### With Images (Async Download)

```java

ConverterConfig config = ConverterConfig.builder()

    .enableImageDownload(true)

    .imageTimeout(5000, 15000)

    .build();

HtmlToExcelConverter converter = new HtmlToExcelConverter(workbook, config);

String html = "";

converter.applyHtmlToCell(cell, html);

// Images downloaded asynchronously and embedded in cell

```

### Advanced Configuration

```java

ConverterConfig config = ConverterConfig.builder()

    .enableImageDownload(true)

    .imageTimeout(5000, 15000)  // Connect/read timeout

    .maxCellLength(30000)        // Custom max length

    .truncateSuffix("...")       // Custom truncation suffix

    .build();

HtmlToExcelConverter converter = new HtmlToExcelConverter(workbook, config);

```

## 🎨 Supported HTML & CSS

| Feature | Tag/CSS | Example |

|---------|---------|---------|

| Bold | ``, `` | `Bold` |

| Italic | ``, `` | `Italic` |

| Underline | `` | `Underline` |

| Color | `style="color:..."` | `color:#FF0000` / `rgb(255,0,0)` / `red` |

| Font | `style="font-family:..."` | `font-family:Arial` |

| Size | `style="font-size:..."` | `font-size:14px` / `12pt` |

| Background | `style="background-color:..."` | `background-color:#FFFF00` |

| Link | `` | `text` |

| Image | `` | `` |

| Break | `
`, `
` | `
`, `


...` |

| List | ``, ``, `` | `item` |

| Table | ``, ``, `` | `...` |

## 🏗️ Architecture

### Core Module

```

HtmlToExcelConverter (Facade)

├── Config (ConverterConfig)

├── Parser

│   ├── CssParser

│   ├── ColorParser

│   └── HtmlTraverser (List/Table support)

├── Cache

│   ├── FontCache

│   └── StyleCache

├── Builder (FontBuilder)

└── Handler

    ├── BackgroundHandler

    ├── HyperlinkHandler

    └── ImageHandler (Async download)

```

### Multi-Module Structure

```

html2excel-richtext/

├── html2excel-richtext-core/        # Core converter

├── html2excel-richtext-jxls/        # JXLS integration

├── html2excel-richtext-easyexcel/   # EasyExcel integration

└── html2excel-richtext-examples/    # Example code

```

## 🔧 Requirements

- **Java**: 8 or higher

- **Apache POI**: 5.0 or higher

- **Jsoup**: 1.14 or higher

## 📊 Performance

Benchmarks on converting 1000 HTML snippets to Excel cells:

| Metric | Value |

|--------|-------|

| Throughput | ~5000 cells/sec |

| Memory | ~50MB heap |

| Font Cache Hit Rate | >95% |

| Style Cache Hit Rate | >90% |

| Image Download | Async/Parallel |

## 🤝 Contributing

Contributions welcome! Please:

1. Fork the repository

2. Create your feature branch (`git checkout -b feature/amazing-feature`)

3. Commit your changes (`git commit -m 'Add amazing feature'`)

4. Push to the branch (`git push origin feature/amazing-feature`)

5. Open a Pull Request

## 📄 License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

## 🙏 Credits

This library was extracted and refactored from a real-world enterprise application.

## 📮 Contact

- Issues: [GitHub Issues](https://github.com/fivefish130/html2excel-richtext/issues)

- Discussions: [GitHub Discussions](https://github.com/fivefish130/html2excel-richtext/discussions)

## ⭐ Star History

If you find this library useful, please give it a star! ⭐

---

**Made with ❤️ by fivefish130**

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/fivefish130/html2excel-richtext

Awesome Lists containing this project

README