Introduzione

Aspose.Cells FOSS per C++ è costruito come due livelli. Il livello che la maggior parte del codice tocca è la facciata: Workbook, Worksheet, Cell e Style, che è ciò di cui trattano gli annunci e i post sulle funzionalità per questa piattaforma. Sotto di esso si trova un secondo livello, nello spazio dei nomi Aspose::Cells_FOSS::Core, composto da semplici record di dati — WorkbookModel, WorksheetModel, CellRecord, StyleValue e circa quattro dozzine di tipi correlati *Model e *Value. Questi record contengono lo stato reale del foglio di calcolo analizzato: valori delle celle indicizzati da CellAddress, attributi di stile come StyleValue, impostazioni della cartella di lavoro e del foglio di lavoro, configurazione della pagina, filtri e diagnostica del caricamento. Le classi facciata leggono da questo livello e scrivono su di esso invece di memorizzare lo stato loro stesse.

Il ponte tra i due livelli è esplicito e pubblico. Workbook::GetModel() restituisce un Core::WorkbookModel, Worksheet::GetModel() restituisce un Core::WorksheetModel, e Style::ToCore() / Style::FromCore() convertono un Style mutabile da e verso un Core::StyleValue. DocumentProperties::GetModel() e ExtendedDocumentProperties::GetModel() fanno lo stesso per i metadati del documento. Un consumatore accede a questo livello direttamente in un insieme più ristretto di casi rispetto al consueto API di modifica delle celle: ispezionare il DiagnosticBag registrato durante il caricamento o il salvataggio di una cartella di lavoro, normalizzare uno stile tramite il StyleRepository a livello di cartella di lavoro, o lavorare direttamente con i record cella e riga plain-old-data invece degli oggetti wrapper Cell / Row.

Tutto quello descritto qui viene distribuito nello stesso albero sorgente, con licenza MIT e privo di dipendenze, del resto di Aspose.Cells FOSS per C++, costruito con CMake e incluso come header e sorgenti anziché come binario precompilato. Se non hai ancora lavorato con la facciata API, inizia prima con il post sulle funzionalità Workbook/Worksheet/Cell — questo post parte da quella base e si concentra su ciò che si trova sotto di essa.

Cosa è incluso

L’albero del modello Workbook e Worksheet

Core::WorkbookModel è il record radice. GetWorksheets() restituisce un std::deque<WorksheetModel>, GetSettings() un WorkbookSettingsModel, GetProperties() un WorkbookPropertiesModel, GetDocumentProperties() un DocumentPropertiesModel, GetDiagnostics() un DiagnosticBag, GetStyles() un StyleRepository, GetSharedStrings() un SharedStringRepository, e GetDefaultStyle() / SetDefaultStyle() un StyleValue. Tiene anche traccia di GetActiveSheetIndex() e di un std::vector<DefinedNameModel> da GetDefinedNames(). Workbook::GetModel() è il punto di ingresso di questo record.

Core::WorksheetModel, raggiunto tramite Worksheet::GetModel(), memorizza le celle come std::unordered_map<CellAddress, CellRecord> tramite GetCells(), le righe come std::unordered_map<int, RowModel> tramite GetRows(), gli intervalli di colonne come std::vector<ColumnRangeModel> tramite GetColumns(), e gli intervalli uniti come std::vector<MergeRegion> tramite GetMergeRegions(). Trasporta anche GetHyperlinks(), GetValidations(), GetConditionalFormattings(), GetPageSetup(), GetView(), GetProtection(), GetAutoFilter(), GetTabColor() e GetVisibility() (un valore SheetVisibility: Visible, Hidden o VeryHidden).

CellAddress è il tipo di chiave hashabile usato per quella mappa di celle. Analizza il testo in stile A1 in indici di riga/colonna basati su zero e viceversa — è una delle poche classi in questo cluster con copertura di test diretta nel repository 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 contiene il CellValue, il CellValueKind di una cella, una stringa di formula opzionale, un StyleValue e un flag GetIsExplicitlyStored() che distingue una cella effettivamente scritta da una che esiste solo perché un valore predefinito di riga o colonna la tocca. RowModel possiede un’altezza opzionale, un flag nascosto e un indice di stile opzionale; ColumnRangeModel contiene gli stessi tre più l’estensione minima/massima di colonna a cui si applica. MergeRegion è un semplice rettangolo prima-riga/prima-colonna/righe-totali/colonne-totali.

Dati di Stile come Valori Semplici

StyleValue è la controparte Core della facciata mutabile Style — Style::ToCore() converte un Style in uno, e Style::FromCore() costruisce un Style a partire da uno. Raggruppa GetFont() (FontValue), GetPattern() (FillPatternKind), GetForegroundColor() / GetBackgroundColor() (ColorValue), GetBorders() (BordersValue), GetAlignment() (AlignmentValue), GetProtection() (ProtectionValue) e GetNumberFormat() (NumberFormatValue), più un StyleValue::Default() statico e un Clone(). FontValue rispecchia il campo Font per campo: nome, dimensione, grassetto, corsivo, sottolineato, barrato e un ColorValue. ColorValue è esso stesso una semplice tupla ARGB (GetA(), GetR(), GetG(), GetB(), Equals(), GetHashCode()) — a differenza della classe facciata Color non ha una fabbrica in stile FromArgb(), quindi un ColorValue è normalmente ottenuto da uno stile esistente piuttosto che costruito direttamente.

BordersValue contiene cinque membri BorderSideValue — sinistra, destra, alto, basso e diagonale — ciascuno accoppiando un valore enum BorderStyle con un ColorValue. AlignmentValue modella l’allineamento orizzontale e verticale, il testo a capo, il livello di rientro, la rotazione del testo, la riduzione per adattamento e l’ordine di lettura. ProtectionValue e NumberFormatValue supportano i flag di protezione della cella e la coppia id/formato numerico-stringa personalizzata che Style espone.

StyleRepository, raggiunto tramite WorkbookModel::GetStyles(), espone una sola operazione: Normalize(style) -> StyleValue. La cartella di lavoro lo utilizza internamente durante il caricamento e il salvataggio per internare stili equivalenti anziché duplicare record StyleValue identici — non è una cache di stile a scopo generale con ricerca basata su indice nella superficie corrente di API.

Proprietà del Documento e Impostazioni a Livello di Cartella di Lavoro

DocumentPropertiesModel raggruppa GetCore() (CoreDocumentPropertiesModel: title, subject, creator, keywords, description, last-modified-by, revision, category, content status e created/modified timestamps) e GetExtended() (ExtendedDocumentPropertiesModel: application, app version, company, manager, doc security, hyperlink base e i flag scale-crop / links-up-to-date / shared-doc). DocumentProperties::GetModel() e ExtendedDocumentProperties::GetModel() fungono da ponte dalle classi facciata a questi record.

WorkbookPropertiesModel rispecchia WorkbookProperties — code name, show-objects, filter privacy, backup-file e flag correlati — e annida 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) e CalculationPropertiesModel (calculation mode, iteration settings, full precision, concurrent calculation). WorkbookSettingsModel contiene un valore DateSystem (Windows1900 o Mac1904) e una cultura di visualizzazione — l’equivalente a livello di modello di WorkbookSettings::GetDate1904() / GetCulture(). La maggior parte dei tipi *Model in questo gruppo espone CopyFrom(source) e HasStoredState(), che il serializer usa per distinguere un valore impostato esplicitamente da un default non impostato prima di scrivere XML.

Modelli di funzionalità del foglio di lavoro

WorksheetProtectionModel rispecchia il campo WorksheetProtection campo per campo e aggiunge i campi password memorizzati — GetPasswordHash(), GetAlgorithmName(), GetHashValue(), GetSaltValue(), GetSpinCount() — che la facciata WorksheetProtection non espone direttamente. WorksheetViewModel contiene la visibilità di linee della griglia, intestazione e zero, layout da destra a sinistra e scala di zoom. PageSetupModel annida PageMarginsModel (margini sinistro/destra/alto/basso/intestazione/piè di pagina come double), PrintOptionsModel (linee della griglia, intestazioni, centratura orizzontale e verticale) e HeaderFooterModel (testo dell’intestazione e del piè di pagina sinistro/centrale/destro), insieme a dimensione carta, orientamento, scala, adatta a larghezza/altezza, area di stampa, righe/colonne di titolo di stampa e vettori di interruzione pagina.

AutoFilterModel contiene una stringa di intervallo, un std::vector<FilterColumnModel> e un AutoFilterSortStateModel. FilterColumnModel a sua volta annida AutoFilterColorFilterModel, AutoFilterDynamicFilterModel e AutoFilterTop10Model, più un semplice elenco di stringhe di valori filtro e un std::vector<AutoFilterCustomFilterModel>. ConditionalFormattingModel associa un std::vector<CellArea> a un std::vector<FormatConditionModel> — ogni condizione porta il suo tipo, operatore, formule, campi color-scale/data-bar/icon-set e un StyleValue per il formato risultante. ValidationModel e HyperlinkModel rispecchiano le facciate Validation e Hyperlink come semplici record, e DefinedNameModel rispecchia DefinedName. SheetVisibility è l’enum a livello di modello dietro Worksheet::GetVisibilityType().

Alcune delle funzionalità della facciata supportate da questi record — AutoFilter e ConditionalFormattingCollection in particolare — sono segnalate nella documentazione del prodotto come ancora in sviluppo attivo in questa release. Considera le strutture sopra come il target strutturale attorno al quale modello e serializer sono costruiti, piuttosto che una garanzia che ogni campo effettui il round-trip attraverso un workbook salvato oggi.

Diagnostica e Stato Condiviso

DiagnosticBag, raggiunto tramite WorkbookModel::GetDiagnostics(), raccoglie record DiagnosticEntry — ognuno con un GetCode(), un GetSeverity() (DiagnosticSeverity: Warning, Recoverable o LossyRecoverable), un GetMessage(), un flag GetRepairApplied() e un flag GetDataLossRisk() — generati mentre un workbook viene analizzato o serializzato. Questo viene eseguito in parallelo con Workbook::GetLoadDiagnostics(), i cui tipi di facciata LoadDiagnostics / LoadIssue condividono lo stesso enum DiagnosticSeverity; il codice che necessita del record modello grezzo invece del wrapper LoadIssue lo ottiene tramite GetDiagnostics() sul modello del workbook.

SharedStringRepository supporta la tabella shared-strings di xlsx: GetValues() restituisce il vettore di stringhe internate, TryGetValue(index, value) risolve un indice in testo, e Intern(value) aggiunge o riutilizza una voce — usato internamente quando SaveOptions::SetUseSharedStrings(true) è impostato. DateSerialConverter converte tra un DateTime e il numero seriale in stile OLE che Excel memorizza in una cella, accettando un DateSystem così i fogli di lavoro basati su 1900 e 1904 si decodificano nella stessa data di calendario.

Avvio rapido

Aggiungi la libreria a un progetto CMake come sottodirectory e collega il target che definisce:

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

L’esempio seguente scrive una cella tramite la facciata, poi accede al modello sottostante per una borsa diagnostica e un’analisi CellAddress — la stessa operazione che WorksheetModel::GetCells() utilizza internamente per indicizzare la sua mappa di celle:

#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;
}

Formati supportati

FormatoEstensioneLeggiScrivi
XLSX.xlsx✓✓

Il livello modello descritto qui è la rappresentazione in memoria su cui operano il lettore e lo scrittore xlsx; non è legato a nessun formato di file aggiuntivo oltre all’import/export Xlsx supportato dal resto della libreria.

Open Source e Licenze

Aspose.Cells FOSS per C++ è rilasciato con licenza MIT. Il codice sorgente, inclusi gli header modello Aspose::Cells_FOSS::Core citati in questo post, è su GitHub; l’uso commerciale, la modifica e la redistribuzione sono consentiti.

Come iniziare

Risorse correlate