Cómo trabajar con enlaces y referencias de Word en .NET
Esta guía muestra cómo insertar hipervínculos, referencias cruzadas a marcadores, campos de valor solicitado y campos de cita en Aspose.Words FOSS para .NET, usando FieldHyperlink, FieldRef, FieldPageRef, FieldCitation, y los demás enlaces y referencias Field subclases en el Aspose.Words.Fields espacio de nombres. Cubre la inserción de un hipervínculo simple, la creación de marcadores y su referencia cruzada, la solicitud de valores durante una actualización de campo y la citación de fuentes bibliográficas.
Guía paso a paso
Paso 1: Instalar el paquete
Aspose.Words FOSS for .NET aún no publica un paquete NuGet; en su lugar, construya la biblioteca desde el código fuente. Clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, luego compile Aspose.Words.sln en configuración Release con el SDK .NET y haga referencia al ensamblado Aspose.Words resultante desde su proyecto. La biblioteca tiene como objetivo .NET Standard 2.0, por lo que se ejecuta en .NET Framework 4.6.2+ y .NET 6/8/10.
Paso 2: Importar las clases requeridas
Agregue una directiva using Aspose.Words; para Document y DocumentBuilder, y una directiva using Aspose.Words.Fields; para FieldHyperlink, FieldRef, FieldPageRef, FieldNoteRef, FieldStyleRef, FieldSet, FieldAsk, FieldFillIn, FieldCitation, FieldBibliography, y las demás clases de campo que cubre esta guía.
Paso 3: Insertar un hipervínculo
Para un hipervínculo sencillo, llame a DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark) – pase isBookmark: false para un objetivo URL o true para enlazar a un marcador en el mismo documento. Recurra a construir un FieldHyperlink directamente cuando se necesiten propiedades que el atajo no expone: Address y SubAddress contienen la URL de destino o la ubicación dentro del documento, ScreenTip define la información sobre el cursor, OpenInNewWindow y IsImageMap son indicadores de visualización, y Target nombra un marco del navegador.
Paso 4: Crear un marcador para referenciar
Llame a DocumentBuilder.StartBookmark(bookmarkName) antes del contenido que el marcador debe cubrir, y a DocumentBuilder.EndBookmark(bookmarkName) después de él, usando el mismo nombre para ambas llamadas. DocumentBuilder.MoveToBookmark(bookmarkName) mueve el cursor a un marcador que ya existe — útil para navegar a una ubicación antes de insertar un campo de referencia cruzada cerca de él.
Paso 5: Insertar una referencia cruzada a ese marcador
FieldRef (el campo REF), FieldPageRef (PAGEREF) y FieldNoteRef (NOTEREF) se resuelven cada uno al contenido de un marcador con nombre mediante su propiedad BookmarkName. Establezca InsertHyperlink para que la referencia sea clicable, y InsertRelativePosition para informar una posición relativa (“arriba” / “abajo”) en lugar del propio texto referenciado. FieldRef también admite opciones de numeración de párrafos — InsertParagraphNumber, InsertParagraphNumberInFullContext, InsertParagraphNumberInRelativeContext, NumberSeparator — y IncludeNoteOrComment. FieldStyleRef (STYLEREF) se resuelve al párrafo más cercano formateado con un StyleName dado en lugar de un marcador, con SearchFromBottom para buscar hacia atrás desde la posición del campo. FieldSet (SET) define un valor de texto marcado — BookmarkName y BookmarkText — que un campo REF en otro lugar puede resolver.
Paso 6: Solicitar un valor durante una actualización
FieldAsk (ASK) y FieldFillIn (FILLIN) solicite un valor de quien actualice el campo: establecer PromptText al texto mostrado al usuario, DefaultResponse para un valor de reserva, y PromptOnceOnMailMerge para limitar la solicitud repetida durante una combinación de correspondencia. FieldAsk además almacena su respuesta en BookmarkName para que otros campos puedan referenciarla. Para actualizaciones de campos sin supervisión, proporcione respuestas de forma programática en lugar de solicitar interactivamente; consulte el guía de campos para la interfaz de devolución de llamada que hace esto.
Paso 7: Referenciar contenido externo o vinculado
FieldDde (DDE) y FieldDdeAuto (DDEAUTO) enlazan a contenido en otra aplicación mediante ProgId, SourceFullName y SourceItem, con InsertAsText, InsertAsHtml, InsertAsPicture, InsertAsRtf, InsertAsUnicode y InsertAsBitmap seleccionando la representación insertada, y AutoUpdate / IsLinked controlando el comportamiento de actualización. FieldLink (LINK) es el equivalente OLE-link, añadiendo FormatUpdateType. FieldImport (IMPORT) y FieldIncludePicture (INCLUDEPICTURE) incorporan un gráfico externo mediante SourceFullName y GraphicFilter. FieldInclude (INCLUDE) y FieldIncludeText (INCLUDETEXT) incorporan contenido de documento externo, con BookmarkName para delimitar el rango incluido y LockFields para evitar que se actualice; FieldIncludeText también admite fuentes XML a través de Encoding, MimeType, NamespaceMappings, XPath y XslTransformation.
Paso 8: Referenciar bloques de construcción y entradas de glosario
FieldAutoText (AUTOTEXT), FieldAutoTextList (AUTOTEXTLIST) y FieldGlossary (GLOSSARY) hacen referencia a una entrada de bloque de construcción con nombre a través de EntryName; FieldAutoTextList añade ListStyle y ScreenTip para su presentación estilo lista.
Paso 9: Insertar campos de cita y bibliografía
FieldCitation (CITATION) y FieldBibliography (BIBLIOGRAPHY) renderiza contenido proveniente de los datos de bibliografía del documento. Establece FieldCitation.SourceTag (o el alternativo AnotherSourceTag) para identificar qué fuente cita, y usa Prefix, Suffix, PageNumber, VolumeNumber, y el Suppress* banderas (SuppressAuthor, SuppressTitle, SuppressYear) para controlar cómo se formatea la cita. FieldBibliography.SourceTag, FilterLanguageId, y FormatLanguageId controlan qué fuentes aparecen en la bibliografía renderizada y en qué idioma. Estos campos solo se renderizan correctamente una vez que coincidan Source existen registros – vea el guía de bibliografía para crear esos.
Problemas comunes y soluciones
El campo REF, PAGEREF o NOTEREF muestra un resultado de error El BookmarkName el objetivo no existe en el documento. Cree el marcador con DocumentBuilder.StartBookmark() / EndBookmark() antes de actualizar el campo.
El campo ASK o FILLIN bloquea una actualización sin supervisión No se ha asignado ninguna devolución de llamada para proporcionar una respuesta de forma programática. Asigne la devolución de llamada de actualización de campo descrita en el guía de campos, o establezca DefaultResponse en el campo para que tenga un valor de respaldo.
El campo CITATION o BIBLIOGRAPHY se muestra vacío El SourceTag no coincide con ningún Source en los datos de bibliografía del documento. Añada el que coincida Source – ver el guía bibliográfica.
El campo DDE, DDEAUTO o LINK no se actualiza Estos campos hacen referencia a una fuente OLE externa que no está disponible fuera del contexto original de Windows/OLE. Trate el resultado almacenado del campo como el último valor conocido en esa situación.
Un hipervínculo insertado con InsertHyperlink carece de una propiedad que necesito DocumentBuilder.InsertHyperlink() es un acceso directo que no expone cada FieldHyperlink propiedad. Construya o recupere el FieldHyperlink directamente para establecer propiedades como ScreenTip or IsImageMap.
Preguntas frecuentes
¿Cuál es la diferencia entre FieldRef y FieldStyleRef?
FieldRef se resuelve al contenido de un marcador con nombre (BookmarkName); FieldStyleRef, en cambio, se resuelve al párrafo más cercano formateado con un StyleName dado, independiente de los marcadores.
¿Cómo inserto un hipervínculo simple sin crear un Campo manualmente?
Llame a DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark).
¿Estas clases de campo de enlace y referencia están en un espacio de nombres separado de los demás campos?
No – FieldHyperlink, FieldRef, FieldCitation, y el resto de las clases cubiertas aquí son subclases ordinarias de Field en el espacio de nombres Aspose.Words.Fields, el mismo espacio de nombres usado para cada otro tipo de campo.
¿Cómo se relacionan los campos de cita con el modelo de datos de la bibliografía?
FieldCitation and FieldBibliography renderizar contenido mediante búsqueda SourceTag contra el Source registros descritos en el guía de bibliografía – estas clases de campo manejan la renderización, mientras que el Source and Contributor clases contienen los datos subyacentes.
¿Cómo creo un marcador antes de referenciarlo?
Llame a DocumentBuilder.StartBookmark(bookmarkName) antes del contenido, y a DocumentBuilder.EndBookmark(bookmarkName) después de él, usando el mismo nombre para ambas llamadas.
