Încărcarea documentelor cu LoadOptions

Încărcarea documentelor cu LoadOptions

Acest ghid arată cum să controlați încărcarea documentelor dincolo de o simplă cale de fișier sau flux, utilizând clasa LoadOptions. Document are suprasarcini de constructor care acceptă o instanță LoadOptions — Document(fileName, loadOptions) și Document(stream, loadOptions) — astfel încât orice setare descrisă aici se aplică în timpul încărcării, înainte ca obiectul document să fie returnat codului dumneavoastră.

Clasa LoadOptions

LoadOptions transportă setările Aspose.Words de care are nevoie FOSS în timpul încărcării unui document într-un obiect Document. Constructorii săi includ un LoadOptions() fără parametri, LoadOptions(password) pentru deschiderea directă a unui fișier protejat prin parolă și LoadOptions(loadFormat, password, baseUri) pentru specificarea explicită a formatului. Dincolo de Password și BaseUri (utilizate pentru rezolvarea referințelor relative, cum ar fi resursele legate), LoadOptions expune Encoding pentru formatele bazate pe text, TempFolder pentru procesarea de documente mari, MswVersion pentru a specifica care convenții de format ale versiunii Word se aplică și UpdateDirtyFields, IgnoreOleData și UseSystemLcid pentru un control mai fin al comportamentului de încărcare. LoadOptions.FontSettings vă permite să furnizați FontSettings în timpul încărcării, în loc să configurați fonturile doar după ce documentul a fost încărcat.

Opțiuni de încărcare specifice formatului

Unele formate au propria subclasă LoadOptions care expune setări specifice acelui format. TxtLoadOptions (pentru text simplu) adaugă AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection și LeadingSpacesOptions/TrailingSpacesOptions separate de tip TxtLeadingSpacesOptions/TxtTrailingSpacesOptions pentru controlul modului în care spațiile albe de la început și sfârșit ale fiecărei linii sunt gestionate. MarkdownLoadOptions adaugă PreserveEmptyLines, ImportUnderlineFormatting și SoftLineBreakCharacter pentru controlul modului în care convențiile de întrerupere a liniei din Markdown se mapează pe paragrafele și rulurile documentului. Ambele subclase moștenesc fiecare proprietate generală LoadOptions, astfel încât o parolă sau un callback de încărcare a resurselor setat pe o instanță TxtLoadOptions sau MarkdownLoadOptions se comportă la fel ca pe clasa de bază.

Callback-uri de încărcare a resurselor

LoadOptions.ResourceLoadingCallback acceptă o implementare a IResourceLoadingCallback, care este notificată pe măsură ce încărcătorul rezolvă resursele externe referențiate de documentul încărcat. Callback-ul primește un ResourceLoadingArgs care descrie ResourceType resursei încărcate și returnează un ResourceLoadingAction pentru a spune încărcătorului dacă să încarce resursa în mod normal, să o ignore sau să înlocuiască cu date personalizate. Acesta este punctul de extensie pentru controlul sau interceptarea rezolvării resurselor în timpul încărcării, independent de formatul citit.

Setări de limbă, direcție și recuperare

LoadOptions.LanguagePreferences este un obiect LanguagePreferences al cărui DefaultEditingLanguage (o valoare enum EditingLanguage) stabilește limba Aspose.Words pe care FOSS o presupune când un document nu specifică una explicit; AddEditingLanguage(language) și AddEditingLanguages(languages) înregistrează limbi suplimentare pe care documentul le poate folosi. DocumentDirection (de asemenea expus direct pe TxtLoadOptions) este un enum cu valori LeftToRight, RightToLeft și Auto pentru controlul direcției fluxului de text la încărcare. LoadOptions.RecoveryMode primește o valoare DocumentRecoveryMode, care controlează modul în care încărcătorul răspunde când întâlnește un document malformat sau parțial corupt.

Callback-uri de progres și avertisment

Dincolo de încărcarea resurselor, LoadOptions.WarningCallback și LoadOptions.ProgressCallback acceptă implementări de callback care sunt notificate despre problemele nefatale întâlnite în timpul încărcării și, respectiv, despre progresul încărcării — utile pentru expunerea problemelor recuperabile codului apelant sau pentru raportarea progresului în documente mari fără interogare periodică.

Sfaturi și bune practici

• Transmite LoadOptions(password) (sau setează LoadOptions.Password) în loc să prinzi o excepție de încărcare și să încerci din nou — Aspose.Words FOSS are nevoie de parolă înainte să poată analiza documentul.
• Setează LanguagePreferences.DefaultEditingLanguage când încarci documente ale căror metadate de limbă lipsesc sau sunt nesigure, astfel încât procesarea ulterioară dependentă de limbă să se comporte predictibil.
• Preferă clasa de opțiuni specifică formatului (TxtLoadOptions, MarkdownLoadOptions) în locul clasei de bază LoadOptions atunci când încarci acele formate, deoarece subclasa specifică expune setări relevante pentru format pe care clasa de bază nu le are.
• Implementează IResourceLoadingCallback când ai nevoie să redirecționezi, să memorezi în cache sau să blochezi rezolvarea resurselor externe în timpul încărcării, în loc de după ce documentul este deja în memorie.
• Setează LoadOptions.RecoveryMode în mod deliberat pentru conductele care procesează documente din surse neîncredere sau terțe, în loc să te bazezi pe comportamentul de recuperare implicit.

Probleme comune

FAQ

Cum pot încărca un document protejat prin parolă?

Construiește LoadOptions cu parola — new LoadOptions(password) — sau setează LoadOptions.Password, apoi transmite-l către new Document(fileName, loadOptions) sau new Document(stream, loadOptions).

Am nevoie de o subclasă LoadOptions specifică formatului, sau este suficientă clasa de bază?

Clasa de bază LoadOptions acoperă setările comune fiecărui format (parolă, codare, callback-uri). Folosiți o subclasă specifică formatului, cum ar fi TxtLoadOptions sau MarkdownLoadOptions, când aveți nevoie de setări specifice acelui format, cum ar fi gestionarea spațiilor albe pentru fișiere text sau convențiile de întrerupere a liniilor pentru Markdown.

Cum pot intercepta sau redirecționa resursele pe care un document le referă în timpul încărcării?

Implementați IResourceLoadingCallback și atribuiți-l lui LoadOptions.ResourceLoadingCallback înainte de încărcare. Callback-ul primește un ResourceLoadingArgs pentru fiecare resursă și returnează un ResourceLoadingAction care decide cum continuă încărcătorul.

Cum pot controla ce limbă Aspose.Words FOSS presupune pentru un document încărcat?

Setați LoadOptions.LanguagePreferences.DefaultEditingLanguage la o valoare EditingLanguage înainte de încărcare; folosiți AddEditingLanguage/AddEditingLanguages pentru a înregistra limbile suplimentare pe care documentul le poate conține.

Ce se întâmplă dacă încărcătorul întâlnește un document malformat?

Comportamentul este controlat de LoadOptions.RecoveryMode, o valoare DocumentRecoveryMode care determină cum răspunde încărcătorul la problemele structurale din documentul sursă.

API Reference Rezumat

Vezi și:

• Aspose.Words for .NET — Enterprise Documentation