Come lavorare con i collegamenti e i riferimenti di Word in .NET
Questa guida mostra come inserire collegamenti ipertestuali, riferimenti incrociati a segnalibri, campi con valore richiesto e campi di citazione in Aspose.Words FOSS per .NET, usando FieldHyperlink, FieldRef, FieldPageRef, FieldCitation, e gli altri collegamenti e riferimenti Field sottoclassi nel Aspose.Words.Fields namespace. Copre l’inserimento di un semplice collegamento ipertestuale, la creazione di segnalibri e il loro riferimento incrociato, la richiesta di valori durante l’aggiornamento di un campo e la citazione delle fonti bibliografiche.
Guida passo passo
Passo 1: Installa il pacchetto
Aspose.Words FOSS for .NET non pubblica ancora un pacchetto NuGet – costruisci invece la libreria dal sorgente. Clona https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, poi compila Aspose.Words.sln in configurazione Release con il SDK .NET e fai riferimento all’assembly Aspose.Words risultante dal tuo progetto. La libreria mira a .NET Standard 2.0, quindi funziona su .NET Framework 4.6.2+ e .NET 6/8/10.
Passo 2: Importa le classi richieste
Aggiungi una direttiva using Aspose.Words; per Document e DocumentBuilder, e una direttiva using Aspose.Words.Fields; per FieldHyperlink, FieldRef, FieldPageRef, FieldNoteRef, FieldStyleRef, FieldSet, FieldAsk, FieldFillIn, FieldCitation, FieldBibliography, e le altre classi di campo coperte da questa guida.
Passo 3: Inserire un collegamento ipertestuale
Per un collegamento ipertestuale semplice, chiama DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark) – passa isBookmark: false per un obiettivo URL o true per collegare a un segnalibro nello stesso documento. Passa alla creazione di un FieldHyperlink direttamente quando sono necessarie proprietà che la scorciatoia non espone: Address e SubAddress contengono l’URL di destinazione o la posizione nel documento, ScreenTip imposta il tooltip al passaggio del mouse, OpenInNewWindow e IsImageMap sono flag di visualizzazione, e Target indica un frame del browser.
Passo 4: Creare un segnalibro di riferimento
Chiama DocumentBuilder.StartBookmark(bookmarkName) prima del contenuto che il segnalibro deve coprire, e DocumentBuilder.EndBookmark(bookmarkName) dopo di esso, usando lo stesso nome per entrambe le chiamate. DocumentBuilder.MoveToBookmark(bookmarkName) sposta il cursore su un segnalibro già esistente – utile per navigare verso una posizione prima di inserire un campo di riferimento incrociato vicino ad esso.
Passo 5: Inserire un riferimento incrociato a quel segnalibro
FieldRef (il campo REF), FieldPageRef (PAGEREF) e FieldNoteRef (NOTEREF) risolvono ciascuno al contenuto di un segnalibro denominato tramite la loro proprietà BookmarkName. Imposta InsertHyperlink per rendere il riferimento cliccabile, e InsertRelativePosition per segnalare una posizione relativa (“sopra” / “sotto”) invece del testo di riferimento stesso. FieldRef supporta inoltre opzioni di numerazione dei paragrafi – InsertParagraphNumber, InsertParagraphNumberInFullContext, InsertParagraphNumberInRelativeContext, NumberSeparator – e IncludeNoteOrComment. FieldStyleRef (STYLEREF) risolve al paragrafo più vicino formattato con un dato StyleName invece di un segnalibro, con SearchFromBottom per cercare all’indietro dalla posizione del campo. FieldSet (SET) definisce un valore di testo segnalibro – BookmarkName e BookmarkText – che un campo REF altrove può risolvere.
Passo 6: Richiedere un valore durante un aggiornamento
FieldAsk (ASK) e FieldFillIn (FILLIN) richiedi un valore a chiunque aggiorni il campo: imposta PromptText al testo mostrato all’utente, DefaultResponse per un valore di fallback, e PromptOnceOnMailMerge per limitare le richieste ripetute durante un’unione di posta. FieldAsk memorizza inoltre la sua risposta in BookmarkName in modo che altri campi possano fare riferimento ad essa. Per aggiornamenti dei campi non supervisionati, fornisci le risposte programmaticamente anziché richiedere interattivamente; vedi il guida dei campi per l’interfaccia di callback che lo esegue.
Passo 7: Riferimento a contenuto esterno o collegato
FieldDde (DDE) e FieldDdeAuto (DDEAUTO) collegano a contenuti in un’altra applicazione tramite ProgId, SourceFullName e SourceItem, con InsertAsText, InsertAsHtml, InsertAsPicture, InsertAsRtf, InsertAsUnicode e InsertAsBitmap che selezionano la rappresentazione inserita, e AutoUpdate / IsLinked che controllano il comportamento di aggiornamento. FieldLink (LINK) è l’equivalente OLE-link, aggiungendo FormatUpdateType. FieldImport (IMPORT) e FieldIncludePicture (INCLUDEPICTURE) inseriscono una grafica esterna tramite SourceFullName e GraphicFilter. FieldInclude (INCLUDE) e FieldIncludeText (INCLUDETEXT) inseriscono contenuto di documento esterno, con BookmarkName per delimitare l’intervallo incluso e LockFields per impedire il suo aggiornamento; FieldIncludeText supporta inoltre fonti XML tramite Encoding, MimeType, NamespaceMappings, XPath e XslTransformation.
Passo 8: Riferimento a blocchi di costruzione e voci di glossario
FieldAutoText (AUTOTEXT), FieldAutoTextList (AUTOTEXTLIST) e FieldGlossary (GLOSSARY) fanno tutti riferimento a una voce di blocco di costruzione nominata tramite EntryName; FieldAutoTextList aggiunge ListStyle e ScreenTip per la sua presentazione in stile elenco.
Passo 9: Inserire campi di citazione e bibliografia
FieldCitation (CITATION) e FieldBibliography (BIBLIOGRAPHY) visualizza il contenuto proveniente dai dati della bibliografia del documento. Imposta FieldCitation.SourceTag (o l’alternativa AnotherSourceTag) per identificare quale fonte cita, e usa Prefix, Suffix, PageNumber, VolumeNumber, e il Suppress* flag (SuppressAuthor, SuppressTitle, SuppressYear) per controllare come è formattata la citazione. FieldBibliography.SourceTag, FilterLanguageId, e FormatLanguageId controllano quali fonti compaiono nella bibliografia visualizzata e in quale lingua. Questi campi vengono visualizzati correttamente solo una volta che la corrispondenza Source i record esistono – vedi il guida bibliografica per crearli.
Problemi comuni e soluzioni
Il campo REF, PAGEREF o NOTEREF mostra un risultato di errore Il BookmarkName la destinazione non esiste nel documento. Crea il segnalibro con DocumentBuilder.StartBookmark() / EndBookmark() prima di aggiornare il campo.
Il campo ASK o FILLIN blocca un aggiornamento non supervisionato Nessuna callback è assegnata per fornire una risposta programmaticamente. Assegna la callback di aggiornamento del campo descritta nella guida dei campi, o imposta DefaultResponse sul campo in modo che abbia un valore di fallback.
Il campo CITATION o BIBLIOGRAPHY viene renderizzato vuoto Il SourceTag non corrisponde a nessun Source nei dati della bibliografia del documento. Aggiungi la corrispondenza Source – vedi il guida bibliografica.
il campo DDE, DDEAUTO o LINK non si aggiorna Questi campi fanno riferimento a una sorgente OLE esterna che non è disponibile al di fuori del contesto originale Windows/OLE. Considera il risultato memorizzato del campo come l’ultimo valore noto in quella situazione.
Un collegamento ipertestuale inserito con InsertHyperlink manca di una proprietà di cui ho bisogno DocumentBuilder.InsertHyperlink() è una scorciatoia che non espone ogni FieldHyperlink proprietà. Costruisci o recupera il FieldHyperlink direttamente per impostare proprietà come ScreenTip or IsImageMap.
Domande frequenti
Qual è la differenza tra FieldRef e FieldStyleRef?
FieldRef restituisce il contenuto di un segnalibro nominato (BookmarkName); FieldStyleRef invece restituisce il paragrafo più vicino formattato con un dato StyleName, indipendente dai segnalibri.
Come inserisco un semplice collegamento ipertestuale senza costruire manualmente un Field?
Chiama DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark).
Queste classi di campo link e reference sono in uno spazio dei nomi separato rispetto agli altri campi?
No – FieldHyperlink, FieldRef, FieldCitation e il resto delle classi trattate qui sono normali sottoclassi Field nello spazio dei nomi Aspose.Words.Fields, lo stesso spazio dei nomi usato per tutti gli altri tipi di campo.
Come si relazionano i campi di citazione al modello dati della bibliografia?
FieldCitation and FieldBibliography renderizza il contenuto cercando SourceTag contro il Source record descritti nel guida alla bibliografia – queste classi di campo gestiscono il rendering, mentre le Source and Contributor classi contengono i dati sottostanti.
Come creo un segnalibro prima di fare riferimento ad esso?
Chiama DocumentBuilder.StartBookmark(bookmarkName) prima del contenuto e DocumentBuilder.EndBookmark(bookmarkName) dopo di esso, usando lo stesso nome per entrambe le chiamate.
