{"id":32860889,"url":"https://github.com/fivefish130/html2excel-richtext","last_synced_at":"2025-11-08T20:02:42.910Z","repository":{"id":323166187,"uuid":"1092320733","full_name":"fivefish130/html2excel-richtext","owner":"fivefish130","description":"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.","archived":false,"fork":false,"pushed_at":"2025-11-08T13:23:33.000Z","size":47,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-08T15:11:35.553Z","etag":null,"topics":["apache-poi","data-export","excel","html-converter","html-to-excel","java","jsoup","poi","rich-text","spreadsheet","xlsx"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fivefish130.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-08T12:09:11.000Z","updated_at":"2025-11-08T13:24:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fivefish130/html2excel-richtext","commit_stats":null,"previous_names":["fivefish130/html2excel-richtext"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fivefish130/html2excel-richtext","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivefish130%2Fhtml2excel-richtext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivefish130%2Fhtml2excel-richtext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivefish130%2Fhtml2excel-richtext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivefish130%2Fhtml2excel-richtext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fivefish130","download_url":"https://codeload.github.com/fivefish130/html2excel-richtext/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fivefish130%2Fhtml2excel-richtext/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283410685,"owners_count":26831444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-08T02:00:06.281Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache-poi","data-export","excel","html-converter","html-to-excel","java","jsoup","poi","rich-text","spreadsheet","xlsx"],"created_at":"2025-11-08T20:01:26.532Z","updated_at":"2025-11-08T20:02:42.904Z","avatar_url":"https://github.com/fivefish130.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📊 HTML to Excel Rich Text Converter\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eEnglish\u003c/b\u003e | \u003ca href=\"README_CN.md\"\u003e简体中文\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#modules\"\u003eModules\u003c/a\u003e •\n  \u003ca href=\"#examples\"\u003eExamples\u003c/a\u003e •\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 🌟 Why This Library?\n\nApache 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:\n\n- ✅ **Production-Ready**: Refactored from real enterprise applications\n- ✅ **Feature-Complete**: Supports colors, fonts, backgrounds, hyperlinks, images, lists, tables\n- ✅ **High Performance**: Font/style caching, async image downloading\n- ✅ **Fault-Tolerant**: Auto-fixes malformed HTML using Jsoup\n- ✅ **Well-Architected**: Clean code with SOLID principles\n- ✅ **Well-Tested**: Comprehensive unit tests\n\n## 🎯 Features\n\n### Rich Text Styling\n- **Bold/Italic/Underline**: `\u003cb\u003e`, `\u003cstrong\u003e`, `\u003ci\u003e`, `\u003cem\u003e`, `\u003cu\u003e`\n- **Colors**: `#hex`, `rgb()`, named colors (red, blue, etc.)\n- **Fonts**: Font family and size support\n- **CSS Parsing**: Inline `style` attribute support\n\n### Advanced Features\n- **List Support**: `\u003cul\u003e`, `\u003col\u003e`, `\u003cli\u003e` with automatic bullets/numbers\n- **Table Support**: `\u003ctable\u003e`, `\u003ctr\u003e`, `\u003ctd\u003e` converted to text table format\n- **Cell Backgrounds**: Maps `background-color` to Excel fill\n- **Hyperlinks**: Auto-extract `\u003ca href\u003e` tags\n- **Image Embedding**: Download and embed images from `\u003cimg src\u003e` (async/parallel)\n- **Long Text Handling**: Auto-truncate texts \u003e32,767 characters\n\n### Enterprise-Grade\n- **Caching**: Font/style caching to control Excel object count\n- **Thread-Safe**: Concurrent maps for caching\n- **Configurable**: Flexible timeout, truncation, and cache settings\n- **Pure Java**: No native dependencies\n\n## 📦 Installation\n\n### Maven\n```xml\n\u003c!-- Core module --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.fivefish130\u003c/groupId\u003e\n    \u003cartifactId\u003ehtml2excel-richtext-core\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n\n\u003c!-- JXLS integration (optional) --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.fivefish130\u003c/groupId\u003e\n    \u003cartifactId\u003ehtml2excel-richtext-jxls\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n\n\u003c!-- EasyExcel integration (optional) --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.fivefish130\u003c/groupId\u003e\n    \u003cartifactId\u003ehtml2excel-richtext-easyexcel\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Gradle\n```gradle\n// Core module\nimplementation 'io.github.fivefish130:html2excel-richtext-core:1.0.0'\n\n// JXLS integration (optional)\nimplementation 'io.github.fivefish130:html2excel-richtext-jxls:1.0.0'\n\n// EasyExcel integration (optional)\nimplementation 'io.github.fivefish130:html2excel-richtext-easyexcel:1.0.0'\n```\n\n## 🚀 Quick Start\n\n### Basic Usage (Core)\n\n```java\nimport io.github.fivefish130.html2excel.richtext.HtmlToExcelConverter;\nimport org.apache.poi.xssf.usermodel.*;\n\n// Create workbook\nXSSFWorkbook workbook = new XSSFWorkbook();\nXSSFSheet sheet = workbook.createSheet(\"Demo\");\nXSSFCell cell = sheet.createRow(0).createCell(0);\n\n// Convert HTML to Excel\nHtmlToExcelConverter converter = new HtmlToExcelConverter(workbook);\nString html = \"\u003cp\u003e\u003cb\u003eBold\u003c/b\u003e \u003ci\u003eItalic\u003c/i\u003e \u003cspan style='color:red'\u003eRed\u003c/span\u003e\u003c/p\u003e\";\nconverter.applyHtmlToCell(cell, html);\n\n// Save\ntry (FileOutputStream fos = new FileOutputStream(\"output.xlsx\")) {\n    workbook.write(fos);\n}\n```\n\n## 📦 Modules\n\n### Core Module\nCore HTML to Excel rich text converter\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.fivefish130\u003c/groupId\u003e\n    \u003cartifactId\u003ehtml2excel-richtext-core\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### JXLS Integration\nUse HTML conversion in JXLS templates\n\n```java\n// In Excel template comment:\n// jx:html(lastCell=\"A1\" value=\"product.description\")\n\nContext context = new Context();\ncontext.putVar(\"product\", product);\n\nJxlsHtmlHelper.processTemplate(\n    templateInputStream,\n    outputStream,\n    context\n);\n```\n\n### EasyExcel Integration\nAuto-convert HTML fields using annotations\n\n```java\npublic class Product {\n    private String name;\n\n    @HtmlCell\n    private String description;  // Auto converted from HTML to rich text\n\n    @HtmlCell(enableImageDownload = true)\n    private String detailedInfo;\n}\n\n// Usage\nEasyExcel.write(file, Product.class)\n    .registerWriteHandler(new HtmlCellWriteHandler())\n    .sheet(\"Products\")\n    .doWrite(dataList);\n```\n\n## 💡 Examples\n\n### Running Complete Examples\nThe `html2excel-richtext-examples` module contains **complete, runnable examples** for all features:\n\n```bash\n# Clone and build\ngit clone https://github.com/fivefish130/html2excel-richtext.git\ncd html2excel-richtext/html2excel-richtext-examples\n\n# Run Core examples (generates 7 Excel files)\nmvn exec:java -Dexec.mainClass=\"io.github.fivefish130.html2excel.richtext.examples.CoreExample\"\n\n# Run EasyExcel examples\nmvn exec:java -Dexec.mainClass=\"io.github.fivefish130.html2excel.richtext.examples.EasyExcelExample\"\n\n# Run JXLS examples\nmvn exec:java -Dexec.mainClass=\"io.github.fivefish130.html2excel.richtext.examples.JxlsExample\"\n```\n\n**See** [html2excel-richtext-examples/README.md](html2excel-richtext-examples/README.md) **for details**\n\n### Code Examples\n\n#### HTML with Lists\n\n```java\nString html =\n    \"\u003cul\u003e\" +\n    \"  \u003cli\u003eFirst item\u003c/li\u003e\" +\n    \"  \u003cli\u003eSecond item\u003c/li\u003e\" +\n    \"  \u003cli\u003eThird item\u003c/li\u003e\" +\n    \"\u003c/ul\u003e\";\nconverter.applyHtmlToCell(cell, html);\n```\n\n**Result**:\n```\n• First item\n• Second item\n• Third item\n```\n\n### HTML with Tables\n\n```java\nString html =\n    \"\u003ctable\u003e\" +\n    \"  \u003ctr\u003e\u003ctd\u003eName\u003c/td\u003e\u003ctd\u003eAge\u003c/td\u003e\u003c/tr\u003e\" +\n    \"  \u003ctr\u003e\u003ctd\u003eJohn\u003c/td\u003e\u003ctd\u003e25\u003c/td\u003e\u003c/tr\u003e\" +\n    \"\u003c/table\u003e\";\nconverter.applyHtmlToCell(cell, html);\n```\n\n**Result**:\n```\nName | Age\nJohn | 25\n```\n\n### With Background Color\n```java\nString html = \"\u003cp style='background-color:#FFFF00'\u003eHighlighted Text\u003c/p\u003e\";\nconverter.applyHtmlToCell(cell, html);\n```\n\n### With Hyperlinks\n```java\nString html = \"\u003ca href='https://github.com'\u003eVisit GitHub\u003c/a\u003e\";\nconverter.applyHtmlToCell(cell, html);\n// Cell becomes clickable link in Excel\n```\n\n### With Images (Async Download)\n```java\nConverterConfig config = ConverterConfig.builder()\n    .enableImageDownload(true)\n    .imageTimeout(5000, 15000)\n    .build();\n\nHtmlToExcelConverter converter = new HtmlToExcelConverter(workbook, config);\nString html = \"\u003cimg src='https://example.com/logo.png'/\u003e\";\nconverter.applyHtmlToCell(cell, html);\n// Images downloaded asynchronously and embedded in cell\n```\n\n### Advanced Configuration\n```java\nConverterConfig config = ConverterConfig.builder()\n    .enableImageDownload(true)\n    .imageTimeout(5000, 15000)  // Connect/read timeout\n    .maxCellLength(30000)        // Custom max length\n    .truncateSuffix(\"...\")       // Custom truncation suffix\n    .build();\n\nHtmlToExcelConverter converter = new HtmlToExcelConverter(workbook, config);\n```\n\n## 🎨 Supported HTML \u0026 CSS\n\n| Feature | Tag/CSS | Example |\n|---------|---------|---------|\n| Bold | `\u003cb\u003e`, `\u003cstrong\u003e` | `\u003cb\u003eBold\u003c/b\u003e` |\n| Italic | `\u003ci\u003e`, `\u003cem\u003e` | `\u003ci\u003eItalic\u003c/i\u003e` |\n| Underline | `\u003cu\u003e` | `\u003cu\u003eUnderline\u003c/u\u003e` |\n| Color | `style=\"color:...\"` | `color:#FF0000` / `rgb(255,0,0)` / `red` |\n| Font | `style=\"font-family:...\"` | `font-family:Arial` |\n| Size | `style=\"font-size:...\"` | `font-size:14px` / `12pt` |\n| Background | `style=\"background-color:...\"` | `background-color:#FFFF00` |\n| Link | `\u003ca href=\"...\"\u003e` | `\u003ca href=\"url\"\u003etext\u003c/a\u003e` |\n| Image | `\u003cimg src=\"...\"\u003e` | `\u003cimg src=\"url\"/\u003e` |\n| Break | `\u003cbr\u003e`, `\u003cp\u003e` | `\u003cbr/\u003e`, `\u003cp\u003e...\u003c/p\u003e` |\n| List | `\u003cul\u003e`, `\u003col\u003e`, `\u003cli\u003e` | `\u003cul\u003e\u003cli\u003eitem\u003c/li\u003e\u003c/ul\u003e` |\n| Table | `\u003ctable\u003e`, `\u003ctr\u003e`, `\u003ctd\u003e` | `\u003ctable\u003e\u003ctr\u003e\u003ctd\u003e...\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e` |\n\n## 🏗️ Architecture\n\n### Core Module\n```\nHtmlToExcelConverter (Facade)\n├── Config (ConverterConfig)\n├── Parser\n│   ├── CssParser\n│   ├── ColorParser\n│   └── HtmlTraverser (List/Table support)\n├── Cache\n│   ├── FontCache\n│   └── StyleCache\n├── Builder (FontBuilder)\n└── Handler\n    ├── BackgroundHandler\n    ├── HyperlinkHandler\n    └── ImageHandler (Async download)\n```\n\n### Multi-Module Structure\n```\nhtml2excel-richtext/\n├── html2excel-richtext-core/        # Core converter\n├── html2excel-richtext-jxls/        # JXLS integration\n├── html2excel-richtext-easyexcel/   # EasyExcel integration\n└── html2excel-richtext-examples/    # Example code\n```\n\n## 🔧 Requirements\n\n- **Java**: 8 or higher\n- **Apache POI**: 5.0 or higher\n- **Jsoup**: 1.14 or higher\n\n## 📊 Performance\n\nBenchmarks on converting 1000 HTML snippets to Excel cells:\n\n| Metric | Value |\n|--------|-------|\n| Throughput | ~5000 cells/sec |\n| Memory | ~50MB heap |\n| Font Cache Hit Rate | \u003e95% |\n| Style Cache Hit Rate | \u003e90% |\n| Image Download | Async/Parallel |\n\n## 🤝 Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nApache License 2.0 - see [LICENSE](LICENSE) for details.\n\n## 🙏 Credits\n\nThis library was extracted and refactored from a real-world enterprise application.\n\n## 📮 Contact\n\n- Issues: [GitHub Issues](https://github.com/fivefish130/html2excel-richtext/issues)\n- Discussions: [GitHub Discussions](https://github.com/fivefish130/html2excel-richtext/discussions)\n\n## ⭐ Star History\n\nIf you find this library useful, please give it a star! ⭐\n\n---\n\n**Made with ❤️ by fivefish130**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffivefish130%2Fhtml2excel-richtext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffivefish130%2Fhtml2excel-richtext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffivefish130%2Fhtml2excel-richtext/lists"}