Cómo trabajar con campos en .NET

Paso 1: Obtener la biblioteca

Clona el repositorio y compila Aspose.Words.sln en configuración Release, luego agrega una referencia de proyecto a Aspose.Words.csproj desde tu propio proyecto .NET, como se describe en el guía de instalación. Agrega using Aspose.Words; and using Aspose.Words.Fields; en la parte superior de cualquier archivo que trabaje con campos.

Paso 2: Insertar un campo y leer su resultado

DocumentBuilder.InsertField() inserta un nuevo campo en el cursor, con sobrecargas que actualizan el resultado del campo de inmediato o lo dejan para una pasada de actualización posterior. Cada campo es una instancia de Field compuesta por tres nodos marcadores — FieldStart, Separator y FieldEnd, expuestos como Field.Start / Field.Separator / Field.End. Field.Type identifica qué FieldType representa, Field.Result y Field.DisplayResult contienen el valor calculado más recientemente, Field.Format contiene cualquier interruptor de formato adjunto al código, y Field.GetFieldCode() devuelve el texto sin procesar del código del campo.

Paso 3: Actualizar campos después de una edición programática

Aspose.Words FOSS no recalcula los campos cuando el documento se carga o guarda. Después de una edición que debería cambiar el resultado de un campo, llame a Range.UpdateFields() para recalcular cada campo en ese rango — use Document.Range.UpdateFields() para todo el documento — o Field.Update() para un solo campo. Range.UnlinkFields() convierte cada campo en el rango a texto estático en una sola llamada, y Range.NormalizeFieldTypes() concilia el código de tipo almacenado de un campo con su código de campo real después de una edición manual.

Paso 4: Configurar el comportamiento de actualización de campos con FieldOptions

Document.FieldOptions (una instancia de FieldOptions) controla cómo se comportan los campos de todo el documento durante una actualización: CurrentUser (una instancia de UserInformation — Name, Initials, Address) proporciona la identidad de la que leen los campos relacionados con el autor y el nombre de usuario, DefaultDocumentAuthor genera los resultados relacionados con el autor, y LegacyNumberFormat / UseInvariantCultureNumberFormat / PreProcessCulture / FieldUpdateCultureSource controlan el formato de números y fechas. Para tuberías no supervisadas, asigne FieldOptions.UserPromptRespondent (un IFieldUserPromptRespondent) para que los campos guiados por indicaciones como ASK y FILLIN no bloqueen esperando entrada interactiva, y asigne un IFieldDatabaseProvider personalizado a FieldOptions.FieldDatabaseProvider para proporcionar las filas del campo DATABASE desde su propia fuente de datos en lugar de una conexión real a base de datos.

Paso 5: Rastrear actualizaciones de campos con una devolución de llamada

Implemente IFieldUpdatingCallback (FieldUpdating y FieldUpdated) y asígnelo a FieldOptions para ejecutar código inmediatamente antes y después de que cada campo se recalcule — útil para auditar exactamente qué campos cambiaron en un trabajo por lotes. Para informar del progreso en un documento grande, implemente IFieldUpdatingProgressCallback (Notify), que recibe un FieldUpdatingProgressArgs que expone TotalFieldsCount, UpdatedFieldsCount y UpdateCompleted.

Paso 6: Convertir o eliminar un campo

Field.Unlink() reemplaza el campo con su último resultado calculado como texto estático ordinario, descartando el código subyacente del campo — úselo cuando quiera que el valor quede incorporado permanentemente en el documento. Field.Remove() elimina los nodos FieldStart, Separator y FieldEnd junto con el código y el resultado del campo, eliminando el campo por completo. Prefiera estos dos métodos en lugar de borrar directamente los nodos marcadores, ya que eliminar manualmente solo una parte de la estructura de un campo puede dejar el árbol del documento inconsistente.