简介

Aspose.Cells FOSS for C++ 被构建为两层。大多数代码触及的层是外观层：Workbook、Worksheet、Cell 和 Style，这正是本平台的公告和特性文章所覆盖的内容。其下是第二层，位于 Aspose::Cells_FOSS::Core 命名空间中，由普通数据记录组成——WorkbookModel、WorksheetModel、CellRecord、StyleValue，以及大约四十多个相关的 *Model 和 *Value 类型。这些记录保存实际解析后的电子表格状态：以 CellAddress 为键的单元格值、作为 StyleValue 的样式属性、工作簿和工作表设置、页面布局、过滤器以及加载诊断信息。外观类从该层读取并写入，而不是自行存储状态。

这两层之间的桥梁是明确且公开的。Workbook::GetModel() 返回一个 Core::WorkbookModel，Worksheet::GetModel() 返回一个 Core::WorksheetModel，而 Style::ToCore() / Style::FromCore() 将可变的 Style 与 Core::StyleValue 相互转换。DocumentProperties::GetModel() 和 ExtendedDocumentProperties::GetModel() 对文档元数据执行相同的操作。相比日常的单元格编辑 API，消费者仅在较少的情形下直接使用此层：检查工作簿加载或保存时记录的 DiagnosticBag、通过工作簿级别的 StyleRepository 对样式进行规范化，或直接使用 plain-old-data 单元格和行记录，而不是使用 Cell / Row 包装对象。

此处描述的所有内容与 Aspose.Cells FOSS for C++ 的其余部分一起，作为同一套 MIT 许可证、无依赖的源代码树发布，使用 CMake 构建，并以头文件和源文件的形式包含，而非预构建的二进制文件。如果您尚未使用过外观 API，请先阅读 Workbook/Worksheet/Cell 功能文章——本文假设您已有这些基础，并聚焦于其底层实现。

包含内容

工作簿和工作表模型树

Core::WorkbookModel 是根记录。GetWorksheets() 返回一个 std::deque<WorksheetModel>，GetSettings() 返回一个 WorkbookSettingsModel，GetProperties() 返回一个 WorkbookPropertiesModel，GetDocumentProperties() 返回一个 DocumentPropertiesModel，GetDiagnostics() 返回一个 DiagnosticBag，GetStyles() 返回一个 StyleRepository，GetSharedStrings() 返回一个 SharedStringRepository，以及 GetDefaultStyle() / SetDefaultStyle() 返回一个 StyleValue。它还跟踪来自 GetDefinedNames() 的 GetActiveSheetIndex() 和一个 std::vector<DefinedNameModel>。Workbook::GetModel() 是该记录的入口点。

Core::WorksheetModel，通过 Worksheet::GetModel() 访问，将单元格存储为 std::unordered_map<CellAddress, CellRecord>，通过 GetCells()，行存储为 std::unordered_map<int, RowModel>，通过 GetRows()，列范围存储为 std::vector<ColumnRangeModel>，通过 GetColumns()，以及合并范围存储为 std::vector<MergeRegion>，通过 GetMergeRegions()。它还携带 GetHyperlinks()、GetValidations()、GetConditionalFormattings()、GetPageSetup()、GetView()、GetProtection()、GetAutoFilter()、GetTabColor() 和 GetVisibility()（一个 SheetVisibility 值：Visible、Hidden 或 VeryHidden）。

CellAddress 是用于该单元格映射的可哈希键类型。它将 A1 样式的文本解析为零基的行/列索引并且可以反向转换——这是该簇中为数不多的在 FOSS 仓库中拥有直接测试覆盖的类之一：

#include "aspose/cells_foss/core/CellAddress.h"

using namespace Aspose::Cells_FOSS;

Core::CellAddress parsed = Core::CellAddress::Parse("AB3");
// parsed.GetRowIndex()    == 2    (zero-based row index)
// parsed.GetColumnIndex() == 27   (zero-based column index)
// parsed.ToString()       == "AB3"

CellRecord 保存单元格的 CellValue、CellValueKind、一个可选的公式字符串、一个 StyleValue，以及一个 GetIsExplicitlyStored() 标志，用于区分实际写入的单元格和仅因行或列默认而存在的单元格。RowModel 包含可选的高度、隐藏标志和可选的样式索引；ColumnRangeModel 包含相同的三项以及它适用的最小/最大列跨距。MergeRegion 是一个普通的首行/首列/总行数/总列数矩形。

将样式数据设为普通值

StyleValue 是 Core 对应于可变 Style facade — Style::ToCore() 将 Style 转换为一个，而 Style::FromCore() 从一个构建 Style。它将 GetFont()（FontValue）、GetPattern()（FillPatternKind）、GetForegroundColor() / GetBackgroundColor()（ColorValue）、GetBorders()（BordersValue）、GetAlignment()（AlignmentValue）、GetProtection()（ProtectionValue）和 GetNumberFormat()（NumberFormatValue）分组在一起，加上一个 static StyleValue::Default() 和一个 Clone()。FontValue 逐字段镜像 Font：name、size、bold、italic、underline、strike-through，和一个 ColorValue。ColorValue 本身是一个普通的 ARGB 元组（GetA(), GetR(), GetG(), GetB(), Equals(), GetHashCode()）——不像 facade Color 类，它没有 FromArgb()-style 工厂，因此通常从现有样式获取 ColorValue，而不是直接构造。

BordersValue 包含五个 BorderSideValue 成员 — left、right、top、bottom 和 diagonal — 每个成员将一个 BorderStyle 枚举值与一个 ColorValue 配对。AlignmentValue 对水平和垂直对齐、自动换行、缩进级别、文本旋转、收缩以适应以及阅读顺序进行建模。ProtectionValue 和 NumberFormatValue 支持单元格保护标志以及 Style 暴露的数字格式 id/自定义字符串对。

StyleRepository，通过 WorkbookModel::GetStyles() 访问，公开了一个操作：Normalize(style) -> StyleValue。工作簿在加载和保存时内部使用它，以便对等价样式进行内部化，而不是复制相同的 StyleValue 记录——它不是在当前 API 表面上的通用样式缓存，也不支持基于索引的查找。

文档属性和工作簿级别设置

DocumentPropertiesModel 将 GetCore() 分组（CoreDocumentPropertiesModel：标题、主题、创建者、关键字、描述、最后修改者、修订、类别、内容状态，以及 created/modified 时间戳）以及 GetExtended()（ExtendedDocumentPropertiesModel：应用程序、应用版本、公司、管理员、文档安全、超链接基址，以及 scale-crop / links-up-to-date / shared-doc 标志）。DocumentProperties::GetModel() 和 ExtendedDocumentProperties::GetModel() 在外观类与这些记录之间搭建桥梁。

WorkbookPropertiesModel 镜像 WorkbookProperties —— 代码名、show-objects、filter privacy、backup-file 以及相关标志 —— 并嵌套 WorkbookProtectionModel（锁定结构/窗口/修订、工作簿及修订密码）、WorkbookViewModel（窗口位置和大小、首个可见工作表、滚动条和工作表标签可见性、标签比例、最小化状态、自动筛选日期分组）以及 CalculationPropertiesModel（计算模式、迭代设置、全精度、并发计算）。WorkbookSettingsModel 包含一个 DateSystem 值（Windows1900 或 Mac1904）和一个显示文化 —— 这是 WorkbookSettings::GetDate1904() / GetCulture() 的模型层对应物。该组中大多数 *Model 类型公开 CopyFrom(source) 和 HasStoredState()，序列化器使用它们在写入 XML 之前区分显式设定的值和未设定的默认值。

工作表功能模型

WorksheetProtectionModel 逐字段镜像 WorksheetProtection，并添加存储的密码字段 —— GetPasswordHash()、GetAlgorithmName()、GetHashValue()、GetSaltValue()、GetSpinCount() —— 这些字段外观类 WorksheetProtection 并未直接暴露。WorksheetViewModel 包含网格线、标题以及零可见性、从右到左布局和缩放比例。PageSetupModel 嵌套 PageMarginsModel（左/右/上/下/页眉/页脚边距，以 double 表示），PrintOptionsModel（网格线、标题、水平和垂直居中），以及 HeaderFooterModel（左/居中/右页眉和页脚文本），并附带纸张尺寸、方向、比例、适合宽度/高度、打印区域、打印标题行/列，以及分页向量。

AutoFilterModel 包含一个范围字符串、一个 std::vector<FilterColumnModel> 和一个 AutoFilterSortStateModel。FilterColumnModel 进一步嵌套 AutoFilterColorFilterModel、AutoFilterDynamicFilterModel 和 AutoFilterTop10Model，以及一个普通的过滤值字符串列表和一个 std::vector<AutoFilterCustomFilterModel>。ConditionalFormattingModel 将 std::vector<CellArea> 与 std::vector<FormatConditionModel> 配对 —— 每个条件携带其类型、运算符、公式、颜色尺度/数据条/图标集字段，以及一个用于结果格式的 StyleValue。ValidationModel 和 HyperlinkModel 作为普通记录镜像 Validation 和 Hyperlink 外观类，DefinedNameModel 镜像 DefinedName。SheetVisibility 是 Worksheet::GetVisibilityType() 背后的模型层枚举。

这些记录所支持的部分外观特性——尤其是 AutoFilter 和 ConditionalFormattingCollection——在产品文档中被标注为本次发布仍在积极开发中。请将上述结构视为模型和序列化器所构建的目标结构，而不是保证每个字段今天都能通过已保存的工作簿来回传递的承诺。

诊断与共享状态

DiagnosticBag，通过 WorkbookModel::GetDiagnostics() 访问，收集 DiagnosticEntry 记录——每条记录包含一个 GetCode()、一个 GetSeverity()（DiagnosticSeverity：Warning、Recoverable 或 LossyRecoverable）、一个 GetMessage()、一个 GetRepairApplied() 标志和一个 GetDataLossRisk() 标志——这些记录在解析或序列化工作簿时生成。它与 Workbook::GetLoadDiagnostics() 并行运行，其外观层的 LoadDiagnostics / LoadIssue 类型共享相同的 DiagnosticSeverity 枚举；需要原始模型记录而非 LoadIssue 包装器的代码可通过工作簿模型上的 GetDiagnostics() 访问它。

SharedStringRepository 支持 xlsx shared-strings 表：GetValues() 返回内部字符串向量，TryGetValue(index, value) 将索引解析回文本，Intern(value) 添加或复用条目——在设置了 SaveOptions::SetUseSharedStrings(true) 时内部使用。DateSerialConverter 在 DateTime 与 Excel 在单元格中存储的 OLE 样式序列号之间进行转换，接受一个 DateSystem，以便 1900 和 1904 基准的工作簿解码为相同的日历日期。

快速入门

将库作为子目录添加到 CMake 项目中，并链接其定义的目标：

add_subdirectory(path/to/Aspose.Cells-FOSS-for-Cpp)
target_link_libraries(MyApp PRIVATE Aspose.Cells.Foss.Cpp)

下面的示例通过外观写入单元格，然后深入底层模型获取诊断包和一个 CellAddress 解析——这与 WorksheetModel::GetCells() 在内部用于键控其单元格映射的操作相同：

#include "aspose/cells_foss/Workbook.h"
#include "aspose/cells_foss/Worksheet.h"
#include "aspose/cells_foss/Cell.h"
#include "aspose/cells_foss/core/CellAddress.h"
#include <iostream>

using namespace Aspose::Cells_FOSS;

int main() {
    Workbook workbook;
    Worksheet& sheet = workbook.GetWorksheets()[0];
    sheet.SetName("Report");
    sheet.GetCells()["A1"].PutValue("Total");
    workbook.Save("report.xlsx");

    Core::CellAddress address = Core::CellAddress::Parse("A1");
    std::cout << "Row: " << address.GetRowIndex()
              << " Column: " << address.GetColumnIndex() << "\n";

    for (const auto& entry : workbook.GetModel().GetDiagnostics().GetEntries()) {
        std::cout << "Diagnostic: " << entry.GetMessage() << "\n";
    }

    return 0;
}

支持的格式

格式扩展名读取写入
XLSX.xlsx✓✓

此处描述的模型层是 xlsx 读取器和写入器操作的内存表示；它本身并未绑定除库其余部分支持的 Xlsx 导入/导出之外的任何其他文件格式。

开源与许可

Aspose.Cells FOSS 的 C++ 版采用 MIT 许可证。源代码（包括本文中引用的 Aspose::Cells_FOSS::Core 模型头文件）位于 GitHub；允许商业使用、修改和再分发。

入门

相关资源