Вступ
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 — це простий прямокутник «перший рядок/перший стовпець/загальна кількість рядків/загальна кількість стовпців».
Дані стилю як прості значення
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 — кожен поєднує значення enum 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 — це enum рівня моделі, що стоїть за Worksheet::GetVisibilityType().
Деякі з фасадних функцій, які підтримують ці записи — зокрема AutoFilter і ConditionalFormattingCollection — згадані в документації продукту як все ще у процесі активної розробки у цьому випуску. Ставтеся до наведених вище форм як до структурної цілі, навколо якої побудовані модель і серіалізатор, а не як до гарантії, що кожне поле сьогодні проходить повний цикл збереження у робочій книзі.
Діагностика та спільний стан
DiagnosticBag, доступний через WorkbookModel::GetDiagnostics(), збирає записи DiagnosticEntry — кожен з GetCode(), GetSeverity() (DiagnosticSeverity: Warning, Recoverable або LossyRecoverable), GetMessage(), прапорцем GetRepairApplied() і прапорцем GetDataLossRisk() — створені під час парсингу або серіалізації робочої книги. Це працює разом з Workbook::GetLoadDiagnostics(), чиї типи фасадного рівня LoadDiagnostics / LoadIssue мають той самий enum 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; комерційне використання, модифікація та розповсюдження дозволені.
