Introdução
Gerenciamento de planilhas é a parte do Aspose.Cells FOSS para C++ que a maioria dos programas toca primeiro: o Workbook que possui o arquivo, os objetos Worksheet dentro dele e a coleção Cells que contém valores, fórmulas e formatação. Este post explora essa superfície com mais profundidade do que uma introdução geral — como workbooks e worksheets são criados e navegados, como valores e fórmulas de células são lidos e gravados, como Style, Font, Color e Borders se combinam para formatar a saída, e como PageSetup, Hyperlink, DefinedName e Validation adicionam estrutura ao redor da grade bruta de células.
Cada classe abordada aqui faz parte da API nativa de C++ declarada nos cabeçalhos aspose/cells_foss/. Não há interoperabilidade COM nem dependência da instalação do Microsoft Excel — a biblioteca lê e grava o formato de pacote .xlsx diretamente, o que também explica por que a versão atual suporta apenas .xlsx, tanto na carga quanto na gravação.
Os exemplos abaixo se acumulam: um workbook é criado, worksheets e células são preenchidos, o estilo é aplicado e o arquivo é salvo e recarregado para confirmar o ciclo completo. Todo o código foi adaptado das próprias suítes de compatibilidade, golden e testes unitários da biblioteca, de modo que reflete operações exercidas em saída real de .xlsx.
Recursos Principais
Gerenciamento de Workbook e Worksheet
Um Workbook começa com uma worksheet em seu WorksheetCollection. Worksheets são adicionadas com Add(), localizadas por índice ou por nome, e renomeadas com SetName(). WorksheetCollection também rastreia qual planilha está ativa:
#include "aspose/cells_foss/Workbook.h"
#include "aspose/cells_foss/Worksheet.h"
using namespace Aspose::Cells_FOSS;
Workbook workbook;
Worksheet& sheet = workbook.GetWorksheets()[0];
sheet.SetName("Data");
int summaryIndex = workbook.GetWorksheets().Add("Summary");
workbook.GetWorksheets().SetActiveSheetIndex(0);
int sheetCount = workbook.GetWorksheets().GetCount(); // 2
Salvar e recarregar passam pelo mesmo tipo Workbook. Workbook::Save() aceita um caminho de arquivo, e um Workbook pode ser construído diretamente a partir de um caminho ou de um buffer de bytes em memória, o que faz o round-trip dos valores e fórmulas das células:
workbook.Save("report.xlsx");
Workbook loaded("report.xlsx");
Worksheet& reloadedSheet = loaded.GetWorksheets()["Data"];
Valores de Células e Fórmulas
Cells, acessado através de Worksheet::GetCells(), indexa células por referência no estilo A1. Cell::PutValue() aceita strings, inteiros, doubles e booleanos, SetFormula() armazena uma string de fórmula do Excel, e GetValue() devolve um CellValue com acessores tipados (AsString(), AsInteger(), AsDouble(), AsBool(), AsDateTime()):
Cells& cells = sheet.GetCells();
cells["A1"].PutValue("Category");
cells["B1"].PutValue("Amount");
cells["A2"].PutValue("Travel");
cells["B2"].PutValue(482.50);
cells["A3"].PutValue("Supplies");
cells["B3"].PutValue(129.99);
cells["B4"].SetFormula("=SUM(B2:B3)");
CellValue amount = cells["B2"].GetValue();
if (amount.IsDouble()) {
double value = amount.AsDouble();
}
std::string formula = cells["B4"].GetFormula();
Cell::GetType() relata o CellValueType armazenado (Blank, String, Number, Boolean, DateTime ou Formula), e GetDisplayStringValue() devolve o valor formatado da maneira que apareceria no Excel, respeitando qualquer formato numérico aplicado através de Style.
Estilizando com Style, Font, Color e Borders
Cell::GetStyle() devolve um objeto Style que pode ser modificado e reaplicado com SetStyle(). Style expõe um Font, um conjunto Borders, padrão de preenchimento e cor, alinhamento e formato numérico:
#include "aspose/cells_foss/Style.h"
#include "aspose/cells_foss/Color.h"
Cell headerCell = sheet.GetCells()["A1"];
Style style = headerCell.GetStyle();
Font font = style.GetFont();
font.SetBold(true);
font.SetColor(Color::FromArgb(255, 255, 255, 255));
style.SetFont(font);
style.SetPattern(FillPattern::Solid);
style.SetForegroundColor(Color::FromArgb(255, 34, 120, 212));
style.SetHorizontalAlignment(HorizontalAlignmentType::Center);
Borders borders = style.GetBorders();
Border bottomBorder = borders.GetBottom();
bottomBorder.SetLineStyle(BorderStyleType::Thin);
borders.SetBottom(bottomBorder);
style.SetBorders(borders);
style.SetNumberFormat("#,##0.00");
headerCell.SetStyle(style);
Style é um tipo de valor: ler de volta com GetStyle() reflete o que foi definido por último com SetStyle(), o que torna simples criar um estilo e aplicá-lo em toda a linha de cabeçalho ou em um intervalo de células de dados.
Configuração de Página e Configuração de Impressão
Worksheet::GetPageSetup() retorna um objeto PageSetup que cobre tamanho de papel, orientação, margens, escala, títulos de impressão e quebras de página:
#include "aspose/cells_foss/PageSetup.h"
PageSetup& pageSetup = sheet.GetPageSetup();
pageSetup.SetOrientation(PageOrientationType::Landscape);
pageSetup.SetPaperSize(PaperSizeType::PaperA4);
pageSetup.SetFitToPagesWide(1);
pageSetup.SetFitToPagesTall(0);
pageSetup.SetPrintArea("$A$1:$D$20");
pageSetup.SetPrintTitleRows("$1:$1");
pageSetup.SetLeftMargin(0.5);
pageSetup.SetCenterFooter("Page &P of &N");
pageSetup.AddHorizontalPageBreak(20);
As margens estão disponíveis tanto em unidades brutas (GetLeftMargin()) quanto em polegadas (GetLeftMarginInch()), e GetHorizontalPageBreaks() / GetVerticalPageBreaks() retornam as posições de quebra de página atualmente definidas na planilha.
Hyperlinks, Nomes Definidos e Validação de Dados
Worksheet::GetHyperlinks() retorna um HyperlinkCollection. Add() recebe uma célula ou intervalo de destino mais um endereço e retorna o índice do novo hyperlink, que é usado para obter o objeto Hyperlink para alterações adicionais:
#include "aspose/cells_foss/Hyperlink.h"
sheet.GetCells()["A1"].PutValue("Documentation");
int linkIndex = sheet.GetHyperlinks().Add("A1", 1, 1, "https://example.com/docs");
Hyperlink link = sheet.GetHyperlinks()[linkIndex];
link.SetTextToDisplay("Documentation");
link.SetScreenTip("Open the docs site");
Workbook::GetDefinedNames() gerencia intervalos nomeados da mesma forma — Add() retorna um índice para o DefinedNameCollection:
#include "aspose/cells_foss/DefinedName.h"
int nameIndex = workbook.GetDefinedNames().Add("Total", "=Data!$B$2:$B$3");
DefinedName total = workbook.GetDefinedNames()[nameIndex];
total.SetComment("Sum of tracked expenses");
Worksheet::GetValidations() segue o mesmo padrão de coleção para regras de validação de dados, limitadas a um CellArea:
#include "aspose/cells_foss/Validation.h"
#include "aspose/cells_foss/CellArea.h"
int ruleIndex = sheet.GetValidations().Add(CellArea::CreateCellArea("B2", "B3"));
Validation amountRule = sheet.GetValidations()[ruleIndex];
amountRule.SetType(ValidationType::Decimal);
amountRule.SetOperator(OperatorType::GreaterThan);
amountRule.SetFormula1("0");
amountRule.SetErrorTitle("Invalid Amount");
amountRule.SetErrorMessage("Enter a positive number");
Propriedades do Documento e Configurações da Pasta de Trabalho
Workbook::GetDocumentProperties() expõe os campos de metadados OOXML principais e estendidos (título, autor, empresa, gerente e similares), e Workbook::GetSettings() controla o comportamento ao nível da pasta de trabalho, como o sistema de datas:
#include "aspose/cells_foss/DocumentProperties.h"
workbook.GetDocumentProperties().SetCompany("Example Corp");
workbook.GetDocumentProperties().SetManager("Finance Team");
workbook.GetSettings().SetDate1904(false);
Esses valores passam por salvar e recarregar da mesma forma que o conteúdo das células, o que é útil para relatórios que precisam de metadados consistentes em arquivos gerados.
Início Rápido
Aspose.Cells FOSS para C++ é construído a partir do código-fonte com CMake. Clone o repositório e adicione-o como um subdiretório ou importe-o com FetchContent:
git clone https://github.com/aspose-cells-foss/Aspose.Cells-FOSS-for-Cpp.git
cmake_minimum_required(VERSION 3.15)
project(MyProject CXX)
set(CMAKE_CXX_STANDARD 17)
add_subdirectory(path/to/Aspose.Cells-FOSS-for-Cpp)
add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE Aspose.Cells.Foss.Cpp)
Um exemplo mínimo de gerenciamento de planilhas — criar, estilizar, salvar e recarregar:
#include "aspose/cells_foss/Workbook.h"
#include "aspose/cells_foss/Worksheet.h"
#include "aspose/cells_foss/Cell.h"
using namespace Aspose::Cells_FOSS;
int main() {
Workbook workbook;
Worksheet& sheet = workbook.GetWorksheets()[0];
sheet.SetName("Expenses");
Cells& cells = sheet.GetCells();
cells["A1"].PutValue("Category");
cells["B1"].PutValue("Amount");
cells["A2"].PutValue("Travel");
cells["B2"].PutValue(482.50);
cells["A3"].PutValue("Supplies");
cells["B3"].PutValue(129.99);
cells["B4"].SetFormula("=SUM(B2:B3)");
workbook.Save("expenses.xlsx");
Workbook loaded("expenses.xlsx");
Cells& loadedCells = loaded.GetWorksheets()["Expenses"].GetCells();
double total = loadedCells["B4"].GetValue().AsDouble();
return 0;
}
Formatos Suportados
| Formato | Extensão | Ler | Escrever |
|---|---|---|---|
| Xlsx | .xlsx | ✓ | ✓ |
LoadFormat e SaveFormat ambos expõem um único valor Xlsx nesta versão; os construtores Workbook(path) e Workbook(bytes) carregam entrada .xlsx, e Workbook::Save() grava saída .xlsx para um caminho, um fluxo ou um buffer em memória.
Código Aberto & Licenciamento
Aspose.Cells FOSS para C++ é lançado sob a licença MIT. O código-fonte está disponível em GitHub, e a biblioteca pode ser usada, modificada e redistribuída em projetos comerciais e de código aberto sem taxas de tempo de execução.
