Features

ویژگی‌ها

Aspose.Cells FOSS برای .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 (bold, italic, size, name)، 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 = Color.FromArgb(255, 198, 239, 206);
style.HorizontalAlignment = HorizontalAlignmentType.Center;
cell.SetStyle(style);

wb.Save("styled.xlsx");

قالب‌بندی شرطی

Worksheet.ConditionalFormattings یک ConditionalFormattingCollection برمی‌گرداند. برای ایجاد یک مجموعه قوانین، Add() را فراخوانی کنید، سپس برای افزودن قوانین با استفاده از FormatConditionType و OperatorType، AddCondition() کنید. انواع شرط‌های پشتیبانی‌شده شامل 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 = Color.FromArgb(255, 255, 199, 206);
rule.Style = ruleStyle;

wb.Save("cf.xlsx");

اعتبارسنجی داده

Worksheet.Validations یک ValidationCollection برمی‌گرداند. برای ایجاد یک Validation برای محدوده سلول، Add(CellArea) را فراخوانی کنید. ویژگی 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 (یک مجموعه) دسترسی پیدا کنید و برای فعال‌سازی فیلتر بر روی یک ستون خاص، 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 است. برای درج URLهای خارجی، مراجع سلول داخلی یا لینک‌های mailto، Add() را فراخوانی کنید. برای متن قابل مشاهده توسط کاربر، 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 حاشیه‌های چاپ، جهت، اندازه صفحه، ناحیه چاپ، سطرها/ستون‌های عنوان، سرصفحه‌ها، پاورقی‌ها و شکست‌های صفحه را کنترل می‌کند. از enumهای 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 را بخوانید؛ وقتی به شیء خام .NET نیاز دارید، از Cell.Value استفاده کنید.
• مجموعه‌های قواعد قالب‌بندی شرطی را بر روی بزرگ‌ترین بازه‌ای که نیاز دارید ایجاد کنید — قوانین سطری در صفحات بزرگ هزینه‌بر هستند.
• به جای فراخوانی wb.Save() پس از هر نوشتن سلول، یک‌بار در انتها آن را فراخوانی کنید.

مشکلات رایج

FAQ

آیا Aspose.Cells به‌صورت متن باز برای .NET به Microsoft Office نیاز دارد؟

خیر. این کتابخانه کاملاً کد مدیریت‌شده است و هیچ وابستگی به Office، Excel یا تعامل COM ندارد.

کدام فرمت‌های فایل پشتیبانی می‌شوند؟

XLSX (خواندن و نوشتن). CSV، ODS، PDF و XLS باینری در این نسخه پشتیبانی نمی‌شوند.

آیا می‌توانم از این کتابخانه در یک برنامه تجاری استفاده کنم؟

بله. Aspose.Cells FOSS تحت مجوز MIT منتشر شده است که استفاده تجاری بدون محدودیت و بدون حق امتیاز را مجاز می‌داند.

حداقل نسخه .NET چیست؟

.NET 6.0 یا بالاتر.

چگونه می‌توانم رنگ پس‌زمینه را به یک سلول اعمال کنم؟

style.Pattern = FillPattern.Solid و style.ForegroundColor = Color.FromArgb(...) را تنظیم کنید، سپس cell.SetStyle(style) را فراخوانی کنید.

API Reference خلاصه

همچنین ببینید:

• Aspose.Cells for .NET — Enterprise Documentation