介绍
Aspose.Cells FOSS 为 TypeScript 提供了一个紧凑的核心类集合：Workbook、WorksheetCollection、Worksheet、Cell 和 Style，以及用于格式化和过滤的支持类型。本文系统地巡览了该核心 API 表面——不是单一的狭窄主题，而是每个基于该库的应用最终都会使用的基础：打开和保存工作簿、导航工作表、读取和写入单元格值与公式、应用样式、过滤数据以及导出为其他格式。
下面的每个章节都涵盖了 API 的一个方面，列出相关的具体方法和属性，并配有可运行的 TypeScript 示例。目标是为您提供一个可操作的思维模型，了解各部分如何协同工作，从 new Workbook() 到单个 Cell 属性。
关键特性
工作簿和工作表基础
可以使用 new Workbook() 创建一个空的 Workbook，或通过 Workbook.load(filePath, password) 异步加载已有文件来创建。每个工作簿都公开 worksheets，这是一个支持索引、迭代以及数组式方法（map、filter、forEach、find、indexOf）的 WorksheetCollection，此外还有 addWorksheet(name)、removeWorksheet(index) 和 moveWorksheet(fromIndex, toIndex)。调用 workbook.save(filePath, options) 以持久化更改。
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");
单元格访问与值
A Worksheet 通过 putValue(key, value)、getCell2(key)（返回一个 Cell，如果不存在则创建）、getCell(row, col)（返回 Cell | undefined）和 getCellByRef(ref) 读取和写入单元格。每个 Cell 将 value、formula、row、col 和 ref 公开为属性，并将 setFormula() / setStyle() / setHyperlink() 公开为方法。
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");
样式、字体、边框和对齐
Style 将字体、填充、边框、对齐和数字格式设置组合在一起，用于单元格。可以使用 getFont()/setFont()、getBorder()/setBorder() 和 getAlignment()/setAlignment() 读取或替换整个子对象，或直接在 Style 上使用便捷的设置器，例如 setFontName()、setFontSize()、setBold()、setHorizontalAlignment() 和 setNumberFormat()。使用 Cell.setStyle() 将完成的 Style 应用于单元格。
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");
使用 AutoFilter 类进行自动筛选
Worksheet.setAutoFilter(range) 是常见情况的快捷方式，但底层的 AutoFilter 类也可以直接使用：使用范围构造它，然后对每列调用 addFilterColumn(col, filters, blank) 来定义哪些值应保持可见，或使用 removeFilterColumn(col) / clear() 来撤销筛选。
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");
导出到 HTML、CSV、JSON 和 Markdown
除了 .xlsx，Workbook 还可以使用 toHtml()、toCsv()、toJson() 和 toMarkdown() 直接渲染为文本，或保存为文件，其扩展名通过 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");
快速入门
git clone https://github.com/aspose-cells-foss/Aspose.Cells-FOSS-for-TypeScript.git
cd Aspose.Cells-FOSS-for-TypeScript
npm install
npm run buildimport { 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);
支持的格式
| 格式 | 扩展名 | 读取 | 写入 |
|---|---|---|---|
| XLSX | .xlsx | ✓ | ✓ |
| HTML | .html | ✓ | ✓ |
| CSV | .csv | — | ✓ |
| JSON | .json | — | ✓ |
| Markdown | .md | — | ✓ |
开源与许可
Aspose.Cells FOSS for TypeScript 在 MIT 许可证下发布。源代码可在 GitHub 获取。根据 MIT 许可证条款，允许商业使用。
