Введение

Aspose.Cells FOSS для TypeScript раскрывает свою функциональность через компактный набор базовых классов: Workbook, WorksheetCollection, Worksheet, Cell и Style, а также поддерживающих типов для форматирования и фильтрации. Эта статья представляет собой систематический обзор этого базового API уровня — не одну узкую тему, а фундаментальные возможности, которые использует каждое приложение, построенное на библиотеке: открытие и сохранение workbooks, навигацию по worksheets, чтение и запись cell values и формул, применение стилей, фильтрацию данных и экспорт в другие форматы.

Каждый раздел ниже охватывает одну область API с конкретными методами и свойствами, подкреплёнными работающими примерами TypeScript. Цель — предоставить вам рабочую ментальную модель того, как части сочетаются вместе, от new Workbook() до отдельных свойств Cell.

Ключевые возможности

Workbook и Worksheet Fundamentals

Workbook либо создаётся пустым с помощью new Workbook(), либо загружается асинхронно из существующего файла с помощью Workbook.load(filePath, password). Каждый workbook раскрывает worksheets, WorksheetCollection, который поддерживает индексацию, итерацию и методы массивного стиля (map, filter, forEach, find, indexOf) в дополнение к 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");

Доступ к Cell и значения

Объект 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(). Примените готовый Style к ячейке с помощью 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");

Автофильтрация с классом 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 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);

Поддерживаемые форматы

ФорматРасширениеЧтениеЗапись
XLSX.xlsx✓✓
HTML.html✓✓
CSV.csv—✓
JSON.json—✓
Markdown.md—✓

Открытый исходный код и лицензирование

Aspose.Cells FOSS для TypeScript выпущен под лицензией MIT. Исходный код доступен на GitHub. Коммерческое использование разрешено в соответствии с условиями лицензии MIT.

Начало работы

Связанные ресурсы