FastExcel

一个功能完整的现代 C++17 Excel 文件处理库，采用高性能架构设计，支持完整Excel格式和CSV处理，专为高性能、大规模数据处理而设计。

🚀 核心特性

📊 完整的Excel格式支持

核心数据类型

• 所有Excel数据类型：数字、字符串、布尔、公式、日期时间、错误值、空值、超链接
• 共享公式优化：SharedFormula 和 SharedFormulaManager 自动检测相似公式模式
• 公式优化分析：内置公式优化潜力分析，提供内存节省报告

丰富的样式系统

• 字体样式：名称、大小、粗体、斜体、下划线、删除线、上下标、颜色、字体族
• 填充样式：纯色填充、渐变填充、图案填充（支持gray125等特殊图案）
• 边框样式：四边及对角线边框，多种线条样式和颜色
• 对齐方式：水平对齐、垂直对齐、文本换行、旋转、缩进、收缩适应
• 数字格式：内置和自定义数字格式，支持所有Excel格式代码
• 保护属性：单元格锁定和隐藏

工作表高级功能

• 合并单元格：完整的合并单元格支持和管理
• 自动筛选：数据筛选功能，支持复杂筛选条件
• 冻结窗格：行列冻结，支持多种冻结模式
• 打印设置：打印区域、重复行列、页面设置、边距、缩放
• 工作表保护：密码保护，选择性保护选项
• 视图设置：缩放、网格线、行列标题、从右到左显示

🖼️ 图片和媒体支持

• 图片插入：支持 PNG、JPEG、GIF、BMP 等主流图片格式
• 多种锚点类型：绝对定位、单元格锚定、双单元格锚定
• 图片属性控制：位置、大小、旋转、透明度调整
• 高性能处理：自动优化图片尺寸和压缩

📄 CSV数据处理

• 智能解析：自动检测分隔符、编码、数据类型
• 多种分隔符支持：逗号、分号、制表符、自定义分隔符
• 数据类型推断：自动识别数字、布尔值、日期、字符串
• 编码处理：完美支持UTF-8、GBK等中文编码，解决乱码问题
• 大文件支持：流式处理，支持超大CSV文件读取
• 灵活配置：丰富的解析选项和错误处理策略

🏗️ 现代架构设计

高性能样式系统

// 流畅样式构建器
auto style = workbook->createStyleBuilder()
    .font().name("Arial").size(12).bold(true).color(Color::BLUE)
    .fill().pattern(PatternType::Solid).fgColor(Color::LIGHT_GRAY)
    .border().all(BorderStyle::Thin, Color::BLACK)
    .alignment().horizontal(HorizontalAlign::Center)
    .build();

智能存储策略

• 样式去重：FormatRepository 自动检测和合并相同样式
• 共享字符串：SharedStringTable 优化重复字符串存储
• 内存池管理：减少内存分配开销
• 智能缓存：LRU缓存热点数据

📈 高性能优化

内存优化 ✨

• 智能指针架构：全面使用 std::unique_ptr 替代 raw pointers，消除内存泄漏
• RAII内存管理：ExtendedData 结构采用 RAII 原则，自动资源管理
• 紧凑Cell结构：24字节/Cell（vs 传统64字节+）
• 内联字符串：16字节以下字符串直接内联存储
• 位域压缩：使用位域减少标志位空间占用

处理速度优化 ✨

• 高性能XML流写：完全基于 XMLStreamWriter，消除字符串拼接开销
• 统一XML转义：XMLUtils::escapeXML() 提供优化的文本转义处理
• 批量操作：writeRange 支持批量数据写入
• 并行处理：多线程支持加速处理
• 流式处理：常量内存，大文件支持

🔄 OPC包编辑技术

• 增量编辑：支持修改现有Excel文件而不重新生成
• 保真写回：保留未修改部分的原始格式
• 变更跟踪：DirtyManager 精确跟踪修改部分
• 部件管理：智能管理OPC包的复杂依赖关系

📦 快速开始

系统要求

• C++17兼容编译器（GCC 7+, Clang 5+, MSVC 2017+）
• CMake 3.15+
• Windows/Linux/macOS

构建安装

# 克隆仓库
git clone https://github.com/wuxianggujun/FastExcel.git
cd FastExcel

# 配置构建
cmake -B cmake-build-debug -S .

# 编译项目
cmake --build cmake-build-debug

# 并行编译加速
cmake --build cmake-build-debug -j 4

# 运行示例程序
cd cmake-build-debug/bin/examples
./sheet_copy_with_format_example

💡 使用指南

创建Excel文件

#include "src/fastexcel/core/Workbook.hpp"
#include "src/fastexcel/core/Worksheet.hpp"
#include "src/fastexcel/core/Path.hpp"

using namespace fastexcel::core;

int main() {
    // 创建工作簿
    auto workbook = Workbook::create("demo.xlsx");
    
    // 添加工作表
    auto worksheet = workbook->addSheet("销售数据");
    
    // 写入表头
    worksheet->setValue(0, 0, std::string("产品名称"));
    worksheet->setValue(0, 1, std::string("数量"));
    worksheet->setValue(0, 2, std::string("单价"));
    worksheet->setValue(0, 3, std::string("总价"));
    
    // 写入数据
    worksheet->setValue(1, 0, std::string("笔记本电脑"));
    worksheet->setValue(1, 1, 10);
    worksheet->setValue(1, 2, 5999.99);
    
    // 写入公式
    worksheet->setFormula(1, 3, "B2*C2");
    
    // 保存文件
    workbook->save();
    return 0;
}

高级样式设置

#include "src/fastexcel/core/Workbook.hpp"
#include "src/fastexcel/core/StyleBuilder.hpp"

using namespace fastexcel::core;

int main() {
    auto workbook = Workbook::create("styled_report.xlsx");
    auto worksheet = workbook->addSheet("财务报表");
    
    // 创建标题样式
    auto titleStyle = workbook->createStyleBuilder()
        .font().name("微软雅黑").size(16).bold(true).color(Color::WHITE)
        .fill().pattern(PatternType::Solid).fgColor(Color::DARK_BLUE)
        .border().all(BorderStyle::Medium, Color::BLACK)
        .alignment().horizontal(HorizontalAlign::Center).vertical(VerticalAlign::Center)
        .build();
    
    // 应用样式
    int titleStyleId = workbook->addStyle(titleStyle);
    
    // 写入数据并设置样式
    worksheet->setValue(0, 0, std::string("2024年度财务报表"));
    worksheet->setCellStyle(0, 0, titleStyleId);
    
    workbook->save();
    return 0;
}

图片插入功能

#include "src/fastexcel/core/Workbook.hpp"
#include "src/fastexcel/core/Image.hpp"

using namespace fastexcel::core;

int main() {
    auto workbook = Workbook::create("image_report.xlsx");
    auto worksheet = workbook->addSheet("图片演示");
    
    // 插入图片 - 绝对定位
    auto image1 = std::make_unique<Image>("logo.png");
    image1->setPosition(100, 100);  // 设置位置
    image1->setSize(200, 150);      // 设置大小
    worksheet->insertImage(std::move(image1), AnchorType::Absolute);
    
    // 插入图片 - 单元格锚定
    auto image2 = std::make_unique<Image>("chart.jpg");
    worksheet->insertImage(std::move(image2), AnchorType::OneCell, 2, 1); // 锚定到C2单元格
    
    // 插入图片 - 双单元格锚定（图片会随单元格调整）
    auto image3 = std::make_unique<Image>("graph.png");
    worksheet->insertImage(std::move(image3), AnchorType::TwoCell, 5, 1, 8, 4); // 从F2到E9
    
    workbook->save();
    return 0;
}

CSV数据处理

#include "src/fastexcel/core/Workbook.hpp"
#include "src/fastexcel/core/CSVProcessor.hpp"

using namespace fastexcel::core;

int main() {
    // 从CSV文件创建Excel工作簿
    auto workbook = Workbook::create("data_analysis.xlsx");
    
    // 配置CSV解析选项
    CSVOptions options = CSVOptions::standard();
    options.has_header = true;           // 包含标题行
    options.auto_detect_delimiter = true; // 自动检测分隔符
    options.auto_detect_types = true;     // 自动推断数据类型
    options.encoding = "UTF-8";           // UTF-8编码支持中文
    
    // 从CSV文件加载数据
    auto worksheet = workbook->loadCSV("sales_data.csv", "销售数据", options);
    
    if (worksheet) {
        std::cout << "CSV数据加载成功！" << std::endl;
        
        // 获取数据范围
        auto [min_row, max_row, min_col, max_col] = worksheet->getUsedRangeFull();
        std::cout << "数据范围: " << max_row + 1 << " 行, " << max_col + 1 << " 列" << std::endl;
        
        // 导出为不同格式的CSV
        CSVOptions exportOptions = CSVOptions::europeanStyle(); // 欧洲格式（分号分隔）
        worksheet->saveAsCSV("sales_data_eu.csv", exportOptions);
        
        // 保存Excel文件
        workbook->save();
    }
    
    return 0;
}

读取Excel文件

#include "src/fastexcel/core/Workbook.hpp"

using namespace fastexcel::core;

int main() {
    // 打开现有Excel文件
    auto workbook = Workbook::open("input.xlsx");
    
    if (workbook) {
        // 获取第一个工作表
        auto worksheet = workbook->getSheet(0);
        
        if (worksheet) {
            auto [max_row, max_col] = worksheet->getUsedRange();
            
            // 遍历所有数据
            for (int row = 0; row <= max_row; ++row) {
                for (int col = 0; col <= max_col; ++col) {
                    if (worksheet->hasCellAt(row, col)) {
                        // 获取单元格显示值（自动处理各种数据类型）
                        std::string displayValue = worksheet->getCellDisplayValue(row, col);
                        std::cout << "(" << row << "," << col << "): " << displayValue << std::endl;
                    }
                }
            }
        }
        
        // 将指定工作表导出为CSV
        workbook->exportSheetAsCSV(0, "exported_data.csv");
    }
    
    return 0;
}

高性能批处理

#include "src/fastexcel/core/Workbook.hpp"

using namespace fastexcel::core;

int main() {
    // 配置高性能选项
    auto workbook = Workbook::create("big_data.xlsx");
    
    // 启用高性能模式
    workbook->setHighPerformanceMode(true);
    
    // 设置优化参数
    workbook->setRowBufferSize(10000);          // 大行缓冲
    workbook->setCompressionLevel(6);           // 平衡压缩
    workbook->setXMLBufferSize(8 * 1024 * 1024); // 8MB XML缓冲
    
    auto worksheet = workbook->addSheet("大数据表");
    
    // 批量写入大量数据
    for (int i = 0; i < 100000; ++i) {
        worksheet->setValue(i, 0, i + 1);          // 序号
        worksheet->setValue(i, 1, "数据" + std::to_string(i)); // 文本
        worksheet->setValue(i, 2, i * 1.5);        // 计算值
        
        if (i % 10000 == 0) {
            std::cout << "已处理 " << i << " 行数据" << std::endl;
        }
    }
    
    // 获取性能统计
    auto stats = workbook->getStatistics();
    std::cout << "内存使用: " << stats.memory_usage / (1024*1024) << " MB" << std::endl;
    std::cout << "单元格总数: " << stats.total_cells << std::endl;
    
    workbook->save();
    return 0;
}

📊 性能指标

指标	FastExcel	传统库	提升幅度
内存效率	24字节/Cell	64字节+/Cell	62% ↓
样式去重	自动去重	重复存储	50-80% ↓
文件大小	优化压缩	标准压缩	15-30% ↓
处理速度	并行+缓存	单线程	3-5x ↑
大文件支持	常量内存	线性增长	无限制

实际测试数据

测试环境：Intel i7-12700K, 32GB RAM, Windows 11
数据集：100万行 x 10列，包含数字、文本、公式

                  FastExcel    传统库      提升
文件生成时间：      8.5秒       28.2秒     3.3x
内存占用峰值：      125MB       680MB      81% ↓
输出文件大小：      45MB        62MB       27% ↓
样式数量（去重后）：  156         2847       95% ↓

🔧 完整功能清单

📝 数据类型支持

• ✅ 数字：整数、浮点数、科学计数法
• ✅ 字符串：Unicode支持、富文本
• ✅ 布尔值：TRUE/FALSE
• ✅ 公式：所有Excel函数、共享公式优化
• ✅ 日期时间：完整的Excel日期系统
• ✅ 错误值：#DIV/0!, #N/A, #VALUE! 等
• ✅ 超链接：URL、邮箱、内部引用

🎨 样式系统

• ✅ 字体：名称、大小、粗体、斜体、下划线、删除线、颜色
• ✅ 填充：纯色、渐变、图案填充（gray125等特殊图案）
• ✅ 边框：四边框线、对角线、多种样式和颜色
• ✅ 对齐：水平、垂直、换行、旋转、缩进
• ✅ 数字格式：内置格式、自定义格式代码
• ✅ 保护：锁定、隐藏属性

🖼️ 图片和媒体

• ✅ 图片格式：PNG、JPEG、GIF、BMP、TIFF
• ✅ 锚点类型：绝对定位、单元格锚定、双单元格锚定
• ✅ 图片操作：位置调整、大小缩放、旋转变换
• ✅ 性能优化：自动压缩、格式转换、内存管理

📄 CSV数据处理

• ✅ 智能解析：自动检测分隔符（逗号、分号、制表符）
• ✅ 编码支持：UTF-8、GBK、ASCII，自动检测和转换
• ✅ 类型推断：数字、布尔值、日期、字符串自动识别
• ✅ 大文件支持：流式处理，支持GB级CSV文件
• ✅ 错误处理：完善的错误报告和恢复机制
• ✅ 双向转换：Excel ↔ CSV 无缝转换

📊 工作表功能

• ✅ 基本操作：添加、删除、重命名、移动、复制
• ✅ 合并单元格：合并、拆分、范围管理
• ✅ 自动筛选：数据筛选、高级筛选
• ✅ 冻结窗格：行列冻结、分割窗格
• ✅ 打印设置：打印区域、重复行列、页面设置
• ✅ 工作表保护：密码保护、选择性保护
• ✅ 视图设置：缩放、网格线、标题显示

🔧 高级功能

• ✅ OPC包编辑：增量修改、保真写回
• ✅ 变更跟踪：精确跟踪修改部分
• ✅ 主题支持：完整的Excel主题系统
• ✅ 定义名称：命名区域、公式常量
• ✅ 文档属性：核心属性、自定义属性
• ✅ VBA项目：保留和传输VBA代码
• ✅ 工作簿保护：结构保护、窗口保护

⚡ 性能优化

• ✅ 内存优化：紧凑数据结构、内存池
• ✅ 缓存系统：LRU缓存、智能预取
• ✅ 并行处理：多线程支持、任务队列
• ✅ 压缩优化：多种压缩引擎、自适应压缩
• ✅ 流式处理：常量内存、大文件支持

🧪 示例程序

项目提供了完整的示例程序集：

基础功能

• examples/basic_usage.cpp - 基本读写操作
• examples/cell_types_example.cpp - 各种数据类型
• examples/batch_operations.cpp - 批量操作

样式和格式

• examples/formatting_example.cpp - 完整样式演示
• examples/style_builder_example.cpp - 样式构建器
• examples/theme_colors_example.cpp - 主题颜色系统

图片处理

• examples/image_insertion_demo.cpp - 图片插入完整演示
• examples/quick_image_example.cpp - 快速图片插入示例
• examples/test_image_fix.cpp - 图片处理测试

CSV数据处理

• examples/test_csv_functionality.cpp - CSV功能完整测试
• test_csv_edge_cases.cpp - CSV边界情况测试

高级功能

• examples/formulas_and_shared.cpp - 公式和共享公式
• examples/sheet_copy_with_format_example.cpp - 带格式复制
• examples/high_performance_edit_example.cpp - 高性能编辑

🔍 调试和诊断

完整的日志系统

#include "fastexcel/utils/Logger.hpp"

// 配置日志
Logger::setLevel(LogLevel::DEBUG);
Logger::setOutputFile("fastexcel_debug.log");

// 使用便捷宏
LOG_INFO("处理工作表: {}", sheetName);
LOG_DEBUG("单元格({}, {}): 类型={}, 值={}", row, col, type, value);
LOG_WARN("样式ID{}未找到，使用默认样式", styleId);
LOG_ERROR("文件写入失败: {}", errorMsg);

性能诊断工具

// 获取详细性能统计
auto stats = workbook->getStatistics();
std::cout << "工作表数量: " << stats.total_worksheets << std::endl;
std::cout << "单元格总数: " << stats.total_cells << std::endl;
std::cout << "样式数量: " << stats.total_formats << std::endl;
std::cout << "内存使用: " << stats.memory_usage << " 字节" << std::endl;

// 样式去重统计
auto deduplicationStats = workbook->getStyleStats();
std::cout << "样式去重比率: " << deduplicationStats.deduplication_ratio << std::endl;

📚 完整文档

快速入门

• 📖 快速开始指南 - 5分钟上手教程
• 🔧 安装配置指南 - 详细的安装和配置说明
• 💡 示例代码 - 完整的代码示例和最佳实践

API文档

• 📚 核心API参考 - 完整的API文档
• 🏗️ 架构设计文档 - 深入理解架构设计
• ⚡ 性能优化指南 - 性能调优最佳实践

完整文档中心

访问 📚 文档中心 查看所有文档

🤝 社区和支持

贡献指南

1. 📋 贡献指南 - 如何参与项目
2. 📝 代码规范 - 代码风格和规范
3. 🐛 问题报告 - 报告bug和建议
4. 💬 讨论区 - 技术讨论

开发环境

# 完整开发环境配置
cmake -B build -S . \
  -DFASTEXCEL_BUILD_EXAMPLES=ON \
  -DFASTEXCEL_BUILD_TESTS=ON \
  -DFASTEXCEL_BUILD_UNIT_TESTS=ON \
  -DCMAKE_BUILD_TYPE=Debug

# 构建并运行测试
cmake --build build --parallel 4
cd build && ctest -V --parallel 4

🎯 路线图

已完成 ✅

• 完整Excel格式支持
• 高性能内存管理
• 图片插入功能
• CSV数据处理
• OPC包编辑技术
• 共享公式优化
• 主题系统支持
• 性能监控工具

开发中 🚧

• Web Assembly支持
• Python绑定
• 图表和绘图对象支持
• 宏和VBA编辑器
• 云存储集成

计划中 📋

• 实时协作功能
• 数据透视表支持
• 条件格式高级功能
• Excel插件开发SDK

📄 许可证和版权

FastExcel 采用 MIT许可证，允许商业和开源使用。详细信息请查看 LICENSE 文件。

🙏 致谢和依赖

FastExcel基于以下优秀的开源项目构建：

核心依赖

• minizip-ng - 高性能ZIP文件处理
• libexpat - 快速XML解析器
• fmt - 现代C++字符串格式化
• spdlog - 高性能日志库

特别感谢

• Microsoft Office Open XML 规范团队
• Excel文件格式研究社区
• 所有贡献者和用户反馈

---

FastExcel - 让Excel处理变得简单高效 ⚡

🚀 快速开始 • 📚 完整文档 • 💡 示例代码 • 🤝 参与贡献