Wprowadzenie
Aspose.Cells FOSS dla C++ jest zbudowane jako dwie warstwy. Warstwa, z którą najczęściej wchodzi w interakcję kod, to fasada: Workbook, Worksheet, Cell i Style, co jest tematem ogłoszeń i wpisów o funkcjach tej platformy. Pod nią znajduje się druga warstwa, w przestrzeni nazw Aspose::Cells_FOSS::Core, składająca się z prostych rekordów danych — WorkbookModel, WorksheetModel, CellRecord, StyleValue oraz około czterdziestu powiązanych typów *Model i *Value. Te rekordy przechowują rzeczywisty, sparsowany stan arkusza kalkulacyjnego: wartości komórek indeksowane przez CellAddress, atrybuty stylu jako StyleValue, ustawienia skoroszytu i arkusza, konfigurację strony, filtry oraz diagnostykę ładowania. Klasy fasady odczytują i zapisują do tej warstwy zamiast przechowywać stan samodzielnie.
Most pomiędzy dwoma warstwami jest jawny i publiczny. Workbook::GetModel() zwraca Core::WorkbookModel, Worksheet::GetModel() zwraca Core::WorksheetModel, a Style::ToCore() / Style::FromCore() konwertują mutowalny Style na i z Core::StyleValue. DocumentProperties::GetModel() i ExtendedDocumentProperties::GetModel() robią to samo dla metadanych dokumentu. Konsument sięga po tę warstwę bezpośrednio w węższym zestawie przypadków niż codzienne edytowanie komórek API: przeglądanie DiagnosticBag zapisanego podczas ładowania lub zapisywania skoroszytu, normalizacja stylu poprzez poziomowy StyleRepository skoroszytu, lub bezpośrednia praca z rekordami komórek i wierszy typu plain-old-data zamiast obiektów opakowujących Cell / Row.
Wszystko, co tutaj opisano, jest dostarczane w tym samym drzewie źródeł licencjonowanym na licencji MIT, wolnym od zależności, co reszta Aspose.Cells FOSS dla C++, zbudowanym przy użyciu CMake i dołączonym jako pliki nagłówkowe oraz źródłowe, a nie jako gotowy binarny. Jeśli nie pracowałeś jeszcze z fasadą API, zacznij od wpisu o funkcjach Workbook/Worksheet/Cell — ten wpis zakłada tę bazę i koncentruje się na tym, co leży pod nią.
Co jest w zestawie
Drzewo modelu skoroszytu i arkusza
Core::WorkbookModel jest rekordem głównym. GetWorksheets() zwraca std::deque<WorksheetModel>, GetSettings() WorkbookSettingsModel, GetProperties() WorkbookPropertiesModel, GetDocumentProperties() DocumentPropertiesModel, GetDiagnostics() DiagnosticBag, GetStyles() StyleRepository, GetSharedStrings() SharedStringRepository, a GetDefaultStyle() / SetDefaultStyle() StyleValue. Śledzi także GetActiveSheetIndex() i std::vector<DefinedNameModel> z GetDefinedNames(). Workbook::GetModel() jest punktem wejścia do tego rekordu.
Core::WorksheetModel, dostępny poprzez Worksheet::GetModel(), przechowuje komórki jako std::unordered_map<CellAddress, CellRecord> za pomocą GetCells(), wiersze jako std::unordered_map<int, RowModel> za pomocą GetRows(), zakresy kolumn jako std::vector<ColumnRangeModel> za pomocą GetColumns() oraz zakresy scalone jako std::vector<MergeRegion> za pomocą GetMergeRegions(). Zawiera także GetHyperlinks(), GetValidations(), GetConditionalFormattings(), GetPageSetup(), GetView(), GetProtection(), GetAutoFilter(), GetTabColor() oraz GetVisibility() (wartość SheetVisibility: Visible, Hidden lub VeryHidden).
CellAddress jest typem klucza hashującego używanym w tej mapie komórek. Parsuje tekst w stylu A1 na indeksy wierszy/kolumn zerowe oraz z powrotem — jest to jedna z niewielu klas w tym klastrze objętych bezpośrednim pokryciem testowym w repozytorium 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 przechowuje CellValue, CellValueKind komórki, opcjonalny ciąg formuły, StyleValue oraz flagę GetIsExplicitlyStored(), która rozróżnia komórkę rzeczywiście zapisaną od tej, która istnieje jedynie dlatego, że domyślne ustawienie wiersza lub kolumny na nią wpływa. RowModel zawiera opcjonalną wysokość, flagę ukrycia oraz opcjonalny indeks stylu; ColumnRangeModel zawiera te same trzy elementy plus minimalny/maksymalny rozpiętość kolumn, której dotyczy. MergeRegion jest prostokątem określającym pierwszy wiersz/pierwszą kolumnę/całkowitą liczbę wierszy/całkowitą liczbę kolumn.
Dane stylu jako zwykłe wartości
StyleValue jest Core odpowiednikiem mutowalnej fasady Style — Style::ToCore() konwertuje Style na taką, a Style::FromCore() tworzy Style z takiej. Grupuje GetFont() (FontValue), GetPattern() (FillPatternKind), GetForegroundColor() / GetBackgroundColor() (ColorValue), GetBorders() (BordersValue), GetAlignment() (AlignmentValue), GetProtection() (ProtectionValue) oraz GetNumberFormat() (NumberFormatValue), plus statyczny StyleValue::Default() i Clone(). FontValue odzwierciedla pole po polu Font: nazwa, rozmiar, pogrubienie, kursywa, podkreślenie, przekreślenie oraz ColorValue. ColorValue sam w sobie jest zwykłą krotką ARGB (GetA(), GetR(), GetG(), GetB(), Equals(), GetHashCode()) — w przeciwieństwie do fasady klasy Color nie posiada fabryki w stylu FromArgb(), więc ColorValue jest zwykle uzyskiwany z istniejącego stylu zamiast tworzyć go bezpośrednio.
BordersValue zawiera pięciu członków BorderSideValue — lewy, prawy, górny, dolny i przekątny — każdy łączy wartość wyliczenia BorderStyle z ColorValue. AlignmentValue modeluje wyrównanie poziome i pionowe, zawijanie tekstu, poziom wcięcia, obrót tekstu, dopasowanie do rozmiaru oraz kolejność czytania. ProtectionValue i NumberFormatValue obsługują flagi ochrony komórek oraz parę identyfikatora formatu liczby/ciągu własnego, którą udostępnia Style.
StyleRepository, dostępny poprzez WorkbookModel::GetStyles(), udostępnia jedną operację: Normalize(style) -> StyleValue. Skoroszyt używa jej wewnętrznie podczas ładowania i zapisywania, aby internować równoważne style zamiast duplikować identyczne rekordy StyleValue — nie jest to ogólnego przeznaczenia pamięć podręczna stylów z wyszukiwaniem opartym na indeksie w bieżącej warstwie API.
Właściwości dokumentu i ustawienia na poziomie skoroszytu
DocumentPropertiesModel grupuje GetCore() (CoreDocumentPropertiesModel: tytuł, temat, twórca, słowa kluczowe, opis, ostatnio modyfikowane przez, wersja, kategoria, status treści oraz znaczniki czasu created/modified) oraz GetExtended() (ExtendedDocumentPropertiesModel: aplikacja, wersja aplikacji, firma, menedżer, zabezpieczenia dokumentu, baza hiperłączy oraz flagi skalowanie-przycinanie / linki-aktualne / dokument-współdzielony). DocumentProperties::GetModel() i ExtendedDocumentProperties::GetModel() łączą klasy fasady z tymi rekordami.
WorkbookPropertiesModel odzwierciedla WorkbookProperties — nazwa kodowa, pokaż-obiekty, prywatność filtra, plik kopii zapasowej i powiązane flagi — oraz zawiera w sobie WorkbookProtectionModel (blokada struktury/okien/wersji, hasło skoroszytu i wersji), WorkbookViewModel (pozycja i rozmiar okna, pierwsza widoczna karta, widoczność paska przewijania i zakładek arkuszy, współczynnik zakładek, stan zminimalizowany, grupowanie dat w autofiltrowaniu) oraz CalculationPropertiesModel (tryb obliczeń, ustawienia iteracji, pełna precyzja, równoległe obliczenia). WorkbookSettingsModel zawiera wartość DateSystem (Windows1900 lub Mac1904) oraz kulturę wyświetlania — odpowiednik na poziomie modelu dla WorkbookSettings::GetDate1904() / GetCulture(). Większość typów *Model w tej grupie udostępnia CopyFrom(source) i HasStoredState(), które serializer używa, aby odróżnić wartość ustawioną explicite od domyślnej nieustawionej przed zapisaniem XML.
Modele funkcji arkusza kalkulacyjnego
WorksheetProtectionModel odzwierciedla pole WorksheetProtection pole po polu i dodaje przechowywane pola hasła — GetPasswordHash(), GetAlgorithmName(), GetHashValue(), GetSaltValue(), GetSpinCount() — które fasada WorksheetProtection nie udostępnia bezpośrednio. WorksheetViewModel zawiera widoczność linii siatki, nagłówka i zer, układ od prawej do lewej oraz skalę powiększenia. PageSetupModel zawiera PageMarginsModel (marginesy lewy/prawy/górny/dolny/nagłówek/stopka jako liczby zmiennoprzecinkowe), PrintOptionsModel (linijki siatki, nagłówki, wyśrodkowanie w poziomie i pionie) oraz HeaderFooterModel (tekst nagłówka i stopki po lewej/środkowy/prawej), wraz z rozmiarem papieru, orientacją, skalą, dopasowaniem do szerokości/wysokości, obszarem wydruku, wierszami/kolumnami tytułów wydruku oraz wektorami podziału stron.
AutoFilterModel przechowuje ciąg zakresu, std::vector<FilterColumnModel> oraz AutoFilterSortStateModel. FilterColumnModel z kolei zawiera AutoFilterColorFilterModel, AutoFilterDynamicFilterModel i AutoFilterTop10Model, plus prostą listę ciągów wartości filtra oraz std::vector<AutoFilterCustomFilterModel>. ConditionalFormattingModel łączy std::vector<CellArea> z std::vector<FormatConditionModel> — każdy warunek zawiera swój typ, operator, formuły, pola skali kolorów/paska danych/zestawu ikon oraz StyleValue określający wynikowy format. ValidationModel i HyperlinkModel odzwierciedlają fasady Validation i Hyperlink jako proste rekordy, a DefinedNameModel odzwierciedla DefinedName. SheetVisibility jest wyliczeniem na warstwie modelu stojącym za Worksheet::GetVisibilityType().
Niektóre z funkcji fasady, które te rekordy obsługują — szczególnie AutoFilter i ConditionalFormattingCollection — są wymienione w dokumentacji produktu jako nadal będące w aktywnym rozwoju w tej wersji. Traktuj powyższe schematy jako strukturalny cel, wokół którego zbudowane są model i serializer, a nie jako gwarancję, że każde pole zostanie poprawnie odtworzone w zapisanym skoroszycie już dziś.
Diagnostyka i współdzielony stan
DiagnosticBag, osiągnięty przez WorkbookModel::GetDiagnostics(), zbiera rekordy DiagnosticEntry — każdy z GetCode(), GetSeverity() (DiagnosticSeverity: Warning, Recoverable lub LossyRecoverable), GetMessage(), flagą GetRepairApplied() i flagą GetDataLossRisk() — generowane podczas parsowania lub serializacji skoroszytu. Działa to równolegle z Workbook::GetLoadDiagnostics(), którego typy na poziomie fasady LoadDiagnostics / LoadIssue korzystają z tego samego wyliczenia DiagnosticSeverity; kod potrzebujący surowego rekordu modelu zamiast opakowania LoadIssue uzyskuje go poprzez GetDiagnostics() w modelu skoroszytu.
SharedStringRepository obsługuje tabelę shared-strings w formacie xlsx: GetValues() zwraca wektor zinternowanych łańcuchów, TryGetValue(index, value) odtwarza indeks na tekst, a Intern(value) dodaje lub ponownie wykorzystuje wpis — używane wewnętrznie, gdy ustawione jest SaveOptions::SetUseSharedStrings(true). DateSerialConverter konwertuje pomiędzy DateTime a numerem seryjnym w stylu OLE, który Excel przechowuje w komórce, przyjmując DateSystem, aby skoroszyty oparte na 1900 i 1904 były dekodowane do tej samej daty kalendarzowej.
Szybki start
Dodaj bibliotekę do projektu CMake jako podkatalog i podłącz cel, który definiuje:
add_subdirectory(path/to/Aspose.Cells-FOSS-for-Cpp)
target_link_libraries(MyApp PRIVATE Aspose.Cells.Foss.Cpp)
Poniższy przykład zapisuje komórkę za pośrednictwem fasady, a następnie sięga do leżącego u podstaw modelu, aby uzyskać worek diagnostyczny i CellAddress parsowanie — tę samą operację, którą WorksheetModel::GetCells() używa wewnętrznie do kluczowania swojej mapy komórek:
#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;
}
Obsługiwane formaty
| Format | Rozszerzenie | Odczyt | Zapis |
|---|---|---|---|
| XLSX | .xlsx | ✓ | ✓ |
Warstwa modelu opisana tutaj jest reprezentacją w pamięci, na której działają czytnik i zapisujący xlsx; nie jest ona powiązana z żadnym dodatkowym formatem pliku poza importem/eksportem Xlsx, które obsługuje reszta biblioteki.
Open Source i licencjonowanie
Aspose.Cells FOSS dla C++ jest licencjonowane na licencji MIT. Kod źródłowy, w tym Aspose::Cells_FOSS::Core nagłówki modelu wymienione w tym poście, znajduje się na GitHub; dozwolone jest komercyjne użycie, modyfikacja i redystrybucja.
