الميزات
الميزات
Aspose.Cells FOSS for .NET هي مكتبة .NET مُدارة بحتة لإنشاء وقراءة وتعديل جداول Excel XLSX. نقطة الدخول هي الفئة Workbook، التي توفر الوصول إلى أوراق العمل، الأسماء المعرفة، وعمليات الحفظ/التحميل. تلخص هذه الصفحة كل مجال ميزة رئيسي مع أمثلة شفرة مختصرة.
إنشاء دفتر العمل، التحميل، والحفظ
إنشاء دفتر عمل جديد باستخدام new Workbook(). تحميل ملف XLSX موجود بتمرير مسار الملف إلى المُنشئ. استخدم LoadOptions لتمكين التحميل المتسامح مع الأخطاء. استدعِ Workbook.Save(path) لحفظ التغييرات.
using Aspose.Cells_FOSS;
// New workbook
var wb = new Workbook();
wb.Worksheets[0].Cells["A1"].PutValue("Hello");
wb.Save("output.xlsx");
// Load with repair options
var opts = new LoadOptions { TryRepairPackage = true, TryRepairXml = true };
try
{
var loaded = new Workbook("input.xlsx", opts);
Console.WriteLine(loaded.Worksheets[0].Cells["A1"].StringValue);
}
catch (WorkbookLoadException ex)
{
Console.WriteLine("Load failed: " + ex.Message);
}بيانات الخلية والصيغ
استخدم Cell.PutValue() لكتابة السلاسل، الأعداد الصحيحة، الأعداد العشرية، القيم المنطقية، وDateTime. اضبط Cell.Formula لتعيين سلسلة صيغة متوافقة مع Excel. اقرأ النص المعروض مرة أخرى عبر Cell.StringValue والقيمة الخام عبر Cell.Value.
using Aspose.Cells_FOSS;
var wb = new Workbook();
var ws = wb.Worksheets[0];
ws.Cells["A1"].PutValue("Qty");
ws.Cells["B1"].PutValue("Price");
ws.Cells["C1"].PutValue("Total");
ws.Cells["A2"].PutValue(10);
ws.Cells["B2"].PutValue(4.99m);
ws.Cells["C2"].Formula = "=A2*B2";
wb.Save("data.xlsx");
var loaded = new Workbook("data.xlsx");
Console.WriteLine(loaded.Worksheets[0].Cells["C2"].StringValue); // 49.9تنسيق الخلية
استرجع وعدل كائن Style لأي خلية تحتوي على Cell.GetStyle() و Cell.SetStyle(). توفر فئة Style Font (عريض، مائل، حجم، اسم)، ForegroundColor، Pattern (من نوع FillPattern)، HorizontalAlignment (باستخدام HorizontalAlignmentType)، والتحكم في الحدود عبر Borders.
using Aspose.Cells_FOSS;
var wb = new Workbook();
var cell = wb.Worksheets[0].Cells["A1"];
cell.PutValue("Styled Header");
var style = cell.GetStyle();
style.Font.Bold = true;
style.Font.Size = 14;
style.Pattern = FillPattern.Solid;
style.ForegroundColor = System.Drawing.Color.FromArgb(255, 198, 239, 206);
style.HorizontalAlignment = HorizontalAlignmentType.Center;
cell.SetStyle(style);
wb.Save("styled.xlsx");التنسيق الشرطي
Worksheet.ConditionalFormattings تُعيد ConditionalFormattingCollection. استدعِ Add() لإنشاء مجموعة قواعد، ثم AddCondition() لإضافة القواعد باستخدام FormatConditionType وOperatorType. تشمل أنواع الشروط المدعومة CellValue، Expression، ColorScale، DataBar، وIconSet.
using Aspose.Cells_FOSS;
var wb = new Workbook();
var ws = wb.Worksheets[0];
for (var i = 0; i < 10; i++)
ws.Cells[i, 0].PutValue(i + 1);
var ruleSet = ws.ConditionalFormattings[ws.ConditionalFormattings.Add()];
ruleSet.AddArea(CellArea.CreateCellArea("A1", "A10"));
var rule = ruleSet[ruleSet.AddCondition(FormatConditionType.CellValue, OperatorType.Between, "3", "7")];
var ruleStyle = rule.Style;
ruleStyle.Pattern = FillPattern.Solid;
ruleStyle.ForegroundColor = System.Drawing.Color.FromArgb(255, 255, 199, 206);
rule.Style = ruleStyle;
wb.Save("cf.xlsx");التحقق من صحة البيانات
Worksheet.Validations تُعيد ValidationCollection. استدعِ Add(CellArea) لإنشاء Validation لنطاق الخلايا. اضبط خاصية Type باستخدام ValidationType (List، Decimal، أو Custom). قم بتكوين Formula1، Formula2، Operator، InputTitle، InputMessage، ErrorTitle، وErrorMessage.
using Aspose.Cells_FOSS;
var wb = new Workbook();
var ws = wb.Worksheets[0];
var listVal = ws.Validations[ws.Validations.Add(CellArea.CreateCellArea("A1", "A10"))];
listVal.Type = ValidationType.List;
listVal.Formula1 = "\"Open,Closed,Pending\"";
listVal.InCellDropDown = true;
var numVal = ws.Validations[ws.Validations.Add(CellArea.CreateCellArea("B1", "B10"))];
numVal.Type = ValidationType.Decimal;
numVal.Operator = OperatorType.Between;
numVal.Formula1 = "0";
numVal.Formula2 = "100";
numVal.ShowError = true;
wb.Save("validation.xlsx");الفلتر التلقائي
Worksheet.AutoFilter يعرض كائن AutoFilter. قم بتعيين AutoFilter.Range لتحديد نطاق صف العنوان. الوصول إلى AutoFilter.FilterColumns (FilterColumnCollection) واستدعاء Add(columnIndex) لتفعيل التصفية على عمود محدد.
using Aspose.Cells_FOSS;
var wb = new Workbook();
var ws = wb.Worksheets[0];
ws.Cells["A1"].PutValue("Name");
ws.Cells["B1"].PutValue("Region");
ws.Cells["C1"].PutValue("Sales");
ws.Cells["A2"].PutValue("Alice"); ws.Cells["B2"].PutValue("North"); ws.Cells["C2"].PutValue(1200);
ws.AutoFilter.Range = "A1:C1";
ws.AutoFilter.FilterColumns.Add(1);
wb.Save("filter.xlsx");الروابط التشعبية والأسماء المعرفة
Worksheet.Hyperlinks هو HyperlinkCollection. استدعِ Add() لإدراج عناوين URL خارجية، مراجع خلايا داخلية، أو روابط بريدية. اضبط Hyperlink.TextToDisplay وHyperlink.ScreenTip للنص الموجه للمستخدم. Workbook.DefinedNames هو DefinedNameCollection؛ استدعِ Add(name, refersTo) لإنشاء نطاقات مسماة.
using Aspose.Cells_FOSS;
var wb = new Workbook();
var ws = wb.Worksheets[0];
ws.Cells["A1"].PutValue("Docs");
var link = ws.Hyperlinks[ws.Hyperlinks.Add("A1", 1, 1, "https://docs.aspose.org/cells/net/")];
link.TextToDisplay = "Documentation";
wb.DefinedNames[wb.DefinedNames.Add("DataRange", "Sheet1!$A$1:$D$10")].Comment = "Main data range";
wb.Save("links.xlsx");إعداد الصفحة
Worksheet.PageSetup يتحكم في هوامش الطباعة، الاتجاه، حجم الورق، منطقة الطباعة، صفوف/أعمدة العنوان، رؤوس الصفحات، تذييلات الصفحات، وفواصل الصفحات. استخدم PageOrientationType وPaperSizeType تعداد.
using Aspose.Cells_FOSS;
var wb = new Workbook();
var ps = wb.Worksheets[0].PageSetup;
ps.Orientation = PageOrientationType.Landscape;
ps.PaperSize = PaperSizeType.PaperA4;
ps.PrintArea = "$A$1:$H$50";
ps.CenterHeader = "My Report";
ps.CenterHorizontally = true;
ps.AddHorizontalPageBreak(25);
wb.Save("paged.xlsx");إدارة ورقة العمل
أضف، وأعد تسمية، وأخفِ، وأعد ترتيب أوراق العمل عبر WorksheetCollection.WorksheetCollection.Add(name) يُرجع فهرس الورقة الجديدة.
اضبط Worksheet.VisibilityType باستخدام VisibilityType.
دمج الخلايا باستخدام Cells.Merge() والتحكم في حجم الصف/العمود عبر Cells.Rows وCells.Columns.
using Aspose.Cells_FOSS;
var wb = new Workbook();
wb.Worksheets[0].Name = "Summary";
var dataIdx = wb.Worksheets.Add("Data");
wb.Worksheets[dataIdx].VisibilityType = VisibilityType.Hidden;
wb.Worksheets.ActiveSheetName = "Summary";
var ws = wb.Worksheets["Summary"];
ws.Cells["A1"].PutValue("Title");
ws.Cells.Merge(0, 0, 1, 4);
ws.Cells.Rows[0].Height = 30d;
ws.Cells.Columns[0].Width = 20d;
wb.Save("worksheets.xlsx");نصائح وأفضل الممارسات
- احرص دائمًا على التقاط
WorkbookLoadExceptionعند تحميل الملفات من مسارات يزودها المستخدم. - استخدم
Cell.PutValue()مع نوع .NET الدقيق الذي تنوي تخزينه — مرّرdecimalللعملة،DateTimeللتواريخ. - اقرأ
Cell.StringValueللنص المعروض؛ استخدمCell.Valueعندما تحتاج إلى كائن .NET الخام. - أنشئ مجموعات قواعد تنسيق شرطي على أوسع نطاق تحتاجه — قواعد كل صف مكلفة في الأوراق الكبيرة.
- استدعِ
wb.Save()مرة واحدة في النهاية بدلاً من بعد كل كتابة خلية.
المشكلات الشائعة
| المشكلة | السبب | الإصلاح |
|---|---|---|
WorkbookLoadException عند الفتح | بنية ZIP تالفة في XLSX | تعيين LoadOptions.TryRepairPackage = true |
الصيغة تُعيد StringValue فارغ | الصيغة لا تُعاد حسابها عند التحميل | الوصول إلى Cell.StringValue بعد جولة Workbook.Save() |
| عنوان الارتباط التشعبي يُظهر URL الخام | TextToDisplay غير مُعيّن | تعيين Hyperlink.TextToDisplay بعد Add() |
| علامة تبويب ورقة العمل غير مرئية | VisibilityType مُعيّن إلى Hidden | تعيين ws.VisibilityType = VisibilityType.Visible |
الأسئلة المتكررة
هل يتطلب Aspose.Cells FOSS لـ .NET Microsoft Office؟
لا. المكتبة هي شفرة مُدارة بحتة دون أي اعتماد على Office أو Excel أو COM interop.
ما هي صيغ الملفات المدعومة؟
XLSX (قراءة وكتابة). CSV و ODS و PDF و XLS الثنائي غير مدعوم في هذا الإصدار.
هل يمكنني استخدام هذه المكتبة في تطبيق تجاري؟
نعم. Aspose.Cells FOSS منشور تحت رخصة MIT، والتي تسمح بالاستخدام التجاري غير المقيد دون أي عوائد.
ما هو الحد الأدنى لإصدار .NET؟
.NET 6.0 أو أحدث.
كيف يمكنني تطبيق لون خلفية على خلية؟
قم بتعيين style.Pattern = FillPattern.Solid و style.ForegroundColor = System.Drawing.Color.FromArgb(...)، ثم استدعِ cell.SetStyle(style).
ملخص مرجع API
| Class / Method | Description |
|---|---|
Workbook | الفئة الجذرية — إنشاء، تحميل، حفظ دفاتر العمل |
Workbook.Worksheets | إرجاع WorksheetCollection |
Workbook.Save(path) | حفظ دفتر العمل إلى القرص |
Workbook.DefinedNames | مجموعة النطاقات المسماة |
Worksheet.Cells | الوصول إلى شبكة الخلايا |
Worksheet.ConditionalFormattings | مجموعات قواعد التنسيق الشرطي |
Worksheet.Validations | قواعد التحقق من صحة البيانات |
Worksheet.AutoFilter | تكوين الفلتر التلقائي |
Worksheet.Hyperlinks | مجموعة الروابط التشعبية |
Worksheet.PageSetup | إعدادات تخطيط الطباعة |
Cell.PutValue() | كتابة بيانات الخلية ذات النوع المحدد |
Cell.Formula | سلسلة الصيغة المتوافقة مع Excel |
Cell.GetStyle() / Cell.SetStyle() | قراءة/كتابة نمط الخلية |
Style.Pattern | نمط التعبئة (FillPattern enum) |
Style.HorizontalAlignment | محاذاة الخلية (HorizontalAlignmentType) |
LoadOptions | خيارات تحميل الملفات المتسامحة مع الأخطاء |