Clase Utilitare și de Ajutor

Clase utilitare și de ajutor

Acest ghid arată cum să utilizați clasele mici și concentrate de ajutor pe care Aspose.PDF FOSS pentru .NET le furnizează pentru sarcini comune de nivel scăzut: matematică cu numere întregi utilizată de primitivele de securitate, configurarea căutării regex, evaluarea funcțiilor PostScript, descoperirea fonturilor externe, extragerea sub-căilor vectoriale, măsurarea fizică a textului, editări tamponate ale fluxului de conținut, fluxuri mari în memorie și raportarea versiunii bibliotecii. Aceste clase nu sunt puncte de intrare în sine, ci susțin operațiuni de nivel superior pentru documente, texte și randare în întregul API.

Ajutoare pentru matematică cu numere întregi

MathExtensions este un ajutor static mic utilizat intern de primitivele de securitate ale bibliotecii, dar este disponibil pentru utilizare generală ori de câte ori aveți nevoie de o operație modulo care întotdeauna returnează un rezultat nenegativ.

// Unlike the C# % operator, Mod never returns a negative value.
int wrapped = MathExtensions.Mod(-3, 5); // 2

Configurarea căutării regex

RegexManager este o clasă statică care configurează motorul de expresii regulate utilizat de operațiunile de căutare text, cum ar fi TextFragmentAbsorber. Setați MatchTimeout pentru a limita durata de execuție a unui model și activați NonBacktracking pentru a folosi motorul regex fără backtracking în căutările sensibile la performanță.

using var doc = Document.Open(pdfBytes);

// Guard against runaway regex patterns.
RegexManager.MatchTimeout = TimeSpan.FromSeconds(5);
RegexManager.NonBacktracking = true;

var absorber = new TextFragmentAbsorber(@"\d{3}-\d{4}", true);
doc.Pages[1].Accept(absorber);

Evaluarea funcțiilor PostScript

PostScriptEvaluator este o clasă statică care evaluează funcții PDF de tip 4 (PDF32000 §7.10.5) — programe calculator PostScript încorporate într-un PDF, cum ar fi cele utilizate în unele definiții de spațiu de culoare și umbrire.

double[] inputs = { 0.5 };

// Evaluate a PostScript calculator program against the input array.
var outputs = PostScriptEvaluator.Evaluate("{ 2 mul }", inputs);

Căi de căutare pentru fonturi externe

ExternalFontCache gestionează dosarele căutate pentru fonturi externe (neîncorporate) TrueType/OpenType în timpul redării și conversiei. Folosiți Instance pentru a accesa singletonul, GetDefaultFontsFolders pentru a inspecta locațiile de căutare încorporate și SetFontsFolders pentru a le adăuga sau înlocui.

var cache = ExternalFontCache.Instance;
var defaultFolders = cache.GetDefaultFontsFolders();

// reset: false appends to the existing search paths instead of replacing them.
cache.SetFontsFolders(new[] { @"C:\Fonts\Custom" }, reset: false);

Extracția sub-căilor vectoriale

GraphicsAbsorber vizitează o pagină și extrage sub-căile sale vectoriale pictate ca elemente SubPath, fiecare având propria limită Rectangle în spațiul paginii. Acest lucru este util pentru inspectarea sau măsurarea lucrărilor vectoriale fără a parcurge manual fluxul de conținut.

using var doc = Document.Open(pdfBytes);

var absorber = new GraphicsAbsorber();
absorber.Visit(doc.Pages[1]);

Console.WriteLine($"Elements found: {absorber.Elements.Count}");

foreach (var element in absorber.Elements)
{
    if (element is SubPath subPath)
    {
        Rectangle bounds = subPath.Rectangle;
        Console.WriteLine($"Sub-path bounds: [{bounds.LLX}, {bounds.LLY}, {bounds.URX}, {bounds.URY}]");
    }
}

Măsurarea segmentului de text fizic

PhysicalTextSegment este proiecția în spațiul paginii a unui TextSegment absorbit. Accesați-l prin TextSegment.PhysicalSegment pentru a măsura o secvență de caractere sau pentru a citi TextState rezolvat.

using var doc = Document.Open(pdfBytes);

var absorber = new TextFragmentAbsorber();
doc.Pages[1].Accept(absorber);

foreach (TextFragment fragment in absorber.TextFragments)
{
    foreach (TextSegment segment in fragment.Segments)
    {
        PhysicalTextSegment physical = segment.PhysicalSegment;
        var width = physical.MeasureSegment(segment.StartCharIndex, segment.EndCharIndex, true);
        TextState state = physical.TextState;
    }
}

Bufferizarea editărilor fluxului de conținut

ContentsAppender, accesat prin Page.ContentsAppender, bufferează operatorii pentru a prepend sau a append la fluxul de conținut al paginii și îi comite într-un singur pas cu UpdateData.

using var doc = Document.Open(pdfBytes);

Page page = doc.Pages[1];
page.ContentsAppender.AppendToBegin(new GSave());
page.ContentsAppender.AppendToEnd(new GRestore());
page.ContentsAppender.UpdateData();

Fluxuri mari în memorie

OptimizedMemoryStream este un flux în memorie extensibil care poate depăși limita de 2 GB a unui singur tablou din MemoryStream prin stocarea datelor în bucăți de dimensiune fixă. Derivează din Stream, astfel că suportă operațiile obișnuite de citire, scriere și căutare.

using var stream = new OptimizedMemoryStream();

byte[] buffer = System.Text.Encoding.UTF8.GetBytes("large payload");
stream.Write(buffer, 0, buffer.Length);

bool canSeek = stream.CanSeek;
byte[] allBytes = stream.ToArray();

Informații despre versiunea bibliotecii

BuildVersionInfo este o clasă statică care expune numele produsului bibliotecii și numerele de versiune la runtime — utilă pentru diagnosticare și cereri de suport.

Console.WriteLine(BuildVersionInfo.Product);
Console.WriteLine(BuildVersionInfo.AssemblyVersion);
Console.WriteLine(BuildVersionInfo.FileVersion);

Sfaturi și cele mai bune practici

• Setați RegexManager.MatchTimeout înainte de a efectua căutări pe modele neîncredere sau furnizate de utilizator pentru a evita backtracking-ul catastrofic.
• Apelați ExternalFontCache.SetFontsFolders cu reset: true când doriți să înlocuiți complet căile de căutare implicite în loc să le adăugați.
• Preferă OptimizedMemoryStream în loc de MemoryStream atunci când se memorează în buffer documente foarte mari sau date de imagine care pot depăși 2 GB.
• Finalizează întotdeauna un lot de editări ContentsAppender cu UpdateData() — operatorii din buffer nu sunt comiteți în fluxul de conținut până atunci.
• GraphicsAbsorber.Elements poate conține instanțe GraphicElement altele decât SubPath; verifică tipul înainte de a face casting.

Probleme comune

FAQ

De ce MathExtensions.Mod diferă de operatorul % al C#?

MathExtensions.Mod întotdeauna returnează un rest nenegativ, în timp ce operatorul încorporat % poate returna o valoare negativă când dividendul este negativ.

Cum pot împiedica o căutare de text bazată pe regex să ruleze prea mult timp?

Setează RegexManager.MatchTimeout la un TimeSpan înainte de a construi sau rula un TextFragmentAbsorber care folosește un model regex.

Înlocuiește SetFontsFolders sau adaugă la căile de căutare existente?

Depinde de argumentul reset: transmite true pentru a înlocui lista curentă de dosare sau false pentru a adăuga noile dosare la aceasta.

Ce extrage de fapt GraphicsAbsorber?

Extrage sub-căile vectoriale pictate ale unei pagini ca elemente SubPath, fiecare având o limită Rectangle în spațiul paginii, prin GraphicsAbsorber.Visit.

Când ar trebui să folosesc OptimizedMemoryStream în loc de MemoryStream?

Când datele tamponate pot apropia sau depăși 2 GB, deoarece MemoryStream este susținut de un singur array cu această limită strictă.

API Reference Rezumat

Vezi și:

• Metadate și utilitare
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation