QXlsx开发笔记（二）：QXlsx基本数据结构解说以及单元格Cell边框操作

若该文为原创文章，转载请注明原文出处

本文章博客地址：https://hpzwl.blog.csdn.net/article/details/156397531

长沙红胖子Qt（长沙创微智科）博文大全：开发技术集合（包含Qt实用技术、树莓派、三维、OpenCV、OpenGL、ffmpeg、OSG、单片机、软硬结合等等）持续更新中...

Qt开发专栏：三方库开发技术

上一篇：《QXlsx开发笔记（一）：QXlsx介绍、编译和使用》

下一篇：敬请期待...

前言

QXlsx的基本数据结构解析。

Demo效果

QXlsx数据结构

QXlsx采用三层级树形结构组织Excel数据，从上到下依次为：

Document（工作簿）→ Worksheet（工作表）→ Cell（单元格）

三者是包含与被包含的关系，共同构成 Excel 文件的完整数据载体。

顶层：Document 类（Excel 工作簿 / 文档）

QXlsx::Document是QXlsx的顶层核心类，对应一个完整的Excel工作簿文件（.xlsx 格式），负责管理整个Excel文件的生命周期和全局资源。

核心作用：承载多个工作表（Worksheet）、统一管理文件的创建/读取/保存/关闭，以及全局样式、属性配置等。
关键特性：一个Document实例对应一个Excel文件，可通过它新增、删除、切换工作表，是操作Excel的入口类。

中间层：Worksheet类（工作表）

QXlsx::Worksheet对应Excel中的单个工作表（如Sheet1、Sheet2），是单元格（Cell）的容器，负责组织和管理工作表内的所有数据和格式。

核心作用：维护单元格的二维分布、工作表名称、行高列宽、打印设置等工作表级配置，是单元格操作的直接上下文。
关键特性：一个Document包含多个Worksheet，通过工作表名称或索引可获取对应的Worksheet实例。

底层：Cell类（单元格）

QXlsx::Cell 对应 Excel 中的单个单元格（如 A1、B3），是存储数据和格式的最小单元，所有具体的单元格数据（值、类型、样式）都封装在该类中。

核心作用：存储单元格的原始数据、数据类型（文本 / 数字 / 日期等）、单元格样式（字体 / 颜色 / 边框等），以及单元格的位置信息（行号、列号）。
关键特性：Cell 实例依赖于 Worksheet 存在，无法脱离工作表独立创建。
这个结构对于我们操作excel来说，基本都是只操作底层单元格。

单元格Cell的操作

对于表格的操作，常规分为几大类操作，我们以操作目标为方向，进行归类：

单元格的边框

依赖QXlsx::Format核心类，通过setBorderStyle()和setBroderColor()等接口实现边框的操作，边框样式/颜色通过 Format 定义，支持细/粗/虚线，可单独设置上下左右边框。

单元格的底色

依赖QXlsx::Format核心类，通过setPatternBackgroundColor()和setPatternType()等接口实现，底色需指定"填充类型+颜色"，PatternSolid 为纯色填充（最常用）。

单元格的高度和宽度

依赖QXlsx:Worksheet核心类，通过setRowHeight ()和setColumnWidth ()等接口实现，行高/列宽属于工作表级配置，单位为"磅"（Excel 通用单位），支持批量设置列宽。

单元格的合并与分开

依赖QXlsx:Worksheet核心类，通过mergeCells ()和unmergeCells ()等接口实现，合并和拆分单元格，属于工作表级配置，合并仅左上角保留值；取消合并后原区域单元格恢复为空。

单元格的字体样式

依赖QXlsx::Format核心类，通过setFontName()、setFontSize()和setFontBold()等接口实现，字体名称/大小/加粗/颜色/斜体均封装在Format中，可复用。

单元格插入图片

依赖QXlsx::Document/Worksheet核心类，通过insertImage()接口实现。图片锚定到指定单元格，支持设置宽高，路径需为绝对/可执行文件相对路径。

边框操作Demo

步骤一：新建xlsx（QXlsx框架）

新建xlsx进行保存是QXlsx的基础框架：

可以直接存储，默认是：

打开会提示容错，确认是没有worksheet，下面的既不会报错，有一个活动的sheet了：

步骤二：获取到指定单元格

这个方式在当前的社区版本是不行的，cell返回只有智能指针，且cell接口只有获取和读取，没有设置相关的接口，这个跟版本密切相关吧。

通过worksheet写入空白格式才可以（这个版本也没有直接设置，遇到有内容的，就先读取，再写入规避吧）。

步骤三：对指定的单元格进行边框设置

步骤四：保存xlsx

步骤五：使用office开打excel查看

Demo源码

cpp 复制代码

void XlsxManager::testDemo1()
{
    // 步骤一：创建表格
    Document document;
//    document.save();
    // 步骤二：获取当前操作表（若程序新建xlsx，必须调用才会有worksheet，不调用office打开没worksheet)
    Worksheet *pWorksheet = document.currentWorksheet();
#if 0
    // 步骤三：获取指定单元格（注意：这个社区版本，只有std::shared_ptr的cellAt接口）,且连设置文本接口都没有
    std::shared_ptr<Cell> pCell1 = pWorksheet->cellAt(0, 0);
#endif
    // 步骤三: 直接通过worksheet操作单元格边框,需要设置边框样式和边框颜色
    {
        // 设置单个单元格： 边框样式 颜色
        {
            QXlsx::Format format;
            // 设置边框样式
            format.setBorderStyle(Format::BorderMedium);
            format.setBorderColor(Qt::blue);
            // 这里是writeBlank（注意：本版本没有setFormat)
            pWorksheet->writeBlank(2, 2, format);
        }
        // 设置单个单元格： 边框样式 颜色
        {
            QXlsx::Format format;
            // 设置边框样式
            format.setBorderStyle(Format::BorderDashDotDot);
            format.setBorderColor(Qt::red);
            // 这里是writeBlank（注意：本版本没有setFormat)
            pWorksheet->writeBlank(2, 4, format);
        }
        // 设置单个单元格： 边框样式 颜色
        {
            QXlsx::Format format;
            // 设置边框样式
            format.setTopBorderStyle(Format::BorderThick);
            format.setTopBorderColor(Qt::red);
            // 这里是writeBlank（注意：本版本没有setFormat)
            pWorksheet->writeBlank(2, 6, format);
        }
        // 设置单个单元格： 边框样式 颜色
        {
            QXlsx::Format format;
            // 设置边框样式
            format.setBottomBorderStyle(Format::BorderThick);
            format.setBottomBorderColor(Qt::red);
            // 这里是writeBlank（注意：本版本没有setFormat)
            pWorksheet->writeBlank(2, 8, format);
        }
        // 设置一行
        {
            QXlsx::Format format;
            // 设置边框样式
            format.setBottomBorderStyle(Format::BorderThick);
            format.setBottomBorderColor(Qt::red);
            // 这里是writeBlank（注意：本版本没有setFormat)
            pWorksheet->setRowFormat(4, 4, format);
        }
        // 设置一列(入坑，这个接口会直接将该2列给缩放到最小宽度，需要拉开）
        {
            QXlsx::Format format;
            // 设置边框样式
            format.setBottomBorderStyle(Format::BorderThick);
            format.setBottomBorderColor(Qt::green);
            // 这里是writeBlank（注意：本版本没有setFormat)
            pWorksheet->setColumnFormat(10, 11, format);
        }
        // 设置一列(入坑，这个接口会直接将该2列给缩放到最小宽度，需要拉开,发现这个接口：列都会宽小，但是行不会）
        {
            QXlsx::Format format;
            // 设置边框样式
            format.setBottomBorderStyle(Format::BorderThick);
            format.setBottomBorderColor(Qt::darkBlue);
            // 这里是writeBlank（注意：本版本没有setFormat)
            pWorksheet->setColumnFormat(CellRange(13, 14, 13, 14), format);
        }

#if 0
        // 拓展：设置单个单元格： 对角线 颜色 实则无效，也无宽度接口
        {
            QXlsx::Format format;
            // 设置边框样式
            format.setDiagonalBorderType(Format::DiagnoalBorderBoth);
            format.setDiagonalBorderColor(Qt::red);
            // 这里是writeBlank（注意：本版本没有setFormat)
            pWorksheet->setRowFormat(2, 6, format);
        }
#endif

#if 0
        // 拓展：调用默认索引会崩溃, 此版本有bug，规避不用此接口
        {
            QXlsx::Format format;
            // 使用默认索引的边框样式
            format.setBorderIndex(2);   // 调用默认索引会崩溃
            format.setBorderColor(Qt::yellow);
            // 这里是writeBlank（注意：本版本没有setFormat)
            pWorksheet->writeBlank(1, 5, format);
        }
#endif
    }
    document.save();
}

工程模板v1.1.0

入坑

入坑一：设置列的边框样式未生效

问题

未生效

原因

生效了，这个接口会让受影响的缩小宽度导致看不见，如下测试：

直接1到11都不见了，实则可以拖出来：

这个接口有bug。

解决方式

接口无法解决，可以规避，设置好之后，再调用设置宽度的即可。

上一篇：《QXlsx开发笔记（一）：QXlsx介绍、编译和使用》

下一篇：敬请期待...

本文章博客地址：https://hpzwl.blog.csdn.net/article/details/156397531