Introdução

Aspose.Cells FOSS para C++ é construído em duas camadas. A camada que a maioria do código toca é a fachada: Workbook, Worksheet, Cell e Style, que é o que os anúncios e posts de recursos para esta plataforma cobrem. Por baixo dela está uma segunda camada, no namespace Aspose::Cells_FOSS::Core, composta por registros de dados simples — WorkbookModel, WorksheetModel, CellRecord, StyleValue, e aproximadamente quatro dezenas de tipos relacionados *Model e *Value. Esses registros mantêm o estado real da planilha analisada: valores de célula indexados por CellAddress, atributos de estilo como StyleValue, configurações de workbook e worksheet, configuração de página, filtros e diagnósticos de carregamento. As classes da fachada leem e escrevem nesta camada ao invés de armazenar o estado por si mesmas.

A ponte entre as duas camadas é explícita e pública. Workbook::GetModel() devolve um Core::WorkbookModel, Worksheet::GetModel() devolve um Core::WorksheetModel, e Style::ToCore() / Style::FromCore() convertem um Style mutável para e de um Core::StyleValue. DocumentProperties::GetModel() e ExtendedDocumentProperties::GetModel() fazem o mesmo para metadados de documento. Um consumidor acessa essa camada diretamente em um conjunto mais restrito de casos do que o cotidiano API de edição de células: inspecionar o DiagnosticBag registrado enquanto um workbook era carregado ou salvo, normalizar um estilo através do StyleRepository ao nível do workbook, ou trabalhar diretamente com os registros plain-old-data de célula e linha ao invés dos objetos wrapper Cell / Row.

Tudo o que é descrito aqui é distribuído na mesma árvore de código fonte livre de dependências e licenciada sob MIT que o resto do Aspose.Cells FOSS para C++, construída com CMake e incluída como cabeçalhos e código fonte ao invés de um binário pré-compilado. Se você ainda não trabalhou com a fachada API, comece primeiro pelo post de recursos Workbook/Worksheet/Cell — este post parte desse fundamento e foca no que está por baixo dele.

O que está incluído

Árvore do Modelo Workbook e Worksheet

Core::WorkbookModel é o registro raiz. GetWorksheets() devolve um std::deque<WorksheetModel>, GetSettings() um WorkbookSettingsModel, GetProperties() um WorkbookPropertiesModel, GetDocumentProperties() um DocumentPropertiesModel, GetDiagnostics() um DiagnosticBag, GetStyles() um StyleRepository, GetSharedStrings() um SharedStringRepository, e GetDefaultStyle() / SetDefaultStyle() um StyleValue. Também rastreia GetActiveSheetIndex() e um std::vector<DefinedNameModel> de GetDefinedNames(). Workbook::GetModel() é o ponto de entrada para este registro.

Core::WorksheetModel, acessado por meio de Worksheet::GetModel(), armazena células como std::unordered_map<CellAddress, CellRecord> via GetCells(), linhas como std::unordered_map<int, RowModel> via GetRows(), intervalos de colunas como std::vector<ColumnRangeModel> via GetColumns() e intervalos mesclados como std::vector<MergeRegion> via GetMergeRegions(). Também contém GetHyperlinks(), GetValidations(), GetConditionalFormattings(), GetPageSetup(), GetView(), GetProtection(), GetAutoFilter(), GetTabColor() e GetVisibility() (um valor SheetVisibility: Visible, Hidden ou VeryHidden).

CellAddress é o tipo de chave hashável usado para esse mapa de células. Ele analisa texto no estilo A1 em índices de linha/coluna baseados em zero e vice-versa — esta é uma das poucas classes neste cluster com cobertura de testes direta no repositório 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 contém o CellValue, CellValueKind de uma célula, uma string de fórmula opcional, um StyleValue e um sinalizador GetIsExplicitlyStored() que diferencia uma célula realmente escrita de uma que existe apenas porque um padrão de linha ou coluna a atinge. RowModel possui uma altura opcional, um sinalizador oculto e um índice de estilo opcional; ColumnRangeModel possui os mesmos três itens mais o intervalo de colunas mínimo/máximo ao qual se aplica. MergeRegion é um retângulo simples de primeira linha/primeira coluna/total de linhas/total de colunas.

Dados de Estilo como Valores Simples

StyleValue é a contraparte Core da fachada mutável Style — Style::ToCore() converte um Style em um, e Style::FromCore() cria um Style a partir de um. Ele agrupa GetFont() (FontValue), GetPattern() (FillPatternKind), GetForegroundColor() / GetBackgroundColor() (ColorValue), GetBorders() (BordersValue), GetAlignment() (AlignmentValue), GetProtection() (ProtectionValue) e GetNumberFormat() (NumberFormatValue), além de um StyleValue::Default() estático e um Clone(). FontValue espelha o campo Font campo por campo: nome, tamanho, negrito, itálico, sublinhado, tachado e um ColorValue. ColorValue em si é uma tupla ARGB simples (GetA(), GetR(), GetG(), GetB(), Equals(), GetHashCode()) — ao contrário da classe fachada Color, não possui uma fábrica no estilo FromArgb(), portanto um ColorValue normalmente é obtido de um estilo existente em vez de ser construído diretamente.

BordersValue contém cinco membros BorderSideValue — esquerda, direita, superior, inferior e diagonal — cada um combinando um valor enum BorderStyle com um ColorValue. AlignmentValue modela alinhamento horizontal e vertical, quebra de texto, nível de recuo, rotação de texto, encolher para caber e ordem de leitura. ProtectionValue e NumberFormatValue suportam os sinalizadores de proteção de célula e o par id de formato numérico/cadeia personalizada que Style expõe.

StyleRepository, acessado por meio de WorkbookModel::GetStyles(), expõe uma operação: Normalize(style) -> StyleValue. A pasta de trabalho o utiliza internamente ao carregar e salvar para internar estilos equivalentes em vez de duplicar registros StyleValue idênticos — não é um cache de estilo de uso geral com pesquisa baseada em índice na superfície atual do API.

Propriedades do Documento e Configurações ao Nível da Pasta de Trabalho

DocumentPropertiesModel agrupa GetCore() (CoreDocumentPropertiesModel: título, assunto, criador, palavras-chave, descrição, último-modificado-por, revisão, categoria, status do conteúdo e timestamps created/modified) e GetExtended() (ExtendedDocumentPropertiesModel: aplicação, versão da aplicação, empresa, gerente, segurança do documento, base de hyperlink e as flags scale-crop / links-up-to-date / shared-doc). DocumentProperties::GetModel() e ExtendedDocumentProperties::GetModel() fazem a ponte das classes fachada para esses registros.

WorkbookPropertiesModel espelha WorkbookProperties — nome do código, show-objects, privacidade de filtro, backup-file e flags relacionadas — e aninha WorkbookProtectionModel (bloquear estrutura/janelas/revisão, senha da pasta de trabalho e das revisões), WorkbookViewModel (posição e tamanho da janela, primeira planilha visível, visibilidade da barra de rolagem e da aba da planilha, proporção da aba, estado minimizado, agrupamento de datas do auto-filtro), e CalculationPropertiesModel (modo de cálculo, configurações de iteração, precisão total, cálculo concorrente). WorkbookSettingsModel carrega um valor DateSystem (Windows1900 ou Mac1904) e uma cultura de exibição — o contraparte a nível de modelo de WorkbookSettings::GetDate1904() / GetCulture(). A maioria dos tipos *Model neste grupo expõe CopyFrom(source) e HasStoredState(), que o serializer usa para distinguir um valor explicitamente definido de um padrão não definido antes de gravar XML.

Modelos de Recursos da Planilha

WorksheetProtectionModel espelha o campo WorksheetProtection campo por campo e adiciona os campos de senha armazenados — GetPasswordHash(), GetAlgorithmName(), GetHashValue(), GetSaltValue(), GetSpinCount() — que a fachada WorksheetProtection não expõe diretamente. WorksheetViewModel contém a visibilidade de linhas de grade, cabeçalho e zero, layout da direita para a esquerda e escala de zoom. PageSetupModel aninha PageMarginsModel (margens esquerda, direita, superior, inferior, de cabeçalho e de rodapé como doubles), PrintOptionsModel (linhas de grade, cabeçalhos, centralização horizontal e vertical), e HeaderFooterModel (texto do cabeçalho e rodapé à esquerda/central/direita), juntamente com tamanho do papel, orientação, escala, ajustar à largura/altura, área de impressão, linhas/colunas de título de impressão e vetores de quebra de página.

AutoFilterModel contém uma string de intervalo, um std::vector<FilterColumnModel> e um AutoFilterSortStateModel. FilterColumnModel por sua vez aninha AutoFilterColorFilterModel, AutoFilterDynamicFilterModel e AutoFilterTop10Model, além de uma lista simples de strings de valores de filtro e um std::vector<AutoFilterCustomFilterModel>. ConditionalFormattingModel combina um std::vector<CellArea> com um std::vector<FormatConditionModel> — cada condição transporta seu tipo, operador, fórmulas, campos de escala de cor/barras de dados/conjunto de ícones e um StyleValue para o formato resultante. ValidationModel e HyperlinkModel espelham as fachadas Validation e Hyperlink como registros simples, e DefinedNameModel espelha DefinedName. SheetVisibility é o enum da camada de modelo por trás de Worksheet::GetVisibilityType().

Algumas das funcionalidades da fachada que esses registros dão suporte — AutoFilter e ConditionalFormattingCollection em particular — são destacadas na documentação do produto como ainda em desenvolvimento ativo nesta versão. Considere as estruturas acima como o alvo estrutural em torno do qual o modelo e o serializador foram construídos, e não como uma garantia de que cada campo faça round-trip através de uma pasta de trabalho salva hoje.

Diagnósticos e Estado Compartilhado

DiagnosticBag, acessado via WorkbookModel::GetDiagnostics(), coleta registros DiagnosticEntry — cada um com um GetCode(), um GetSeverity() (DiagnosticSeverity: Warning, Recoverable ou LossyRecoverable), um GetMessage(), uma bandeira GetRepairApplied() e uma bandeira GetDataLossRisk() — gerados enquanto uma pasta de trabalho é analisada ou serializada. Isso ocorre em paralelo com Workbook::GetLoadDiagnostics(), cujos tipos de fachada LoadDiagnostics / LoadIssue compartilham o mesmo enum DiagnosticSeverity; código que precisa do registro de modelo bruto em vez do wrapper LoadIssue o obtém através de GetDiagnostics() no modelo da pasta de trabalho.

SharedStringRepository sustenta a tabela shared-strings do xlsx: GetValues() devolve o vetor de strings interning, TryGetValue(index, value) resolve um índice de volta ao texto, e Intern(value) adiciona ou reutiliza uma entrada — usado internamente quando SaveOptions::SetUseSharedStrings(true) está definido. DateSerialConverter converte entre um DateTime e o número de série no estilo OLE que o Excel armazena em uma célula, recebendo um DateSystem para que planilhas baseadas em 1900 e 1904 sejam decodificadas para a mesma data do calendário.

Início Rápido

Adicione a biblioteca a um projeto CMake como um subdiretório e vincule o alvo que ela define:

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

O exemplo abaixo grava uma célula através da fachada, depois acessa o modelo subjacente para obter um saco de diagnóstico e uma análise CellAddress — a mesma operação que WorksheetModel::GetCells() usa internamente para indexar seu mapa de células:

#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 Suportados

FormatoExtensãoLerEscrever
XLSX.xlsx✓✓

A camada de modelo descrita aqui é a representação em memória na qual o leitor e gravador xlsx operam; ela não está vinculada a nenhum formato de arquivo adicional além da importação/exportação Xlsx que o restante da biblioteca oferece suporte.

Código Aberto e Licenciamento

Aspose.Cells FOSS para C++ é licenciado sob MIT. O código-fonte, incluindo os cabeçalhos de modelo Aspose::Cells_FOSS::Core referenciados nesta postagem, está em GitHub; uso comercial, modificação e redistribuição são permitidos.

Primeiros Passos

Recursos Relacionados