مقدمه
Aspose.Cells FOSS برای TypeScript عملکرد خود را از طریق مجموعهای فشرده از کلاسهای اصلی ارائه میدهد: Workbook، WorksheetCollection، Worksheet، Cell و Style، بههمراه انواع پشتیبانی برای قالببندی و فیلتر کردن. این پست یک مرور نظاممند بر سطح اصلی API است – نه یک موضوع محدود، بلکه اصول اولیهای که هر برنامهای ساختهشده بر پایه کتابخانه از آن استفاده میکند: باز کردن و ذخیرهسازی کتابکارها، مرور شیتها، خواندن و نوشتن مقادیر و فرمولهای سلول، اعمال سبکها، فیلتر کردن دادهها، و صادرات به قالبهای دیگر.
هر بخش زیر یک حوزه از API را با روشها و ویژگیهای مشخص مربوطه پوشش میدهد، بههمراه مثالهای عملی TypeScript. هدف این است که یک مدل ذهنی عملی از نحوه ترکیب قطعات به شما بدهیم، از new Workbook() تا ویژگیهای جداگانه Cell.
ویژگیهای کلیدی
مبانی Workbook و Worksheet
یک 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");
دسترسی به سلولها و مقادیر
یک 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 و مارکداون
فراتر از .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 برای TypeScript تحت مجوز MIT منتشر شده است. کد منبع در GitHub در دسترس است. استفاده تجاری تحت شرایط مجوز MIT مجاز است.