Introdução

Aspose.Cells FOSS para TypeScript expõe sua funcionalidade por meio de um conjunto compacto de classes principais: Workbook, WorksheetCollection, Worksheet, Cell e Style, além de tipos de suporte para formatação e filtragem. Este post é um tour sistemático dessa superfície central API — não um tópico estreito único, mas os fundamentos que toda aplicação construída sobre a biblioteca acaba usando: abrir e salvar workbooks, navegar entre worksheets, ler e escrever valores e fórmulas de células, aplicar estilos, filtrar dados e exportar para outros formatos.

Cada seção abaixo cobre uma área do API com os métodos e propriedades concretos envolvidos, sustentados por exemplos funcionais de TypeScript. O objetivo é fornecer a você um modelo mental funcional de como as peças se encaixam, de new Workbook() até propriedades individuais de Cell.

Principais recursos

Fundamentos de Workbook e Worksheet

Um Workbook é criado vazio com new Workbook() ou carregado assincronamente de um arquivo existente com Workbook.load(filePath, password). Cada workbook expõe worksheets, um WorksheetCollection que suporta indexação, iteração e métodos ao estilo de array (map, filter, forEach, find, indexOf) além de addWorksheet(name), removeWorksheet(index) e moveWorksheet(fromIndex, toIndex). Chame workbook.save(filePath, options) para persistir as alterações.

const workbook = new Workbook();

const ws1 = workbook.worksheets.addWorksheet();
const ws2 = workbook.worksheets.addWorksheet("CustomSheet1");
console.log("Total worksheets:", workbook.worksheets.length);

workbook.worksheets.removeWorksheet(1);
console.log("After delete:", workbook.worksheets.length);

console.log(
  "Names:",
  workbook.worksheets.worksheets.map((w) => w.name),
);

await workbook.save("workbook.xlsx");

Acesso a células e valores

Uma Worksheet lê e grava células através de putValue(key, value), getCell2(key) (retorna um Cell, criando-o se ausente), getCell(row, col) (retorna Cell | undefined), e getCellByRef(ref). Cada Cell expõe value, formula, row, col e ref como propriedades, e setFormula() / setStyle() / setHyperlink() como métodos.

const workbook = new Workbook();
const sheet = workbook.worksheets[0]!;

sheet.putValue("A1", 42);
sheet.putValue("A2", "Hello World");

const formulaCell = sheet.getCell2("A3");
formulaCell.setFormula("=A1+10");

console.log("A1 value:", sheet.getCell(0, 0)?.value);
console.log("A3 formula:", sheet.getCell(2, 0)?.formula);

const byRef = sheet.getCellByRef("A1");
console.log("Ref:", byRef?.ref, "Row:", byRef?.row, "Col:", byRef?.col);

await workbook.save("cells.xlsx");

Estilo, Fonte, Borda e Alinhamento

Style agrupa configurações de fonte, preenchimento, borda, alinhamento e formato numérico para uma célula. Leia ou substitua objetos inteiros com getFont()/setFont(), getBorder()/setBorder() e getAlignment()/setAlignment(), ou use os setters de conveniência diretamente em Style, como setFontName(), setFontSize(), setBold(), setHorizontalAlignment() e setNumberFormat(). Aplique o Style finalizado a uma célula com Cell.setStyle().

const workbook = new Workbook();
const sheet = workbook.worksheets[0]!;

const style = new Style();
style.setFontName("Arial");
style.setFontSize(14);
style.setBold(true);
style.setNumberFormat("0.00");

style.getBorder().bottom = { style: "thin", color: "000000" };

style.setHorizontalAlignment("center");
style.setVerticalAlignment("center");
style.setWrapText(true);

const cell = sheet.getCell2("B2");
cell.putValue(1234.5);
cell.setStyle(style);

console.log("Bold:", style.isBold(), "Format:", style.getNumberFormat());

await workbook.save("styled.xlsx");

Filtragem automática com a classe AutoFilter

Worksheet.setAutoFilter(range) é um atalho para o caso comum, mas a classe subjacente AutoFilter também pode ser usada diretamente: construa-a com um intervalo, então chame addFilterColumn(col, filters, blank) por coluna para definir quais valores devem permanecer visíveis, ou removeFilterColumn(col) / clear() para desfazer a filtragem.

const workbook = new Workbook();
const sheet = workbook.worksheets[0]!;

sheet.putValue("A1", "Name");
sheet.putValue("B1", "City");
sheet.putValue("A2", "Alice");
sheet.putValue("B2", "New York");
sheet.putValue("A3", "Bob");
sheet.putValue("B3", "London");

const filter = new AutoFilter("A1:B3");
filter.addFilterColumn(1, ["New York"], false);

console.log("Filter range:", filter.range);
console.log("Filter columns:", filter.columns.length);

await workbook.save("filtered.xlsx");

Exportando para HTML, CSV, JSON e Markdown

Além de .xlsx, um Workbook pode renderizar-se diretamente como texto com toHtml(), toCsv(), toJson() e toMarkdown(), ou ser salvo em um arquivo cuja extensão seleciona o formato via o enum SaveFormat (XLSX, CSV, JSON, MARKDOWN, HTML).

const workbook = new Workbook();
const sheet = workbook.worksheets[0]!;

sheet.putValue("A1", "Name");
sheet.putValue("B1", "Age");
sheet.putValue("A2", "Alice");
sheet.putValue("B2", 25);
sheet.putValue("A3", "Bob");
sheet.putValue("B3", 30);

console.log("JSON:", workbook.toJson());
console.log("Markdown:\n", workbook.toMarkdown());

await workbook.save("report.csv");
await workbook.save("report.html");

Início rápido

git clone https://github.com/aspose-cells-foss/Aspose.Cells-FOSS-for-TypeScript.git
cd Aspose.Cells-FOSS-for-TypeScript
npm install
npm run build
import { Workbook, Style } from "excel-cells";

const workbook = new Workbook();
const sheet = workbook.worksheets.get(0)!;
sheet.name = "Summary";

sheet.putValue("A1", "Item");
sheet.putValue("B1", "Count");
sheet.putValue("A2", "Widgets");
sheet.putValue("B2", 12);
sheet.putValue("A3", "Gadgets");
sheet.putValue("B3", 7);

const totalCell = sheet.getCell2("B4");
totalCell.setFormula("=SUM(B2:B3)");

const numberStyle = new Style();
numberStyle.setNumberFormat("0");
sheet.getCell2("B2").setStyle(numberStyle);
sheet.getCell2("B3").setStyle(numberStyle);
sheet.getCell2("B4").setStyle(numberStyle);

const detail = workbook.worksheets.addWorksheet("Detail");
detail.putValue("A1", "Raw Data");

await workbook.save("summary.xlsx");

const reloaded = await Workbook.load("summary.xlsx");
console.log("Worksheets:", reloaded.worksheets.length);
console.log("B4 formula:", reloaded.worksheets.get(0)!.getCell(3, 1)?.formula);

Formatos suportados

FormatoExtensãoLerEscrever
XLSX.xlsx✓✓
HTML.html✓✓
CSV.csv—✓
JSON.json—✓
Markdown.md—✓

Código aberto e licenciamento

Aspose.Cells FOSS para TypeScript é lançado sob a licença MIT. O código-fonte está disponível em GitHub. O uso comercial é permitido sob os termos da licença MIT.

Começando

Recursos Relacionados