Introducción

Aspose.Cells FOSS para C++ se construye en dos capas. La capa que la mayor parte del código toca es la fachada: Workbook, Worksheet, Cell y Style, que es lo que cubren los anuncios y publicaciones de características para esta plataforma. Debajo de ella se encuentra una segunda capa, en el espacio de nombres Aspose::Cells_FOSS::Core, compuesta por registros de datos simples — WorkbookModel, WorksheetModel, CellRecord, StyleValue, y aproximadamente cuatro docenas de tipos relacionados *Model y *Value. Estos registros contienen el estado real de la hoja de cálculo analizada: valores de celdas indexados por CellAddress, atributos de estilo como StyleValue, configuraciones del libro y de la hoja, configuración de página, filtros y diagnósticos de carga. Las clases de fachada leen de esta capa y escriben en ella en lugar de almacenar el estado por sí mismas.

El puente entre las dos capas es explícito y público. Workbook::GetModel() devuelve un Core::WorkbookModel, Worksheet::GetModel() devuelve un Core::WorksheetModel, y Style::ToCore() / Style::FromCore() convierten un Style mutable a y desde un Core::StyleValue. DocumentProperties::GetModel() y ExtendedDocumentProperties::GetModel() hacen lo mismo para los metadatos del documento. Un consumidor accede a esta capa directamente en un conjunto más estrecho de casos que la edición cotidiana de celdas API: inspeccionar el DiagnosticBag registrado mientras se cargaba o guardaba un libro, normalizar un estilo a través del StyleRepository a nivel de libro, o trabajar directamente con los registros plain-old-data de celda y fila en lugar de los objetos envoltorio Cell / Row.

Todo lo descrito aquí se entrega en el mismo árbol de código fuente bajo licencia MIT y sin dependencias que el resto de Aspose.Cells FOSS para C++, construido con CMake e incluido como encabezados y código fuente en lugar de un binario precompilado. Si aún no has trabajado con la fachada API, comienza primero con la publicación sobre las características de Workbook/Worksheet/Cell — esta publicación asume ese conocimiento básico y se centra en lo que se encuentra debajo.

Qué incluye

El árbol del modelo de Workbook y Worksheet

Core::WorkbookModel es el registro raíz. GetWorksheets() devuelve un std::deque<WorksheetModel>, GetSettings() un WorkbookSettingsModel, GetProperties() un WorkbookPropertiesModel, GetDocumentProperties() un DocumentPropertiesModel, GetDiagnostics() un DiagnosticBag, GetStyles() un StyleRepository, GetSharedStrings() un SharedStringRepository, y GetDefaultStyle() / SetDefaultStyle() un StyleValue. También rastrea GetActiveSheetIndex() y un std::vector<DefinedNameModel> de GetDefinedNames(). Workbook::GetModel() es el punto de entrada a este registro.

Core::WorksheetModel, alcanzado a través de Worksheet::GetModel(), almacena celdas como std::unordered_map<CellAddress, CellRecord> mediante GetCells(), filas como std::unordered_map<int, RowModel> mediante GetRows(), rangos de columnas como std::vector<ColumnRangeModel> mediante GetColumns(), y rangos fusionados como std::vector<MergeRegion> mediante GetMergeRegions(). También incluye GetHyperlinks(), GetValidations(), GetConditionalFormattings(), GetPageSetup(), GetView(), GetProtection(), GetAutoFilter(), GetTabColor() y GetVisibility() (un valor SheetVisibility: Visible, Hidden o VeryHidden).

CellAddress es el tipo de clave hashable usado para ese mapa de celdas. Analiza texto con estilo A1 a índices de fila/columna basados en cero y viceversa — es una de las pocas clases en este conjunto con cobertura de pruebas directa en el repositorio 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 el CellValue, CellValueKind de una celda, una cadena de fórmula opcional, un StyleValue, y una bandera GetIsExplicitlyStored() que distingue una celda realmente escrita de una que solo existe porque un valor predeterminado de fila o columna la toca. RowModel lleva una altura opcional, una bandera oculta y un índice de estilo opcional; ColumnRangeModel lleva los mismos tres más el rango de columnas mín/máx al que se aplica. MergeRegion es un rectángulo simple de primera fila/primera columna/filas totales/columnas totales.

Datos de Estilo como Valores Simples

StyleValue es la contraparte Core de la fachada mutable Style — Style::ToCore() convierte un Style en uno, y Style::FromCore() construye un Style a partir de uno. Agrupa GetFont() (FontValue), GetPattern() (FillPatternKind), GetForegroundColor() / GetBackgroundColor() (ColorValue), GetBorders() (BordersValue), GetAlignment() (AlignmentValue), GetProtection() (ProtectionValue) y GetNumberFormat() (NumberFormatValue), además de un StyleValue::Default() estático y un Clone(). FontValue refleja el campo Font campo por campo: nombre, tamaño, negrita, cursiva, subrayado, tachado y un ColorValue. ColorValue en sí es una tupla ARGB simple (GetA(), GetR(), GetG(), GetB(), Equals(), GetHashCode()) — a diferencia de la clase fachada Color, no tiene una fábrica de estilo FromArgb(), por lo que un ColorValue se obtiene normalmente de un estilo existente en lugar de construirse directamente.

BordersValue contiene cinco miembros BorderSideValue — izquierda, derecha, superior, inferior y diagonal — cada uno emparejando un valor enum BorderStyle con un ColorValue. AlignmentValue modela la alineación horizontal y vertical, el ajuste de texto, el nivel de sangría, la rotación del texto, reducir para ajustar y el orden de lectura. ProtectionValue y NumberFormatValue respaldan las banderas de protección de celda y el par id/formato numérico-cadena personalizada que Style expone.

StyleRepository, alcanzado a través de WorkbookModel::GetStyles(), expone una operación: Normalize(style) -> StyleValue. El libro de trabajo lo utiliza internamente al cargar y guardar para internar estilos equivalentes en lugar de duplicar registros StyleValue idénticos — no es una caché de estilos de propósito general con búsqueda basada en índices en la superficie actual de API.

Propiedades del Documento y Configuraciones a Nivel de Libro de Trabajo

DocumentPropertiesModel agrupa GetCore() (CoreDocumentPropertiesModel: title, subject, creator, keywords, description, last-modified-by, revision, category, content status, y created/modified timestamps) y GetExtended() (ExtendedDocumentPropertiesModel: application, app version, company, manager, doc security, hyperlink base, y las banderas scale-crop / links-up-to-date / shared-doc). DocumentProperties::GetModel() y ExtendedDocumentProperties::GetModel() enlazan las clases fachada con estos registros.

WorkbookPropertiesModel refleja WorkbookProperties — code name, show-objects, filter privacy, backup-file, y banderas relacionadas — y anida 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), y CalculationPropertiesModel (calculation mode, iteration settings, full precision, concurrent calculation). WorkbookSettingsModel lleva un valor DateSystem (Windows1900 o Mac1904) y una cultura de visualización — el homólogo a nivel de modelo de WorkbookSettings::GetDate1904() / GetCulture(). La mayoría de los tipos *Model en este grupo exponen CopyFrom(source) y HasStoredState(), que el serializador usa para distinguir un valor establecido explícitamente de un valor predeterminado no establecido antes de escribir XML.

Modelos de características de hoja de cálculo

WorksheetProtectionModel refleja el campo WorksheetProtection campo por campo y agrega los campos de contraseña almacenados — GetPasswordHash(), GetAlgorithmName(), GetHashValue(), GetSaltValue(), GetSpinCount() — que la fachada WorksheetProtection no expone directamente. WorksheetViewModel contiene la visibilidad de líneas de cuadrícula, encabezado y ceros, diseño de derecha a izquierda y escala de zoom. PageSetupModel anida PageMarginsModel (márgenes izquierdo/derecho/arriba/abajo/encabezado/pie de página como doubles), PrintOptionsModel (líneas de cuadrícula, encabezados, centrado horizontal y vertical), y HeaderFooterModel (texto de encabezado y pie de página izquierda/centro/derecha), junto con tamaño de papel, orientación, escala, ajuste a ancho/alto, área de impresión, filas/columnas de título de impresión y vectores de salto de página.

AutoFilterModel contiene una cadena de rango, un std::vector<FilterColumnModel> y un AutoFilterSortStateModel. FilterColumnModel a su vez anida AutoFilterColorFilterModel, AutoFilterDynamicFilterModel y AutoFilterTop10Model, más una lista simple de cadenas de valores de filtro y un std::vector<AutoFilterCustomFilterModel>. ConditionalFormattingModel empareja un std::vector<CellArea> con un std::vector<FormatConditionModel> — cada condición lleva su tipo, operador, fórmulas, campos de escala de color/barras de datos/conjunto de íconos y un StyleValue para el formato resultante. ValidationModel y HyperlinkModel reflejan las fachadas Validation y Hyperlink como registros simples, y DefinedNameModel refleja DefinedName. SheetVisibility es el enum de capa modelo detrás de Worksheet::GetVisibilityType().

Algunas de las características de la fachada que respaldan estos registros — AutoFilter y ConditionalFormattingCollection en particular — se mencionan en la documentación del producto como aún en desarrollo activo en esta versión. Trate las formas anteriores como el objetivo estructural alrededor del cual se construyen el modelo y el serializador, más que como una garantía de que cada campo haga un round-trip a través de un libro de trabajo guardado hoy.

Diagnósticos y estado compartido

DiagnosticBag, al que se accede mediante WorkbookModel::GetDiagnostics(), recoge registros DiagnosticEntry — cada uno con un GetCode(), un GetSeverity() (DiagnosticSeverity: Warning, Recoverable, o LossyRecoverable), un GetMessage(), una bandera GetRepairApplied() y una bandera GetDataLossRisk() — generados mientras se analiza o serializa un libro de trabajo. Esto se ejecuta junto a Workbook::GetLoadDiagnostics(), cuyos tipos LoadDiagnostics / LoadIssue a nivel de fachada comparten el mismo enum DiagnosticSeverity; el código que necesita el registro de modelo crudo en lugar del contenedor LoadIssue lo alcanza a través de GetDiagnostics() en el modelo del libro de trabajo.

SharedStringRepository respalda la tabla shared-strings de xlsx: GetValues() devuelve el vector de cadenas internadas, TryGetValue(index, value) resuelve un índice de vuelta al texto, y Intern(value) agrega o reutiliza una entrada — usado internamente cuando SaveOptions::SetUseSharedStrings(true) está configurado. DateSerialConverter convierte entre un DateTime y el número de serie al estilo OLE que Excel almacena en una celda, tomando un DateSystem para que los libros de trabajo basados en 1900 y 1904 se decodifiquen a la misma fecha del calendario.

Inicio rápido

Agregue la biblioteca a un proyecto CMake como subdirectorio y vincule el objetivo que define:

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

El siguiente ejemplo escribe una celda a través de la fachada, luego accede al modelo subyacente para obtener una bolsa de diagnóstico y un análisis CellAddress — la misma operación que WorksheetModel::GetCells() usa internamente para indexar su mapa de celdas:

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

Formatos compatibles

FormatoExtensiónLeerEscribir
XLSX.xlsx✓✓

La capa de modelo descrita aquí es la representación en memoria sobre la que operan el lector y el escritor de xlsx; no está vinculada a ningún formato de archivo adicional más allá de la importación/exportación Xlsx que soporta el resto de la biblioteca.

Código abierto y licencias

Aspose.Cells FOSS para C++ tiene licencia MIT. El código fuente, incluidos los encabezados de modelo Aspose::Cells_FOSS::Core referenciados en esta publicación, está en GitHub; se permite el uso comercial, la modificación y la redistribución.

Primeros pasos

Recursos relacionados