Trabajando con campos
Visión general
Un campo de Word – DATE, IF, DATABASE, REF, y docenas de otros – está representado en Aspose.Words FOSS para .NET por la Field clase y sus subclases, todas en la Aspose.Words.Fields espacio de nombres. Esta página cubre el motor central de campos: el Field modelo de objetos en sí, cómo se recopilan y actualizan los campos, y las interfaces de devolución de llamada que le permiten integrar datos y comportamientos personalizados durante una actualización de campo. Las familias de campos específicas – hipervínculos y referencias cruzadas, campos de fecha/hora, campos de combinación de correspondencia, campos de índice y de tabla de contenido – cada una tiene su propia página dedicada de la guía del desarrollador.
El Modelo de Objeto de Campo
Cada campo en un documento es una instancia de Field compuesta por tres nodos marcador – FieldStart, Separator y FieldEnd – expuestos como las propiedades Field.Start, Field.Separator y Field.End. Field.Type identifica cuál FieldType representa el campo, Field.Result y Field.DisplayResult exponen el valor calculado más recientemente, y Field.Format contiene cualquier interruptor (como cadenas de formato numérico o de fecha/hora) adjunto al código del campo. Field.IsLocked y Field.IsDirty informan el estado bloqueado y obsoleto del campo. Llame a Field.GetFieldCode() para leer el texto bruto del código del campo, a Field.Update() para recalcular el resultado, a Field.Unlink() para reemplazar el campo con texto estático, y a Field.Remove() para eliminarlo por completo.
Accediendo y Actualizando Campos en un Documento
Document.Range.Fields devuelve un FieldCollection – los campos contenidos en ese rango, con Count, Remove(), RemoveAt() y Clear() para eliminación masiva. Range.UpdateFields() recalcula cada campo en el rango, Range.UnlinkFields() convierte cada campo en el rango a texto estático, y Range.NormalizeFieldTypes() reconcilia el código de tipo almacenado de un campo con su código de campo real después de ediciones manuales. DocumentBuilder.InsertField() inserta un nuevo campo en el cursor, con sobrecargas que o bien actualizan el resultado del nuevo campo inmediatamente o lo dejan para una pasada Range.UpdateFields() posterior.
Opciones de Actualización de Campos y Cultura
Document.FieldOptions es una instancia FieldOptions que gobierna cómo se comportan los campos de todo el documento cuando se actualizan: CurrentUser suministra el UserInformation usado por los campos de identidad, DefaultDocumentAuthor genera resultados relacionados con el autor, LegacyNumberFormat y UseInvariantCultureNumberFormat controlan el formato de números, y PreProcessCulture y FieldUpdateCultureSource (emparejados con la devolución de llamada IFieldUpdateCultureProvider) determinan qué cultura rige el formato de fechas y números durante una actualización. TemplateName, FileName y BuiltInTemplatesPaths suministran valores que los campos conscientes de plantillas y nombres de archivo leen de vuelta.
Seguimiento y personalización de actualizaciones de campos
Implemente IFieldUpdatingCallback (FieldUpdating y FieldUpdated) en FieldOptions para ejecutar código inmediatamente antes y después de que cada campo se recalcula – útil para auditar qué campos cambiaron en un trabajo por lotes. Implemente IFieldUpdatingProgressCallback (Notify) para rastrear el progreso general a lo largo de un documento grande; recibe un FieldUpdatingProgressArgs con TotalFieldsCount, UpdatedFieldsCount y UpdateCompleted. Para cambiar cómo se representa como texto el resultado numérico o general de un campo, implemente IFieldResultFormatter (Format(value, format) y FormatNumeric(value, format)) y asígnelo a FieldOptions.ResultFormatter.
Proporcionar datos externos a los campos
El campo DATABASE lee sus filas a través de IFieldDatabaseProvider.GetQueryResult(), que devuelve un FieldDatabaseDataTable (ColumnNames, Rows) construido a partir de instancias FieldDatabaseDataRow (Values) – asigne su implementación a FieldOptions.FieldDatabaseProvider. Los campos de comparación como IF evalúan su condición mediante IComparisonExpressionEvaluator.Evaluate(), que recibe un ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) y devuelve un ComparisonEvaluationResult (Result, ErrorMessage); asigne un evaluador personalizado a FieldOptions.ComparisonExpressionEvaluator para sobrescribir la lógica de comparación predeterminada. Los campos que normalmente solicitan al usuario una entrada durante una actualización — como ASK y FILLIN — llaman a IFieldUserPromptRespondent.Respond() cuando uno se asigna a FieldOptions.UserPromptRespondent, de modo que una actualización desatendida no se bloquee esperando entrada interactiva.
Identidad de usuario y documento para los campos
UserInformation (Name, Initials, Address y el estático UserInformation.DefaultUser) suministra la identidad de la que leen los campos relacionados con el autor y el nombre de usuario. Asigne una instancia a Document.FieldOptions.CurrentUser antes de actualizar los campos que dependen del autor del documento o de la identidad del usuario.
Consejos y buenas prácticas
- Aspose.Words FOSS no recalcula los campos automáticamente al cargar o guardar como lo hace Word – llame a
Range.UpdateFields()(oField.Update()para un solo campo) explícitamente después de cualquier edición programática que deba reflejarse en los resultados del campo. FieldStart,SeparatoryFieldEndson nodos reales en el árbol del documento; elimine un campo a través deField.Remove()oField.Unlink()en lugar de borrar directamente los nodos marcador, o la estructura del campo puede quedar inconsistente.- Los campos cuyo resultado depende del diseño de página –
PAGE,NUMPAGESy las entradas de número de página del TOC – se evalúan a un marcador0, porque esta edición no incluye el motor de diseño/renderizado de página. - Registre
IFieldUpdatingCallbackantes de ejecutarRange.UpdateFields()sobre un documento grande o desconocido si necesita registrar o auditar exactamente qué campos cambiaron. - Configure
FieldOptions.UserPromptRespondent(o proporcione valoresDefaultResponseen las clases de campo impulsadas por indicaciones individuales) antes de actualizar un documento en una canalización sin supervisión, de modo que los camposASK/FILLINno se queden bloqueados esperando entrada interactiva.
Problemas comunes
| Problema | Causa | Corrección |
|---|---|---|
| El resultado del campo está desactualizado después de editar el documento | Aspose.Words FOSS no actualiza automáticamente los campos al cargar o guardar | Llame a Range.UpdateFields() o Field.Update() explícitamente |
Los números de página de PAGE, NUMPAGES o del índice muestran 0 | El diseño/renderizado de página no forma parte de esta edición | Comportamiento esperado – use la versión comercial Aspose.Words para .NET si necesitas números de página calculados |
DATABASE campo no produce filas | No se asigna IFieldDatabaseProvider a FieldOptions.FieldDatabaseProvider | Implementa IFieldDatabaseProvider y asígnalo antes de llamar a Range.UpdateFields() |
| La actualización por lotes del campo parece colgarse | Un campo impulsado por solicitud (ASK, FILLIN) no tiene IFieldUserPromptRespondent asignado | Asigne FieldOptions.UserPromptRespondent, o establezca DefaultResponse en la instancia del campo |
FAQ
¿Aspose.Words FOSS evalúa cada tipo de campo de Word?
El modelo de objeto Field representa cada valor FieldType y actualiza la mayoría de ellos, pero los campos cuyo resultado depende del diseño de página – como PAGE y NUMPAGES – se evalúan a un marcador de posición 0 porque esta edición no incluye el motor de diseño/renderizado.
¿Cómo vuelvo a evaluar los campos después de editar un documento programáticamente?
Llame a Range.UpdateFields() en el rango que cubre el contenido editado, o Document.Range.UpdateFields() para actualizar cada campo en el documento.
¿Puedo convertir un campo a texto plano y estático?
Sí – Field.Unlink() reemplaza el campo con su resultado calculado más reciente como texto ordinario, eliminando el código subyacente del campo.
¿Cómo elimino un campo completamente, incluido su resultado?
Llame a Field.Remove(). Elimina los nodos FieldStart, Separator y FieldEnd junto con el código y el contenido del resultado del campo.
¿Cómo suministro datos personalizados al campo DATABASE?
Implemente IFieldDatabaseProvider y asígnele a Document.FieldOptions.FieldDatabaseProvider. Su implementación de GetQueryResult() devuelve un FieldDatabaseDataTable construido a partir de instancias de FieldDatabaseDataRow.
API Reference Resumen
| Clase / Interfaz | Descripción |
|---|---|
Field | Clase base para un campo de Word; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | Los campos en un rango, a través de Range.Fields; Count, Remove(), Clear() |
FieldType | Enum que identifica qué campo de Word representa una instancia de Field |
FieldOptions | Configuración de actualización de campos en todo el documento, a través de Document.FieldOptions |
IFieldUpdatingCallback | Ganchos FieldUpdating / FieldUpdated alrededor de cada actualización de campo |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | Informes de progreso durante una actualización masiva de campos |
IFieldResultFormatter | Formato personalizado del resultado calculado de un campo |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | Fuente de datos externa para el campo DATABASE |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | Evaluación personalizada de expresiones de campo de estilo comparativo |
IFieldUserPromptRespondent | Proporciona respuestas para campos guiados por indicaciones en actualizaciones no supervisadas |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | Selección de cultura durante la actualización de campos |
UserInformation | Identidad del autor/usuario (Name, Initials, Address) leída por los campos de identidad |