Caricamento dei documenti con LoadOptions

Questa guida mostra come controllare il caricamento dei documenti oltre a un semplice percorso file o stream, usando la classe LoadOptions. Document dispone di overload del costruttore che accettano un’istanza LoadOptions — Document(fileName, loadOptions) e Document(stream, loadOptions) — così tutte le impostazioni descritte qui si applicano al momento del caricamento, prima che l’oggetto documento venga restituito al tuo codice.

La classe LoadOptions

LoadOptions trasporta le impostazioni Aspose.Words di cui FOSS ha bisogno durante il caricamento di un documento in un oggetto Document. I suoi costruttori includono un LoadOptions() senza parametri, LoadOptions(password) per aprire direttamente un file protetto da password, e LoadOptions(loadFormat, password, baseUri) per specificare esplicitamente il formato. Oltre a Password e BaseUri (usati per risolvere riferimenti relativi come risorse collegate), LoadOptions espone Encoding per i formati basati su testo, TempFolder per l’elaborazione di documenti di grandi dimensioni, MswVersion per specificare a quale versione di Word si applicano le convenzioni di formato, e UpdateDirtyFields, IgnoreOleData e UseSystemLcid per un controllo più fine sul comportamento di caricamento. LoadOptions.FontSettings ti consente di fornire FontSettings al momento del caricamento invece di configurare i font solo dopo che il documento è stato caricato.

Opzioni di caricamento specifiche per formato

Alcuni formati hanno la propria sottoclasse LoadOptions che espone impostazioni specifiche per quel formato. TxtLoadOptions (per testo semplice) aggiunge AutoNumberingDetection, DetectNumberingWithWhitespaces, DetectHyperlinks, DocumentDirection e LeadingSpacesOptions/TrailingSpacesOptions separati di tipo TxtLeadingSpacesOptions/TxtTrailingSpacesOptions per controllare come gli spazi bianchi iniziali e finali di ogni riga vengono gestiti. MarkdownLoadOptions aggiunge PreserveEmptyLines, ImportUnderlineFormatting e SoftLineBreakCharacter per controllare come le convenzioni di interruzione di riga di Markdown vengono mappate su paragrafi e run del documento. Entrambe le sottoclassi ereditano ogni proprietà generale LoadOptions, quindi una password o un callback di caricamento risorse impostato su un’istanza TxtLoadOptions o MarkdownLoadOptions si comporta allo stesso modo della classe base.

Callback di caricamento delle risorse

LoadOptions.ResourceLoadingCallback accetta un’implementazione di IResourceLoadingCallback, che viene notificata mentre il loader risolve le risorse esterne referenziate dal documento in caricamento. Il callback riceve un ResourceLoadingArgs che descrive il ResourceType della risorsa in caricamento, e restituisce un ResourceLoadingAction per indicare al loader se caricare la risorsa normalmente, saltarla o sostituirla con dati personalizzati. Questo è il punto di estensione per controllare o intercettare la risoluzione delle risorse durante il caricamento, indipendentemente dal formato letto.

Impostazioni di lingua, direzione e recupero

LoadOptions.LanguagePreferences è un oggetto LanguagePreferences il cui DefaultEditingLanguage (un valore enum EditingLanguage) imposta la lingua Aspose.Words che FOSS assume quando un documento non ne specifica una esplicitamente; AddEditingLanguage(language) e AddEditingLanguages(languages) registrano lingue aggiuntive che il documento può utilizzare. DocumentDirection (esposto anche direttamente su TxtLoadOptions) è un enum con i valori LeftToRight, RightToLeft e Auto per controllare la direzione del flusso di testo al caricamento. LoadOptions.RecoveryMode accetta un valore DocumentRecoveryMode, che controlla come il loader risponde quando incontra un documento malformato o parzialmente corrotto.

Callback di avanzamento e avviso

Oltre al caricamento delle risorse, LoadOptions.WarningCallback e LoadOptions.ProgressCallback accettano implementazioni di callback che vengono notificate dei problemi non fatali riscontrati durante il caricamento e dell’avanzamento del caricamento, rispettivamente — utili per rendere visibili i problemi recuperabili al codice chiamante o per segnalare il progresso su documenti di grandi dimensioni senza effettuare polling.

Suggerimenti e migliori pratiche

Passa LoadOptions(password) (oppure imposta LoadOptions.Password) invece di intercettare un’eccezione di caricamento e riprovare — Aspose.Words FOSS ha bisogno della password prima di poter analizzare il documento.
Imposta LanguagePreferences.DefaultEditingLanguage durante il caricamento di documenti il cui metadato di lingua è mancante o inaffidabile, così l’elaborazione a valle dipendente dalla lingua si comporta in modo prevedibile.
Preferisci la classe di opzioni specifica per il formato (TxtLoadOptions, MarkdownLoadOptions) rispetto alla classe base LoadOptions durante il caricamento di tali formati, poiché la sottoclasse specifica espone impostazioni rilevanti per il formato che la classe base non ha.
Implementa IResourceLoadingCallback quando è necessario reindirizzare, memorizzare nella cache o bloccare la risoluzione di risorse esterne durante il caricamento anziché dopo che il documento è già in memoria.
Imposta LoadOptions.RecoveryMode deliberatamente per pipeline che elaborano documenti da fonti non attendibili o di terze parti, anziché fare affidamento sul comportamento di ripristino predefinito.

Problemi comuni

Problema	Causa	Correzione
Il caricamento di un documento protetto da password genera un’eccezione	Nessuna password è stata fornita, oppure è stata fornita dopo che il caricamento era già iniziato	Passa `LoadOptions(password)` (o imposta `Password` su un’istanza `LoadOptions`) al sovraccarico del costruttore `Document` che accetta `LoadOptions`
Gli spazi bianchi iniziali/finali in un file di testo caricato non vengono gestiti come previsto	Il comportamento predefinito di `TxtLeadingSpacesOptions`/`TxtTrailingSpacesOptions` non corrisponde alle convenzioni di spazi bianchi del file sorgente	Imposta `TxtLoadOptions.LeadingSpacesOptions` / `TrailingSpacesOptions` esplicitamente
Le interruzioni di riga Markdown non corrispondono alla struttura di paragrafo prevista	`MarkdownLoadOptions.PreserveEmptyLines` o `SoftLineBreakCharacter` non corrispondono alle convenzioni del Markdown di origine	Regola la proprietà `MarkdownLoadOptions` pertinente prima del caricamento
Il caricamento di risorse esterne non è osservato né controllabile	Nessun `IResourceLoadingCallback` è stato registrato su `LoadOptions.ResourceLoadingCallback`	Implementa `IResourceLoadingCallback` e assegnalo prima del caricamento

FAQ

Come posso caricare un documento protetto da password?

Costruisci LoadOptions con la password — new LoadOptions(password) — o imposta LoadOptions.Password, quindi passalo a new Document(fileName, loadOptions) o new Document(stream, loadOptions).

Ho bisogno di una sottoclasse `LoadOptions` specifica per il formato, o la classe base è sufficiente?

La classe base LoadOptions copre le impostazioni comuni a ogni formato (password, codifica, callback). Usa una sottoclasse specifica per il formato come TxtLoadOptions o MarkdownLoadOptions quando hai bisogno di impostazioni specifiche per quel formato, ad esempio la gestione degli spazi bianchi per i file di testo o le convenzioni di interruzione di riga per Markdown.

Come posso intercettare o reindirizzare le risorse a cui un documento fa riferimento durante il caricamento?

Implementa IResourceLoadingCallback e assegnalo a LoadOptions.ResourceLoadingCallback prima del caricamento. Il callback riceve un ResourceLoadingArgs per risorsa e restituisce un ResourceLoadingAction che decide come procede il loader.

Come posso controllare quale lingua Aspose.Words FOSS assume per un documento caricato?

Imposta LoadOptions.LanguagePreferences.DefaultEditingLanguage su un valore EditingLanguage prima del caricamento; usa AddEditingLanguage/AddEditingLanguages per registrare lingue aggiuntive che il documento può contenere.

Cosa succede se il loader incontra un documento malformato?

Il comportamento è controllato da LoadOptions.RecoveryMode, un valore DocumentRecoveryMode che determina come il loader risponde ai problemi strutturali nel documento sorgente.

API Reference Riepilogo

Classe/Metodo	Descrizione
`LoadOptions`	Oggetto base delle opzioni che controlla come viene caricato un documento
`Document(fileName, loadOptions)` / `Document(stream, loadOptions)`	Sovraccarichi del costruttore che applicano `LoadOptions` durante il caricamento
`TxtLoadOptions`	Opzioni di caricamento specifiche per documenti di testo semplice
`MarkdownLoadOptions`	Opzioni di caricamento specifiche per documenti Markdown
`IResourceLoadingCallback`	Interfaccia di callback per intercettare la risoluzione di risorse esterne durante il caricamento
`ResourceLoadingArgs` / `ResourceLoadingAction`	Dati dell’evento per risorsa e l’azione restituita al loader
`LanguagePreferences`	Configura le lingue di editing predefinite e aggiuntive assunte al caricamento
`DocumentDirection`	Enum che controlla la direzione del flusso di testo (`LeftToRight`, `RightToLeft`, `Auto`)
`DocumentRecoveryMode`	Controlla il comportamento del loader quando un documento è malformato

Vedi anche

Aspose.Words for .NET — Enterprise Documentation

Caricamento dei documenti con LoadOptions