Lavorare con i Documenti

Aspose.Words FOSS per .NET rappresenta ogni file Word come un modello di oggetti in memoria radicato nella classe Document, con DocumentBuilder che fornisce un API ad alto livello basato su cursore per la creazione di contenuti. Questa guida copre la creazione e il caricamento dei documenti, la scrittura con DocumentBuilder, la struttura sezione/corpo, l’attraversamento dell’albero dei nodi, la combinazione dei documenti e la loro protezione.

Creazione e Caricamento dei Documenti

Crea un documento vuoto con new Document(), oppure apri un file esistente passando un percorso o Stream al costruttore Document(fileName) o Document(stream). Le sovraccariche che accettano un argomento LoadOptions ti permettono di controllare il comportamento di caricamento, ad esempio fornendo una password per un file crittografato.

Prima di caricare un file da una fonte sconosciuta o non affidabile, FileFormatUtil.DetectFileFormat(fileName) (o la sovraccarica Stream) restituisce un FileFormatInfo che descrive il LoadFormat rilevato e se il file è IsEncrypted, HasDigitalSignature o HasMacros.

Scrittura con DocumentBuilder

DocumentBuilder avvolge un Document e espone un cursore che puoi spostare attraverso il documento mentre inserisci contenuti. Write(text) e Writeln(text) inseriscono testo al cursore; InsertParagraph() avvia un nuovo paragrafo. Le proprietà di formattazione sul builder — Font, ParagraphFormat, ListFormat, PageSetup — si applicano a tutto ciò che viene scritto successivamente.

Sposta il cursore con MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) o MoveToParagraph(paragraphIndex, characterIndex). Le proprietà CurrentNode, CurrentParagraph e CurrentSection del builder segnalano la sua posizione corrente nell’albero.

Struttura del documento: Sezioni e Corpo

Un Document contiene un SectionCollection (Document.Sections, più FirstSection / LastSection); ogni Section ha un Body, una collezione opzionale di intestazioni/piè di pagina, e il proprio PageSetup. Section.AppendContent(sourceSection) e PrependContent(sourceSection) copiano il contenuto tra le sezioni, e ClearContent() reimposta una sezione senza rimuoverla dal documento.

All’interno di un Body, il contenuto è esposto tramite Body.Paragraphs (un ParagraphCollection) e Body.Tables. Un Range — disponibile da Document, Section, Paragraph e altri nodi — rappresenta un’area contigua dell’albero; Range.Text legge il suo testo semplice e Range.Replace(pattern, replacement) esegue una ricerca e sostituzione solo su quell’area.

Percorrere l’albero dei nodi con DocumentVisitor

Ogni parte di un documento — sezioni, paragrafi, run, tabelle, campi, forme, commenti, note a piè di pagina — è un Node in un albero composito radicato in Document. Per elaborare ogni nodo di un determinato tipo senza ricorsione manuale, crea una sottoclasse dell’astratto DocumentVisitor e sovrascrivi i callback Visit*Start/Visit*End di cui hai bisogno, come VisitParagraphStart(paragraph) o VisitRun(run), quindi chiama document.Accept(visitor). Ogni callback può restituire un VisitorAction (Continue, SkipThisNode o Stop) per controllare il modo in cui avviene il traversal.

Clonazione, importazione e aggiunta di contenuti

Document.Clone() produce una copia profonda di un intero documento. Per spostare contenuti tra due diverse istanze di Document, chiama ImportNode(srcNode, isImportChildren) sul documento di destinazione per importare un nodo da un albero esterno, oppure chiama Document.AppendDocument(srcDoc, importFormatMode) per aggiungere le sezioni di un documento a un altro usando un ImportFormatMode scelto — KeepSourceFormatting, UseDestinationStyles o KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) inserisce il contenuto del documento sorgente al cursore del builder invece che alla fine della destinazione.

Proteggere i documenti

Document.Protect(type, password) limita la modifica in base a un valore ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields o NoProtection per rimuovere la protezione. Unprotect() (con o senza password) la inverte. Questa è una restrizione di modifica imposta da Word, separata dalla crittografia con password OOXML che OoxmlSaveOptions.Password applica durante il salvataggio di un file.

Suggerimenti e migliori pratiche

Preferisci DocumentBuilder per costruire nuovo contenuto; passa a una manipolazione diretta dei nodi (AppendChild, InsertAfter, Clone) quando hai bisogno di un controllo fine su un albero esistente.
Chiama FileFormatUtil.DetectFileFormat prima di caricare un file da una fonte non attendibile o fornita dall’utente, così puoi verificare LoadFormat e rifiutare in anticipo input non supportati o crittografati.
Quando combini documenti con AppendDocument o InsertDocument, scegli deliberatamente il ImportFormatMode — KeepSourceFormatting conserva l’aspetto della sorgente, UseDestinationStyles corrisponde al set di stili del documento di destinazione.
Usa una sottoclasse DocumentVisitor invece di un’iterazione ricorsiva manuale dell’albero quando devi elaborare ogni istanza di un tipo di nodo in modo coerente.
Document.Protect è una restrizione di modifica, non una crittografia — abbinalo a OoxmlSaveOptions.Password se il file salvato deve richiedere una password per essere aperto.

Problemi comuni

Problema	Causa	Correzione
`Document(fileName)` lancia un’eccezione per un file che si apre correttamente in Word	Il formato del file non è supportato da questa edizione per il caricamento	Chiama prima `FileFormatUtil.DetectFileFormat` e controlla il `LoadFormat` restituito prima di caricare
Il contenuto aggiunto prende i font o gli stili sbagliati	`ImportFormatMode` discrepanza tra i set di stili di origine e destinazione	Passa `KeepSourceFormatting` o `UseDestinationStyles` esplicitamente invece di fare affidamento su un valore predefinito
Il traversal `DocumentVisitor` si interrompe in anticipo o salta contenuti	Una sovrascrittura `VisitStart` / `VisitEnd` restituisce `SkipThisNode` o `Stop` involontariamente	Restituisci `VisitorAction.Continue` da ogni sovrascrittura a meno che tu non intenda specificamente saltare o interrompere
`Unprotect()` non ha effetto	Il documento non era protetto da una password, oppure è stata fornita una password errata	Chiama `Unprotect()` senza argomenti se `Protect` è stato chiamato senza password, altrimenti passa la password corrispondente

FAQ

Qual è la differenza tra `Document.Clone()` e `ImportNode`?

Clone() copia l’intero documento in una nuova istanza di Document. ImportNode(srcNode, isImportChildren) trasferisce un singolo nodo (e opzionalmente i suoi figli) dall’albero di un documento a un altro, ed è ciò che si utilizza quando si combinano contenuti specifici anziché documenti interi.

Quali formati di file può caricare `Document(fileName)`?

Document(fileName) carica DOCX, DOCM, DOTX, DOTM, Flat OPC (oltre alle sue varianti con macro e template), Markdown e testo semplice. I formati di elaborazione testi e web più vecchi sono esclusi dai caricatori di questa edizione.

Come posso scoprire dove è attualmente posizionato un `DocumentBuilder`?

Leggi CurrentNode, CurrentParagraph o CurrentSection sull’istanza del builder.

Il `Document.Protect` cifra il file salvato?

No — è una restrizione di modifica applicata da Word quando il file viene aperto. Per richiedere una password solo per aprire il file, imposta OoxmlSaveOptions.Password durante il salvataggio.

Come leggo solo i paragrafi nel corpo di un documento?

Usa la collezione Body.Paragraphs, oppure Body.GetChildNodes(nodeType, isDeep) per altri tipi di nodo.

API Reference Riepilogo

Classe/Metodo	Descrizione
`Document`	Radice del modello a oggetti del documento; i costruttori caricano da un file o da uno stream, o creano un documento vuoto.
`Document.Save`	Scrive il documento su un file, stream o risposta HTTP in un formato scelto.
`Document.Clone()`	Produce una copia profonda dell’intero documento.
`Document.Protect(type, password)` / `Unprotect()`	Applica o rimuove una restrizione di modifica.
`Document.AppendDocument(srcDoc, importFormatMode)`	Aggiunge le sezioni di un altro documento a questo.
`DocumentBuilder`	Funzione API basata sul cursore per scrivere testo e inserire contenuti in un documento.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	Inserisce il contenuto di un documento sorgente al cursore.
`Section` / `SectionCollection`	Una singola sezione di un documento e la raccolta di tutte le sezioni.
`Body`	Contenitore per il testo principale (paragrafi e tabelle) di una sezione.
`Range`	Un’area contigua dell’albero del documento; supporta `Text` e `Replace`.
`DocumentVisitor`	Classe base astratta per attraversare ogni nodo dell’albero del documento.
`ProtectionType`	Enum delle restrizioni di modifica a livello di documento.
`FileFormatUtil.DetectFileFormat`	Rileva il formato di un file o di uno stream prima di caricarlo.

Vedi anche

Aspose.Words for .NET — Enterprise Documentation

Lavorare con i Documenti