معرفی

Aspose.Cells FOSS for .NET یک کتابخانهٔ خالص کد مدیریت‌شده، دارای مجوز MIT برای خواندن، نوشتن،
و دستکاری کتاب‌کارهای Excel .xlsx بدون هیچ وابستگی به Microsoft Office. نصب شده به عنوان
پکیج Aspose.Cells_FOSS NuGet، این کتابخانه در هر پروژهٔ .NET یکپارچه می‌شود — برنامه‌های کنسولی، وب
APIها، کارگران پس‌زمینه، و توابع بدون سرور.

این پست یک راهنمای گام‌به‌گام ویژگی به ویژگی از API عمومی ارائه می‌دهد، نشان می‌دهد چه چیزهایی ممکن است و چگونه هر قابلیت را از کد C# فراخوانی کنیم.


نمای کلی ویژگی

دوره‌زندگی Workbook و Worksheet

نقطه ورودی برای هر عملیات، کلاس Workbook است. یک مورد را از ابتدا با new Workbook() بسازید، یا یک .xlsx موجود را با new Workbook(filePath) یا new Workbook(stream) بارگذاری کنید. با Workbook.Worksheets به شیت‌ها پیمایش کنید، Worksheet.Name و Worksheet.VisibilityType را تنظیم کنید و با Workbook.Save() ذخیره کنید. برای فایل‌های آسیب‌دیده، یک نمونه LoadOptions را با TryRepairPackage = true و TryRepairXml = true پاس دهید.

using Aspose.Cells_FOSS;

var options = new LoadOptions
{
    TryRepairPackage = true,
    TryRepairXml = true,
};

try
{
    _ = new Workbook("sample.xlsx", options);
}
catch (WorkbookLoadException exception)
{
    Console.WriteLine(exception.Message);
}

داده‌های سلول و فرمول‌ها

مقادیر را به سلول‌ها با Cell.PutValue() بنویسید — بارگذاری‌های بیش از حد string، int، double, decimal، bool و DateTime. مقادیر را از طریق Cell.Value، Cell.StringValue و Cell.Formula بخوانید. فرمول‌های اکسل را با ویژگی Cell.Formula تنظیم کنید؛ رشته فرمول در هنگام ذخیره حفظ می‌شود و یک چرخه بارگذاری مجدد را زنده می‌ماند.

using Aspose.Cells_FOSS;

var workbook = new Workbook();
var sheet = workbook.Worksheets[0];
sheet.Cells["A1"].PutValue("Hello");
sheet.Cells["B1"].PutValue(123);
sheet.Cells["C1"].Formula = "=B1*2";

workbook.Save("hello.xlsx");

var loaded = new Workbook("hello.xlsx");
Console.WriteLine(loaded.Worksheets[0].Cells["C1"].Formula);
Console.WriteLine(loaded.Worksheets[0].Cells["C1"].StringValue);

استایل‌گذاری سلول

از اشیاء Style برای کنترل قلم، پرکردن، حاشیه‌ها، قالب عددی و تراز استفاده کنید. سبک فعلی را با Cell.GetStyle() بازیابی کنید، آن را تغییر دهید، سپس با Cell.SetStyle() اعمال کنید. برای پرکردن پس‌زمینه، Style.Pattern = FillPattern.Solid را تنظیم کنید و یک Color به Style.ForegroundColor اختصاص دهید. از Cells.Merge() برای گسترش محدوده‌های سلول استفاده کنید.

using Aspose.Cells_FOSS;

var workbook = new Workbook();
var cell = workbook.Worksheets[0].Cells["A1"];
cell.PutValue("Styled");

var style = cell.GetStyle();
style.Font.Bold = true;
style.Pattern = FillPattern.Solid;
style.ForegroundColor = Color.FromArgb(255, 241, 196, 15);
cell.SetStyle(style);

Console.WriteLine($"{cell.StringValue} / Bold={cell.GetStyle().Font.Bold}");

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

قواعد قالب‌بندی شرطی را به بازه‌های سلولی از طریق ConditionalFormattingCollection پیوست کنید.
قواعد از FormatConditionType.CellValue، Expression، ColorScale، DataBar و
IconSet پشتیبانی می‌کنند. از OperatorType برای تعیین عملگرهای مقایسه (Between، Equal، GreaterThan و غیره) استفاده کنید، یک Style را به سلول‌های منطبق اختصاص دهید و اولویت و رفتار stop‑if‑true را برای هر قاعده پیکربندی کنید.

using Aspose.Cells_FOSS;

var workbook = new Workbook();
var sheet = workbook.Worksheets[0];

var cfCollection = sheet.ConditionalFormattings[sheet.ConditionalFormattings.Add()];
cfCollection.AddArea(CellArea.CreateCellArea("A1", "A10"));
var rule = cfCollection[cfCollection.AddCondition(
    FormatConditionType.CellValue, OperatorType.Between, "3", "7")];
var style = rule.Style;
style.Pattern = FillPattern.Solid;
style.ForegroundColor = Color.FromArgb(255, 255, 199, 206);
style.Font.Bold = true;
rule.Style = style;

workbook.Save("conditional-formatting.xlsx");

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

با استفاده از Worksheet.Validations، محدودیت‌های ورودی را به سلول‌ها اضافه کنید. انواع اعتبارسنجی پشتیبانی‌شده شامل ValidationType.List، Decimal، Custom و موارد دیگر هستند. اعلان‌های ورودی (InputTitle، InputMessage) و پیام‌های خطا (ErrorTitle، ErrorMessage، ValidationAlertType) را پیکربندی کنید. از CellArea.CreateCellArea() برای تعریف محدوده معتبر استفاده کنید و Validation.AddArea() را برای اعمال یک قانون به محدوده‌های اضافی به کار ببرید.

using Aspose.Cells_FOSS;

var workbook = new Workbook();
var sheet = workbook.Worksheets[0];
sheet.Name = "Validation Sheet";

var listIdx = sheet.Validations.Add(CellArea.CreateCellArea("A1", "A3"));
var listVal = sheet.Validations[listIdx];
listVal.Type = ValidationType.List;
listVal.Formula1 = "\"Open,Closed\"";
listVal.IgnoreBlank = true;
listVal.InCellDropDown = true;
listVal.ShowInput = true;
listVal.InputTitle = "Status";
listVal.InputMessage = "Pick a status";
listVal.ShowError = true;
listVal.ErrorTitle = "Invalid";
listVal.ErrorMessage = "Choose from the list";

workbook.Save("validations-sample.xlsx");

تنظیمات صفحه و گزینه‌های چاپ

پیکربندی طرح چاپ از طریق Worksheet.PageSetup. تنظیم حاشیه‌ها (LeftMarginInch, RightMarginInch, TopMarginInch, BottomMarginInchOrientation، PaperSize، مقیاس، منطقه چاپ، ردیف‌ها و ستون‌های عنوان، سرصفحه‌ها و پاورقی‌ها، و شکست‌های صفحه. تمام تنظیمات پس از یک دور ذخیره‑بارگذاری حفظ می‌شوند.

using Aspose.Cells_FOSS;

var workbook = new Workbook();
var sheet = workbook.Worksheets[0];
sheet.Name = "Print Sheet";
sheet.Cells["A1"].PutValue("Title");

var pageSetup = sheet.PageSetup;
pageSetup.Orientation = PageOrientationType.Landscape;
pageSetup.PaperSize = PaperSizeType.PaperA4;
pageSetup.PrintArea = "$A$1:$C$10";
pageSetup.PrintTitleRows = "$1:$2";
pageSetup.LeftHeader = "Left Header";
pageSetup.CenterFooter = "Center Footer";
pageSetup.PrintGridlines = true;
pageSetup.CenterHorizontally = true;

workbook.Save("page-setup-sample.xlsx");

تنظیمات و حفاظت برگه کاری

نمایش هر برگه را با Worksheet.ShowGridlines، ShowRowColumnHeaders،
ShowZeros، RightToLeft، Zoom و TabColor کنترل کنید. برگه‌ها را با Worksheet.Protect()
محافظت کنید و پرچم‌های دقیق Protection را پیکربندی کنید (Objects، FormatCells، InsertRows،
AutoFilter، SelectLockedCells). ارتفاع ردیف، عرض ستون، ردیف‌ها/ستون‌های مخفی و نواحی ادغام‌شده را از طریق Cells.Rows، Cells.Columns و Cells.Merge() مدیریت کنید.

using Aspose.Cells_FOSS;

var workbook = new Workbook();
var layout = workbook.Worksheets[0];
layout.Name = "Layout";
layout.VisibilityType = VisibilityType.Hidden;
layout.TabColor = Color.FromArgb(255, 34, 68, 102);
layout.ShowGridlines = false;
layout.Zoom = 85;
layout.Protect();
layout.Protection.FormatCells = true;
layout.Protection.InsertRows = true;

layout.Cells["A1"].PutValue("Merged");
layout.Cells.Rows[1].Height = 22.5d;
layout.Cells.Columns[0].Width = 18.25d;
layout.Cells.Merge(0, 0, 2, 2);

workbook.Save("worksheet-settings-sample.xlsx");

هایپرلینک‌ها و بازه‌های نام‌گذاری شده

پیوندهای خارجی، داخلی و mailto: را از طریق HyperlinkCollection.Add() اضافه کنید. Hyperlink.TextToDisplay و Hyperlink.ScreenTip را برای برچسب‌های قابل مشاهده توسط کاربر تنظیم کنید. محدوده‌های نام‌گذاری‌شده را در سطح کتاب‌کار یا برگه با استفاده از DefinedNameCollection.Add() تعریف کنید — محدوده‌های نام‌گذاری‌شده به عنوان نقاط ثابت فرمول و منابع داده نمودار عمل می‌کنند که پس از بارگذاری مجدد فایل حفظ می‌شوند.

using Aspose.Cells_FOSS;

var workbook = new Workbook();
var sheet = workbook.Worksheets[0];

sheet.Cells["A1"].PutValue("Docs");
var link = sheet.Hyperlinks[sheet.Hyperlinks.Add("A1", 1, 1, "https://example.com/docs")];
link.TextToDisplay = "Docs";
link.ScreenTip = "External documentation";

var name = workbook.DefinedNames[workbook.DefinedNames.Add("PrimaryRange", "='Sheet1'!$A$1:$D$5")];
name.Comment = "Primary data range";

workbook.Save("hyperlinks-names.xlsx");
Console.WriteLine("Hyperlinks: " + sheet.Hyperlinks.Count);
Console.WriteLine("Defined names: " + workbook.DefinedNames.Count);

شروع سریع

dotnet add package Aspose.Cells_FOSS
using Aspose.Cells_FOSS;

var workbook = new Workbook();
var sheet = workbook.Worksheets[0];
sheet.Cells["A1"].PutValue("Hello");
sheet.Cells["B1"].PutValue(123);
sheet.Cells["C1"].Formula = "=B1*2";
workbook.Save("output.xlsx");

فرمت‌های پشتیبانی‌شده

قالبپسوندخواندننوشتن
Xlsx.xlsx
Auto(متنوع)

منبع باز و مجوزدهی

Aspose.Cells FOSS برای .NET تحت مجوز MIT منتشر شده و از طریق NuGet به عنوان
Aspose.Cells_FOSS توزیع می‌شود. این برای پروژه‌های منبع باز و تجاری به‌طور یکسان مناسب است.


شروع کار

منابع مرتبط