کار با بسته‌بندی OOXML

کار با بسته‌بندی OOXML

یک فایل XLSX یک آرشیو ZIP بر پایه Open Packaging Convention (OPC) است. Aspose.Cells FOSS برای .NET لایه بستهٔ زیرین را از طریق IPackageReader، IPackageWriter و گراف شیء PackageModel در دسترس قرار می‌دهد. این‌ها APIهای سطح پایین هستند که برای تشخیص و ابزارسازی طراحی شده‌اند — بیشتر برنامه‌ها فقط از کلاس سطح بالای Workbook استفاده می‌کنند.

مدل بسته

PackageModel محتوای منطقی یک آرشیو XLSX را نشان می‌دهد. این سه مجموعه را در دسترس می‌گذارد: Parts (همهٔ بخش‌های محتوا)، Relationships (ورودی‌های رابطهٔ OPC)، و UnsupportedParts (بخش‌هایی که در فایل وجود دارند اما کتابخانه آن‌ها را پردازش نمی‌کند). هر بخش توسط یک PackagePartDescriptor که شامل PartUri، ContentType و Category است توصیف می‌شود.

using Aspose.Cells_FOSS;

// PackageModel is accessed via PackageLoadContext during custom load flows
// The following illustrates the object structure
// var context = new PackageLoadContext(workbook, packageModel);
// var model = context.Package;
// foreach (var part in model.Parts)
// {
//     Console.WriteLine($"URI={part.PartUri}, Type={part.ContentType}");
// }
// Console.WriteLine("Unsupported parts: " + model.UnsupportedParts.Count);

Note: PackageModel به‌صورت داخلی هنگام بارگذاری یک فایل XLSX پر می‌شود. ایجاد مستقیم بخشی از جریان کار سطح‌بالای استاندارد نیست.

IPackageReader و IPackageWriter

IPackageReader یک متد Read() تک برای خواندن یک بستهٔ OPC تعریف می‌کند. IPackageWriter یک متد Write() تک برای نوشتن یک بسته تعریف می‌کند. این رابط‌ها توسط خواننده/نویسنده داخلی کتابخانه مبتنی بر ZIP پیاده‌سازی می‌شوند و می‌توانند توسط پیاده‌سازی‌های سفارشی برای سناریوهای حافظه‌درون‌خطی یا ذخیره‌سازی ابری فراهم شوند.

// Signature reference — not a complete runnable example
// public interface IPackageReader { void Read(...); }
// public interface IPackageWriter { void Write(...); }

PackageStructureException

PackageStructureException زمانی پرتاب می‌شود که ساختار بسته XLSX به‌طور اساسی نامعتبر باشد — برای مثال، وقتی روابط OPC مورد نیاز گم شده باشند. این استثنا سلسله‌مراتبی کلی استثناها را گسترش می‌دهد و پیامی حاوی توصیف این که کدام قاعده ساختاری نقض شده است، حمل می‌کند.

using Aspose.Cells_FOSS;

var opts = new LoadOptions { TryRepairPackage = true };

try
{
    var wb = new Workbook("bad.xlsx", opts);
}
catch (PackageStructureException ex)
{
    Console.WriteLine("OPC structure error: " + ex.Message);
}
catch (WorkbookLoadException ex)
{
    Console.WriteLine("Load error: " + ex.Message);
}

نکات و بهترین روش‌ها

• از PackageModel.UnsupportedParts برای کشف بخش‌های غیر استاندارد که ممکن است در طی پردازش دورانی به‌صورت ساکن حذف شوند، استفاده کنید.
• در هنگام بارگذاری فایل‌ها از منابع غیرقابل اعتماد، علاوه بر WorkbookLoadException، PackageStructureException را نیز بگیرید.
• رابط‌های IPackageReader/IPackageWriter نقاط توسعه هستند؛ تنها زمانی که به ذخیره‌سازی سفارشی نیاز دارید (مثلاً بارگذاری از یک Blob ابری بدون فایل محلی) آن‌ها را پیاده‌سازی کنید.
• برای اکثر تشخیص‌ها، LoadDiagnostics (قابل دسترسی از طریق Workbook.LoadDiagnostics) کافی است — رفتن به لایه بسته به ندرت لازم است.

مشکلات رایج

FAQ

آیا برای کارهای معمولی با صفحه‌گسترده نیاز به استفاده از IPackageReader/IPackageWriter دارم؟

خیر. این واسط‌ها نقاط گسترشی برای سناریوهای پیشرفته هستند. تمام عملیات خواندن/نوشتن استاندارد مستقیماً از طریق Workbook انجام می‌شوند.

آیا بخش‌های پشتیبانی‌نشده هنگام ذخیره حفظ می‌شوند؟

بخش‌های فهرست‌شده در PackageModel.UnsupportedParts پردازش نمی‌شوند و ممکن است بازنویسی نشوند. اگر نیاز به حفظ کامل در مسیر دورگرد برای بخش‌های غیراستاندارد دارید، از یک مرحله پردازش پس از سطح zip استفاده کنید.

تفاوت بین PackageStructureException و WorkbookLoadException چیست؟

PackageStructureException نشان‌دهنده یک خطای سطح OPC/ZIP است (نوع محتوا گم شده، رابطه خراب). WorkbookLoadException نشان‌دهنده یک خطای تجزیه یا معنایی در سطح بالاتر در محتوای XLSX است.

API Reference خلاصه

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

• Aspose.Cells for .NET — Enterprise Documentation