Praca z pakowaniem OOXML

Praca z pakowaniem OOXML

Plik XLSX jest archiwum Open Packaging Convention (OPC) ZIP. Aspose.Cells FOSS dla .NET udostępnia warstwę pakietu poprzez IPackageReader, IPackageWriter oraz graf obiektów PackageModel. Są to niskopoziomowe API przeznaczone do diagnostyki i narzędzi — większość aplikacji używa tylko klasy wysokiego poziomu Workbook.

Model pakietu

PackageModel reprezentuje logiczną zawartość archiwum XLSX. Udostępnia trzy kolekcje: Parts (wszystkie części zawartości), Relationships (wpisy relacji OPC) oraz UnsupportedParts (części obecne w pliku, których biblioteka nie przetwarza). Każda część jest opisana przez PackagePartDescriptor z PartUri, ContentType i 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 jest wypełniane wewnętrznie podczas ładowania pliku XLSX. Bezpośrednia instancjacja nie jest częścią standardowego wysokopoziomowego przepływu pracy.

IPackageReader i IPackageWriter

IPackageReader definiuje pojedynczą metodę Read() do odczytu pakietu OPC. IPackageWriter definiuje pojedynczą metodę Write() do jego zapisu. Interfejsy te są implementowane przez wewnętrzny czytnik/pisarz biblioteki oparty na ZIP i mogą być dostarczane przez własne implementacje w scenariuszach pamięci podręcznej lub przechowywania w chmurze.

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

PackageStructureException

PackageStructureException jest zgłaszany, gdy struktura pakietu XLSX jest zasadniczo niepoprawna — na przykład, gdy brakuje wymaganych relacji OPC. Rozszerza ogólną hierarchię wyjątków i zawiera komunikat opisujący, które invariant strukturalny został naruszony.

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);
}

Wskazówki i najlepsze praktyki

• Użyj PackageModel.UnsupportedParts, aby wykryć niestandardowe części, które mogą być cicho pomijane podczas pełnego cyklu.
• Przechwytuj PackageStructureException oprócz WorkbookLoadException podczas ładowania plików z niepewnych źródeł.
• Interfejsy IPackageReader/IPackageWriter są punktami rozszerzeń; implementuj je tylko wtedy, gdy potrzebujesz niestandardowego przechowywania (np. ładowanie z chmurowego blobu bez pliku lokalnego).
• Dla większości diagnostyk, LoadDiagnostics (dostępny przez Workbook.LoadDiagnostics) jest wystarczający — przechodzenie do warstwy pakietu jest rzadko konieczne.

Typowe problemy

FAQ

Czy muszę używać IPackageReader/IPackageWriter do normalnej pracy z arkuszami kalkulacyjnymi?

Nie. Te interfejsy są punktami rozszerzeń dla zaawansowanych scenariuszy. Wszystkie standardowe operacje odczytu/zapisu przechodzą bezpośrednio przez Workbook.

Czy nieobsługiwane części są zachowywane przy zapisie?

Części wymienione w PackageModel.UnsupportedParts nie są przetwarzane i mogą nie zostać zapisane ponownie. Jeśli wymagana jest wierność round-trip dla części niestandardowych, użyj etapu post-przetwarzania na poziomie zip.

Jaka jest różnica między PackageStructureException a WorkbookLoadException?

PackageStructureException wskazuje na błąd na poziomie OPC/ZIP (brak typu zawartości, uszkodzony związek). WorkbookLoadException wskazuje na błąd wyższego poziomu parsowania lub semantyczny w treści XLSX.

API Reference Podsumowanie

Zobacz także

• Aspose.Cells for .NET — Enterprise Documentation