Como trabalhar com links e referências do Word em .NET
Este guia mostra como inserir hiperligações, referências cruzadas a marcadores, campos de valor solicitado e campos de citação em Aspose.Words FOSS para .NET, usando FieldHyperlink, FieldRef, FieldPageRef, FieldCitation, e o outro link e referência Field subclasses no Aspose.Words.Fields namespace. Ele cobre a inserção de um hyperlink simples, a criação de marcadores e a referência cruzada deles, a solicitação de valores durante uma atualização de campo e a citação de fontes bibliográficas.
Guia passo a passo
Etapa 1: Instalar o pacote
Aspose.Words FOSS para .NET ainda não publica um pacote NuGet – compile a biblioteca a partir do código-fonte em vez disso. Clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, então compile Aspose.Words.sln na configuração Release com o SDK .NET e referencie o assembly Aspose.Words resultante no seu projeto. A biblioteca tem como alvo o .NET Standard 2.0, portanto funciona no .NET Framework 4.6.2+ e no .NET 6/8/10.
Etapa 2: Importar classes necessárias
Adicione uma diretiva using Aspose.Words; para Document e DocumentBuilder, e uma diretiva using Aspose.Words.Fields; para FieldHyperlink, FieldRef, FieldPageRef, FieldNoteRef, FieldStyleRef, FieldSet, FieldAsk, FieldFillIn, FieldCitation, FieldBibliography, e as demais classes de campo que este guia aborda.
Etapa 3: Inserir um hiperlink
Para um hiperlink simples, chame DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark) — passe isBookmark: false para um destino de URL ou true para vincular a um marcador no mesmo documento. Recorra à construção de um FieldHyperlink diretamente quando propriedades que o atalho não expõe são necessárias: Address e SubAddress contêm a URL de destino ou a localização no documento, ScreenTip define a dica de ferramenta ao passar o mouse, OpenInNewWindow e IsImageMap são flags de exibição, e Target nomeia um quadro de navegador.
Etapa 4: Criar um marcador para referência
Chame DocumentBuilder.StartBookmark(bookmarkName) antes do conteúdo que o marcador deve abranger, e DocumentBuilder.EndBookmark(bookmarkName) depois dele, usando o mesmo nome para ambas as chamadas. DocumentBuilder.MoveToBookmark(bookmarkName) move o cursor para um marcador que já existe — útil para navegar até um local antes de inserir um campo de referência cruzada próximo a ele.
Etapa 5: Inserir uma referência cruzada para esse marcador
FieldRef (o campo REF), FieldPageRef (PAGEREF) e FieldNoteRef (NOTEREF) cada um resolve para o conteúdo em um marcador nomeado via sua propriedade BookmarkName. Defina InsertHyperlink para tornar a referência clicável e InsertRelativePosition para relatar uma posição relativa (“acima” / “abaixo”) em vez do próprio texto referenciado. FieldRef também oferece opções de numeração de parágrafos — InsertParagraphNumber, InsertParagraphNumberInFullContext, InsertParagraphNumberInRelativeContext, NumberSeparator — e IncludeNoteOrComment. FieldStyleRef (STYLEREF) resolve para o parágrafo mais próximo formatado com um determinado StyleName em vez de um marcador, com SearchFromBottom para buscar retroativamente a partir da posição do campo. FieldSet (SET) define um valor de texto marcado — BookmarkName e BookmarkText — que um campo REF em outro lugar pode resolver.
Etapa 6: Solicitar um valor durante uma atualização
FieldAsk (ASK) e FieldFillIn (FILLIN) solicita um valor de quem atualizar o campo: set PromptText para o texto exibido ao usuário, DefaultResponse para um valor de reserva, e PromptOnceOnMailMerge para limitar solicitações repetidas durante uma mesclagem de correspondência. FieldAsk também armazena sua resposta em BookmarkName para que outros campos possam referenciá-la. Para atualizações de campo sem intervenção, forneça respostas programaticamente em vez de solicitar interativamente; veja o guia de campos para a interface de retorno de chamada que faz isso.
Etapa 7: Referenciar Conteúdo Externo ou Vinculado
FieldDde (DDE) e FieldDdeAuto (DDEAUTO) vinculam a conteúdo em outro aplicativo via ProgId, SourceFullName e SourceItem, com InsertAsText, InsertAsHtml, InsertAsPicture, InsertAsRtf, InsertAsUnicode e InsertAsBitmap selecionando a representação inserida, e AutoUpdate / IsLinked controlando o comportamento de atualização. FieldLink (LINK) é o equivalente ao OLE-link, adicionando FormatUpdateType. FieldImport (IMPORT) e FieldIncludePicture (INCLUDEPICTURE) inserem um gráfico externo via SourceFullName e GraphicFilter. FieldInclude (INCLUDE) e FieldIncludeText (INCLUDETEXT) inserem conteúdo de documento externo, com BookmarkName para delimitar o intervalo incluído e LockFields para impedir que seja atualizado; FieldIncludeText também oferece suporte a fontes XML através de Encoding, MimeType, NamespaceMappings, XPath e XslTransformation.
Etapa 8: Referenciar Blocos de Construção e Entradas de Glossário
FieldAutoText (AUTOTEXT), FieldAutoTextList (AUTOTEXTLIST) e FieldGlossary (GLOSSARY) referenciam todas uma entrada de bloco de construção nomeada através de EntryName; FieldAutoTextList adiciona ListStyle e ScreenTip para sua apresentação em estilo de lista.
Etapa 9: Inserir Campos de Citação e Bibliografia
FieldCitation (CITATION) e FieldBibliography (BIBLIOGRAPHY) renderizar conteúdo proveniente dos dados de bibliografia do documento. Defina FieldCitation.SourceTag (ou o alternativo AnotherSourceTag) para identificar qual fonte ele cita, e usar Prefix, Suffix, PageNumber, VolumeNumber, e o Suppress* flags (SuppressAuthor, SuppressTitle, SuppressYear) para controlar como a citação é formatada. FieldBibliography.SourceTag, FilterLanguageId, e FormatLanguageId controlar quais fontes aparecem na bibliografia renderizada e em que idioma. Esses campos só são renderizados corretamente depois que o correspondente Source os registros existem – veja o guia de bibliografia para criá-los.
Problemas Comuns e Soluções
O campo REF, PAGEREF ou NOTEREF exibe um resultado de erro O BookmarkName o destino não existe no documento. Crie o marcador com DocumentBuilder.StartBookmark() / EndBookmark() antes de atualizar o campo.
O campo ASK ou FILLIN bloqueia uma atualização não assistida Nenhum callback está atribuído para fornecer uma resposta programaticamente. Atribua o callback de atualização de campo descrito no guia de campos, ou defina DefaultResponse no campo para que ele tenha um valor padrão.
O campo CITATION ou BIBLIOGRAPHY renderiza vazio O SourceTag não corresponde a nenhum Source nos dados de bibliografia do documento. Adicione o correspondente Source – veja o guia de bibliografia.
O campo DDE, DDEAUTO ou LINK não atualiza Esses campos referenciam uma fonte OLE externa que não está disponível fora do contexto original Windows/OLE. Trate o resultado armazenado do campo como o último valor conhecido nessa situação.
Um hiperlink inserido com InsertHyperlink está faltando uma propriedade que eu preciso DocumentBuilder.InsertHyperlink() é um atalho que não expõe todos os FieldHyperlink propriedade. Construa ou recupere o FieldHyperlink diretamente para definir propriedades como ScreenTip or IsImageMap.
Perguntas Frequentes
Qual é a diferença entre FieldRef e FieldStyleRef?
FieldRef resolve para o conteúdo de um marcador nomeado (BookmarkName); FieldStyleRef resolve, por outro lado, para o parágrafo mais próximo formatado com um determinado StyleName, independentemente de marcadores.
Como insiro um hiperlink simples sem construir um Field manualmente?
Chame DocumentBuilder.InsertHyperlink(displayText, urlOrBookmark, isBookmark).
Essas classes de campo de link e referência estão em um namespace separado dos outros campos?
Não – FieldHyperlink, FieldRef, FieldCitation, e o resto das classes abordadas aqui são subclasses ordinárias de Field no namespace Aspose.Words.Fields, o mesmo namespace usado para todo outro tipo de campo.
Como os campos de citação se relacionam com o modelo de dados da bibliografia?
FieldCitation and FieldBibliography renderizar conteúdo ao buscar SourceTag contra o Source registros descritos no guia de bibliografia – essas classes de campo lidam com a renderização, enquanto as Source and Contributor classes mantêm os dados subjacentes.
Como crio um bookmark antes de referenciá-lo?
Chame DocumentBuilder.StartBookmark(bookmarkName) antes do conteúdo, e DocumentBuilder.EndBookmark(bookmarkName) depois dele, usando o mesmo nome para ambas as chamadas.
