Trabajando con Documentos

Aspose.Words FOSS for .NET representa cada archivo Word como un modelo de objetos en memoria con raíz en la clase Document, con DocumentBuilder que proporciona un API de alto nivel basado en cursor para la autoría de contenido. Esta guía cubre la creación y carga de documentos, la autoría con DocumentBuilder, la estructura de sección/cuerpo, la navegación del árbol de nodos, la combinación de documentos y su protección.

Creación y Carga de Documentos

Cree un documento en blanco con new Document(), o abra un archivo existente pasando una ruta o Stream al constructor Document(fileName) o Document(stream). Las sobrecargas que aceptan un argumento LoadOptions le permiten controlar el comportamiento de carga, como proporcionar una contraseña para un archivo cifrado.

Antes de cargar un archivo de una fuente desconocida o no confiable, FileFormatUtil.DetectFileFormat(fileName) (o la sobrecarga Stream) devuelve un FileFormatInfo que describe el LoadFormat detectado, y si el archivo está IsEncrypted, HasDigitalSignature o HasMacros.

Autoría con DocumentBuilder

DocumentBuilder envuelve un Document y expone un cursor que usted mueve a través del documento mientras inserta contenido. Write(text) y Writeln(text) insertan texto en el cursor; InsertParagraph() inicia un nuevo párrafo. Las propiedades de formato en el constructor — Font, ParagraphFormat, ListFormat, PageSetup — se aplican a lo que se escriba a continuación.

Mueva el cursor con MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) o MoveToParagraph(paragraphIndex, characterIndex). Las propiedades CurrentNode, CurrentParagraph y CurrentSection del constructor informan su posición actual en el árbol.

Estructura del documento: Secciones y cuerpo

Un Document contiene un SectionCollection (Document.Sections, más FirstSection / LastSection); cada Section tiene un Body, una colección opcional de encabezados/pies de página, y su propio PageSetup. Section.AppendContent(sourceSection) y PrependContent(sourceSection) copian contenido entre secciones, y ClearContent() restablece una sección sin eliminarla del documento.

Dentro de un Body, el contenido se expone a través de Body.Paragraphs (un ParagraphCollection) y Body.Tables. Un Range — disponible desde Document, Section, Paragraph y otros nodos — representa un área contigua del árbol; Range.Text lee su texto sin formato y Range.Replace(pattern, replacement) realiza una búsqueda y reemplazo solo en esa zona.

Recorriendo el árbol de nodos con DocumentVisitor

Cada parte de un documento — secciones, párrafos, runs, tablas, campos, formas, comentarios, notas al pie — es un Node en un árbol compuesto con raíz en Document. Para procesar cada nodo de un tipo dado sin recursión manual, subclase el DocumentVisitor abstracto y sobrescriba las devoluciones de llamada Visit*Start / Visit*End que necesite, como VisitParagraphStart(paragraph) o VisitRun(run), luego invoque document.Accept(visitor). Cada devolución de llamada puede devolver un VisitorAction (Continue, SkipThisNode o Stop) para controlar cómo avanza el recorrido.

Clonación, importación y anexado de contenido

Document.Clone() produce una copia profunda de un documento completo. Para mover contenido entre dos instancias diferentes de Document, llame a ImportNode(srcNode, isImportChildren) en el documento de destino para introducir un nodo de un árbol externo, o llame a Document.AppendDocument(srcDoc, importFormatMode) para anexar las secciones de un documento a otro usando un ImportFormatMode elegido — KeepSourceFormatting, UseDestinationStyles o KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) inserta el contenido de un documento fuente en el cursor del constructor en lugar de al final del destino.

Protección de documentos

Document.Protect(type, password) restringe la edición según un valor ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields o NoProtection para eliminar la protección. Unprotect() (con o sin contraseña) lo revierte. Esta es una restricción de edición aplicada por Word, independiente del cifrado de contraseña OOXML que OoxmlSaveOptions.Password aplica al guardar un archivo.

Consejos y buenas prácticas

Prefiere DocumentBuilder para construir contenido nuevo; recurre a la manipulación directa de nodos (AppendChild, InsertAfter, Clone) cuando necesites un control fino sobre un árbol existente.
Llama a FileFormatUtil.DetectFileFormat antes de cargar un archivo de una fuente no fiable o suministrada por el usuario para que puedas comprobar LoadFormat y rechazar temprano la entrada no compatible o cifrada.
Al combinar documentos con AppendDocument o InsertDocument, elige deliberadamente el ImportFormatMode — KeepSourceFormatting conserva el aspecto del origen, UseDestinationStyles coincide con el conjunto de estilos del documento de destino.
Utiliza una subclase de DocumentVisitor en lugar de recorrer manualmente el árbol de forma recursiva cuando necesites procesar cada instancia de un tipo de nodo de manera consistente.
Document.Protect es una restricción de edición, no un cifrado — combínalo con OoxmlSaveOptions.Password si el propio archivo guardado debe requerir una contraseña para abrirse.

Problemas comunes

Problema	Causa	Solución
`Document(fileName)` lanza una excepción para un archivo que se abre sin problemas en Word	El formato del archivo no es uno que esta edición admita para cargar	Llame a `FileFormatUtil.DetectFileFormat` primero y verifique el `LoadFormat` devuelto antes de cargar
El contenido añadido adopta fuentes o estilos incorrectos	Desajuste de `ImportFormatMode` entre los conjuntos de estilos de origen y destino	Pase `KeepSourceFormatting` o `UseDestinationStyles` explícitamente en lugar de depender de un valor predeterminado
El recorrido de `DocumentVisitor` se detiene temprano o omite contenido	Una anulación de `VisitStart` / `VisitEnd` devuelve `SkipThisNode` o `Stop` de manera no intencionada	Devuelva `VisitorAction.Continue` en cada anulación a menos que específicamente pretenda omitir o detener
`Unprotect()` no tiene efecto	El documento no estaba protegido con una contraseña, o se proporcionó una contraseña incorrecta	Llame a `Unprotect()` sin argumentos si `Protect` se llamó sin una contraseña, de lo contrario pase la contraseña coincidente

FAQ

¿Cuál es la diferencia entre `Document.Clone()` y `ImportNode`?

Clone() copia un documento completo en una nueva instancia de Document. ImportNode(srcNode, isImportChildren) trae un nodo único (y opcionalmente sus hijos) del árbol de un documento a otro, lo que se utiliza cuando se combina contenido específico en lugar de documentos completos.

¿Qué formatos de archivo puede cargar `Document(fileName)`?

Document(fileName) carga DOCX, DOCM, DOTX, DOTM, Flat OPC (más sus variantes con macros y plantillas), Markdown y texto plano. Los formatos de procesamiento de texto y web más antiguos están excluidos de los cargadores de esta edición.

¿Cómo encuentro dónde está posicionado actualmente un `DocumentBuilder`?

Lea CurrentNode, CurrentParagraph o CurrentSection en la instancia del constructor.

¿`Document.Protect` cifra el archivo guardado?

No — es una restricción de edición aplicada por Word cuando se abre el archivo. Para requerir una contraseña solo para abrir el archivo, configure OoxmlSaveOptions.Password al guardar.

¿Cómo leo solo los párrafos en el cuerpo del documento?

Utilice la colección Body.Paragraphs, o Body.GetChildNodes(nodeType, isDeep) para otros tipos de nodos.

Resumen de API Reference

Clase/Método	Descripción
`Document`	Raíz del modelo de objeto de documento; los constructores cargan desde un archivo o flujo, o crean un documento en blanco.
`Document.Save`	Escribe el documento a un archivo, flujo, o respuesta HTTP en un formato elegido.
`Document.Clone()`	Produce una copia profunda de todo el documento.
`Document.Protect(type, password)` / `Unprotect()`	Aplica o elimina una restricción de edición.
`Document.AppendDocument(srcDoc, importFormatMode)`	Añade las secciones de otro documento a este.
`DocumentBuilder`	Basado en cursor API para escribir texto e insertar contenido en un documento.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	Inserta el contenido de un documento fuente en el cursor.
`Section` / `SectionCollection`	Una sola sección de un documento y la colección de todas las secciones.
`Body`	Contenedor del texto principal (párrafos y tablas) de una sección.
`Range`	Una zona contigua del árbol del documento; soporta `Text` y `Replace`.
`DocumentVisitor`	Clase base abstracta para recorrer cada nodo del árbol del documento.
`ProtectionType`	Enumeración de restricciones de edición a nivel de documento.
`FileFormatUtil.DetectFileFormat`	Detecta el formato de un archivo o flujo antes de cargarlo.

Ver también

Aspose.Words for .NET — Enterprise Documentation

Trabajando con Documentos