Cómo trabajar con documentos en .NET
Esta guía muestra cómo trabajar con el modelo de objetos Document en Aspose.Words FOSS para .NET: crear un documento en blanco, cargar uno existente de forma segura, recorrer su estructura de sección/cuerpo, combinar documentos y aplicar una restricción de edición. Aspose.Words FOSS para .NET está disponible a través de NuGet o compilando desde el código fuente.
Guía paso a paso
Paso 1: Obtener la biblioteca
Clona el repositorio y compílalo Aspose.Words.sln en configuración Release, luego agrega una referencia de proyecto a Aspose.Words.csproj de tu propio proyecto .NET. Los comandos completos de clonación y compilación están en el Guía de instalación. Una vez referenciado, agrega using Aspose.Words; en la parte superior de cualquier archivo que trabaje con documentos.
Paso 2: Crear o cargar un documento
Llama a new Document() para obtener un documento en blanco, o pasa una ruta de archivo o Stream al constructor Document(fileName) / Document(stream) para abrir uno existente. Una sobrecarga que acepta un argumento LoadOptions te permite proporcionar una contraseña para un archivo cifrado. Antes de cargar un archivo cuyo formato no confíes, llama a FileFormatUtil.DetectFileFormat(fileName) — devuelve un FileFormatInfo que informa el LoadFormat detectado y si el archivo IsEncrypted, HasDigitalSignature o HasMacros, de modo que puedas rechazar la entrada inesperada antes de que Document intente analizarlo.
Paso 3: Crear contenido con DocumentBuilder
DocumentBuilder envuelve un Document con un cursor que mueves a través del árbol mientras insertas contenido. Write(text) y Writeln(text) insertan texto en el cursor, y InsertParagraph() inicia un nuevo párrafo. El formato establecido en las propiedades Font, ParagraphFormat, ListFormat y PageSetup del constructor se aplica a lo que escribas a continuación. Reposiciona el cursor con MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) o MoveToParagraph(paragraphIndex, characterIndex), y lee CurrentNode / CurrentParagraph / CurrentSection para confirmar dónde está posicionado el constructor.
Paso 4: Inspeccionar la sección y la estructura del cuerpo
Un Document expone un SectionCollection a través de Document.Sections (más FirstSection / LastSection). Cada Section tiene exactamente un Body, cuyo contenido principal es accesible mediante Body.Paragraphs (un ParagraphCollection) y Body.Tables. Para leer o buscar texto sin recorrer los nodos manualmente, usa el Range disponible en Document, Section, Paragraph y otros nodos — Range.Text devuelve su texto plano, y Range.Replace(pattern, replacement) realiza una búsqueda y reemplazo limitado a ese rango.
Paso 5: Combinar dos documentos
Para copiar un documento completo, llama a Document.Clone(). Para traer contenido específico de una instancia de Document a otra, llama a ImportNode(srcNode, isImportChildren) en el documento de destino, o llama a Document.AppendDocument(srcDoc, importFormatMode) para agregar cada sección de un documento fuente al final del actual. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) hace lo mismo pero inserta en el cursor del constructor en lugar de al final. En los tres casos, elige deliberadamente el valor de ImportFormatMode — KeepSourceFormatting, UseDestinationStyles o KeepDifferentStyles — ya que decide qué estilos del documento prevalecen donde los dos colisionan.
Paso 6: Aplicar una restricción de edición
Llama a Document.Protect(type, password) con un valor de ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions o AllowOnlyFormFields — para restringir qué ediciones acepta Word para el documento. Unprotect() (con o sin la contraseña correspondiente) elimina la restricción. Esto solo afecta la edición dentro de Word; no cifra el archivo guardado. Para exigir una contraseña solo para abrir el archivo, establece OoxmlSaveOptions.Password al guardar.
Problemas comunes y soluciones
Document(fileName) lanza una excepción para un archivo que se abre sin problemas en Word. El formato del archivo no es compatible con los cargadores de esta edición. Llama a FileFormatUtil.DetectFileFormat(fileName) primero y verifica lo devuelto LoadFormat antes de intentar cargar.
El contenido copiado entre documentos adquiere fuentes o estilos incorrectos. El ImportFormatMode pasado a AppendDocument or InsertDocument no coincide con lo que esperabas. Pasa KeepSourceFormatting or UseDestinationStyles explícitamente en lugar de depender de un valor predeterminado.
Unprotect() parece no tener efecto. O el documento no estaba protegido con una contraseña (llame Unprotect() sin argumentos), o la contraseña suministrada no coincide con la que Protect() se llamó.
Formato aplicado a través de DocumentBuilder no aparece donde se esperaba. Formato a nivel de Builder (Font, ParagraphFormat) solo se aplica al contenido escrito after está configurado. Mueva el cursor y establezca el formato antes de llamar Write/Writeln, no después.
Preguntas frecuentes
¿Cómo creo un documento Word nuevo y vacío?
Llame a new Document(). Envuélvalo con un DocumentBuilder para comenzar a insertar contenido de inmediato.
¿Cuál es la diferencia entre Document.Clone() y ImportNode?
Clone() copia un documento completo en una nueva instancia de Document. ImportNode(srcNode, isImportChildren) lleva un nodo único — y opcionalmente sus hijos — del árbol de un documento a otro, que es lo que se usa para combinar contenido específico en lugar de documentos completos.
¿Cómo puedo comprobar de forma segura el formato de un archivo antes de cargarlo?
Llame a FileFormatUtil.DetectFileFormat(fileName) (o a la sobrecarga Stream) e inspeccione las propiedades LoadFormat, IsEncrypted, HasDigitalSignature y HasMacros del FileFormatInfo devuelto antes de pasar el archivo a Document.
¿Cómo puedo leer solo los párrafos dentro del cuerpo de un documento?
Utilice la colección Body.Paragraphs en el Body de la sección, o Body.GetChildNodes(nodeType, isDeep) para otros tipos de nodo.
¿Document.Protect cifra el archivo guardado?
No — es una restricción de edición que Word aplica cuando se abre el archivo. Para requerir una contraseña al abrir el propio archivo, establezca OoxmlSaveOptions.Password al llamar a Document.Save.
