Введение

Aspose.Cells FOSS для 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, или работа напрямую с простыми данными ячеек и строк вместо объектов-обёрток Cell / Row.

Всё описанное здесь поставляется в том же MIT-лицензированном, не зависящем от внешних библиотек дереве исходных файлов, что и остальная часть Aspose.Cells FOSS для C++, построенном с помощью CMake и включённом как заголовки и исходники, а не как готовый бинарный файл. Если вы ещё не работали с фасадом API, начните с публикации о функциях Workbook/Worksheet/Cell — эта статья предполагает знание этой основы и сосредоточена на том, что находится под ней.

Что включено

Дерево модели Workbook и Worksheet

Core::WorkbookModel является корневой записью. GetWorksheets() возвращает std::deque<WorksheetModel>, GetSettings() — WorkbookSettingsModel, GetProperties() — WorkbookPropertiesModel, GetDocumentProperties() — DocumentPropertiesModel, GetDiagnostics() — DiagnosticBag, GetStyles() — StyleRepository, GetSharedStrings() — SharedStringRepository, и GetDefaultStyle() / SetDefaultStyle() — StyleValue. Он также отслеживает GetActiveSheetIndex() и std::vector<DefinedNameModel> из GetDefinedNames(). 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 — это простой прямоугольник first-row/first-column/total-rows/total-columns.

Данные стиля как простые значения

StyleValue — это Core аналог изменяемой фасады Style — Style::ToCore() преобразует Style в него, а Style::FromCore() создает Style из него. Он группирует GetFont() (FontValue), GetPattern() (FillPatternKind), GetForegroundColor() / GetBackgroundColor() (ColorValue), GetBorders() (BordersValue), GetAlignment() (AlignmentValue), GetProtection() (ProtectionValue) и GetNumberFormat() (NumberFormatValue), а также статический StyleValue::Default() и Clone(). FontValue зеркально повторяет поле Font по полям: name, size, bold, italic, underline, strike-through и ColorValue. Сам ColorValue представляет собой простой кортеж ARGB (GetA(), GetR(), GetG(), GetB(), Equals(), GetHashCode()) — в отличие от фасадного класса Color у него нет фабрики в стиле FromArgb(), поэтому ColorValue обычно получается из существующего стиля, а не создаётся напрямую.

BordersValue содержит пять членов BorderSideValue — left, right, top, bottom и diagonal — каждый связывает значение перечисления BorderStyle с ColorValue. AlignmentValue моделирует горизонтальное и вертикальное выравнивание, перенос текста, уровень отступа, вращение текста, сжатие до размера и порядок чтения. ProtectionValue и NumberFormatValue поддерживают флаги защиты ячейки и пару id формата числа/пользовательской строки, которую предоставляет Style.

StyleRepository, доступный через WorkbookModel::GetStyles(), предоставляет одну операцию: Normalize(style) -> StyleValue. Рабочая книга использует её внутренне при загрузке и сохранении, чтобы интернировать эквивалентные стили вместо дублирования одинаковых записей StyleValue — это не универсальный кэш стилей с поиском по индексу в текущей поверхности API.

Свойства документа и настройки уровня рабочей книги

DocumentPropertiesModel группы GetCore() (CoreDocumentPropertiesModel: title, subject, creator, keywords, description, last-modified-by, revision, category, content status, и created/modified timestamps) и GetExtended() (ExtendedDocumentPropertiesModel: application, app version, company, manager, doc security, hyperlink base, и флаги scale-crop / links-up-to-date / shared-doc). DocumentProperties::GetModel() и ExtendedDocumentProperties::GetModel() связывают фасадные классы с этими записями.

WorkbookPropertiesModel отражает WorkbookProperties — code name, show-objects, filter privacy, backup-file, и связанные флаги — и вкладывает WorkbookProtectionModel (lock structure/windows/revision, workbook and revisions password), WorkbookViewModel (window position and size, first visible sheet, scroll-bar and sheet-tab visibility, tab ratio, minimized state, auto-filter date grouping), и CalculationPropertiesModel (calculation mode, iteration settings, full precision, concurrent calculation). 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> — каждое условие несёт свой тип, оператор, формулы, поля color-scale/data-bar/icon-set и 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 поддерживает таблицу shared-strings в xlsx: GetValues() возвращает интернированный вектор строк, TryGetValue(index, value) разрешает индекс обратно в текст, а Intern(value) добавляет или переиспользует запись — используется внутренне, когда установлен SaveOptions::SetUseSharedStrings(true). DateSerialConverter преобразует между DateTime и серийным номером в стиле OLE, который Excel сохраняет в ячейке, принимая 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; коммерческое использование, модификация и распространение разрешены.

Начало работы

Связанные ресурсы