المقدمة

Aspose.Cells FOSS لـ TypeScript يعرّف وظيفته من خلال مجموعة مدمجة من الفئات الأساسية: Workbook، WorksheetCollection، Worksheet، Cell، وStyle، بالإضافة إلى الأنواع الداعمة للتنسيق والتصفية. هذه المقالة جولة منهجية على سطح API الأساسي – ليست موضوعًا ضيقًا واحدًا، بل الأساسيات التي تستخدمها كل تطبيق يُبنى على المكتبة: فتح وحفظ دفاتر العمل، التنقل بين أوراق العمل، قراءة وكتابة قيم الخلايا والصيغ، تطبيق الأنماط، تصفية البيانات، وتصدير إلى صيغ أخرى.

كل قسم أدناه يغطي مجالًا واحدًا من API مع الأساليب والخصائص الملموسة المتضمنة، مدعومًا بأمثلة TypeScript عملية. الهدف هو أن تزودك بنموذج ذهني عملي لكيفية تجميع الأجزاء معًا، من new Workbook() إلى خصائص Cell الفردية.

الميزات الرئيسية

أساسيات دفتر العمل وورقة العمل

يمكن إما إنشاء Workbook فارغًا باستخدام new Workbook() أو تحميله بشكل غير متزامن من ملف موجود باستخدام Workbook.load(filePath, password). كل دفتر عمل يُظهر 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، و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.

بدء الاستخدام

الموارد ذات الصلة