Trabalhando com Links e Referências

Trabalhando com Links e Referências

Visão geral

Códigos de campo de link e referência cruzada do Word – HYPERLINK, REF, PAGEREF, NOTEREF, STYLEREF, SET, ASK, FILLIN, CITATION, BIBLIOGRAPHY, e mais – são cada um implementados como um dedicado Field subclasse em Aspose.Words FOSS para .NET. Todas estas classes residem no Aspose.Words.Fields namespace ao lado de todos os outros tipos de campo; esta página agrupa as que são especificamente relacionadas a links, referências cruzadas, valores solicitados e citações, e descreve o que cada uma expõe.


Hyperlinks

FieldHyperlink representa o campo HYPERLINK: Address e SubAddress contêm a URL de destino ou a localização dentro do documento, ScreenTip define a dica de ferramenta ao passar o mouse, OpenInNewWindow e IsImageMap são sinalizadores de exibição, e Target nomeia uma moldura do navegador. Para casos simples, DocumentBuilder.InsertHyperlink() insere um campo de hipervínculo diretamente sem construir o objeto Field manualmente.


Referências Cruzadas para Marcadores

FieldRef (o campo REF), FieldPageRef (PAGEREF) e FieldNoteRef (NOTEREF) resolvem cada um para o conteúdo em um marcador nomeado via sua propriedade BookmarkName, com InsertHyperlink e InsertRelativePosition controlando se a referência é clicável e se relata uma posição relativa (“acima” / “abaixo”). FieldRef adiciona opções de numeração de parágrafos (InsertParagraphNumber, InsertParagraphNumberInFullContext, InsertParagraphNumberInRelativeContext, NumberSeparator) e IncludeNoteOrComment. FieldStyleRef (STYLEREF) em vez disso resolve para o parágrafo mais próximo formatado com um determinado StyleName, com SearchFromBottom para buscar retroativamente a partir da posição do campo. Os marcadores que esses campos apontam são criados com DocumentBuilder.StartBookmark() e EndBookmark(), e podem ser navegados com MoveToBookmark(). FieldSet (SET) define um valor de texto marcado — BookmarkName e BookmarkText — que um campo REF em outro lugar pode resolver.


Campos de Valor Solicitado

FieldAsk (ASK) e FieldFillIn (FILLIN) solicitam um valor de quem atualiza o campo: PromptText é exibido ao usuário, DefaultResponse fornece um fallback, e PromptOnceOnMailMerge limita solicitações repetidas durante uma mesclagem de correspondência. FieldAsk também armazena sua resposta em BookmarkName para que outros campos a referenciem. Veja o guia de campos for IFieldUserPromptRespondent, o callback que fornece respostas a esses campos programaticamente em vez de solicitar interativamente.


Conteúdo Externo e Vinculado

FieldDde (DDE) e FieldDdeAuto (DDEAUTO) vinculam a conteúdo em outra aplicação 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 de link OLE, adicionando FormatUpdateType. FieldImport (IMPORT) e FieldIncludePicture (INCLUDEPICTURE) trazem um gráfico externo via SourceFullName e GraphicFilter. FieldInclude (INCLUDE) e FieldIncludeText (INCLUDETEXT) trazem conteúdo de documento externo, com BookmarkName para delimitar o intervalo incluído e LockFields para impedir que seja atualizado; FieldIncludeText também suporta fontes XML através de Encoding, MimeType, NamespaceMappings, XPath e XslTransformation.


AutoText e Referências ao Glossário

FieldAutoText (AUTOTEXT), FieldAutoTextList (AUTOTEXTLIST) e FieldGlossary (GLOSSARY) todos referenciam 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.


Campos de Citação e Bibliografia

FieldCitation (CITATION) e FieldBibliography (BIBLIOGRAPHY) renderiza o conteúdo proveniente dos dados de bibliografia do documento. FieldCitation.SourceTag (e o alternativo AnotherSourceTag) identifica qual fonte ele cita, com Prefix, Suffix, PageNumber, VolumeNumber, e o Suppress* flags (SuppressAuthor, SuppressTitle, SuppressYear) controlando como a citação é formatada. FieldBibliography.SourceTag, FilterLanguageId, e FormatLanguageId controlam quais fontes aparecem na bibliografia renderizada e em que idioma. O registro subjacente da fonte renderiza esses campos – Source, Contributor, Person – são abordados no guia de bibliografia.


Campos de Texto de Citação e Forma

FieldQuote (QUOTE) e FieldShape (SHAPE) ambos expõem uma propriedade Text que contém texto literal de campo – FieldQuote insere-o diretamente na posição do campo, enquanto FieldShape o associa ao código de campo que transporta texto de uma forma de desenho.


Dicas e melhores práticas

  • Prefira DocumentBuilder.InsertHyperlink() para inserção simples de hyperlink; recorra à construção direta de um FieldHyperlink somente quando precisar de propriedades como ScreenTip ou IsImageMap que o atalho do construtor não expõe.
  • FieldRef, FieldPageRef, FieldNoteRef e FieldSet coordenam-se todos através de BookmarkName – certifique-se de que o marcador de destino existe (via DocumentBuilder.StartBookmark() / EndBookmark()) antes que o campo que o referencia seja atualizado.
  • Conjunto FieldOptions.UserPromptRespondent (veja o guia de campos) antes de atualizar um documento contendo FieldAsk or FieldFillIn campos em um pipeline não supervisionado.
  • FieldDde e FieldDdeAuto modelam um mecanismo legado de vinculação OLE do Windows – trate AutoUpdate e IsLinked como informacionais ao processar documentos fora do Windows, já que o aplicativo externo do qual normalmente seriam atualizados não está disponível.
  • Campos de citação e bibliografia só são renderizados corretamente uma vez que o subjacente do documento Source os registros existem – veja o guia de bibliografia para construí-los.

Problemas comuns

ProblemaCausaCorreção
REF / PAGEREF / NOTEREF campo exibe um resultado de erroO BookmarkName que ele visa não existe no documentoCrie o marcador com DocumentBuilder.StartBookmark() / EndBookmark() antes de atualizar o campo
O campo ASK / FILLIN bloqueia uma atualização não supervisionadaNenhum IFieldUserPromptRespondent está atribuídoAtribua FieldOptions.UserPromptRespondent, ou defina DefaultResponse no campo
O campo CITATION ou BIBLIOGRAPHY exibe vazioO SourceTag não corresponde a nenhum Source nos dados de bibliografia do documentoAdicione a correspondência Source – veja o guia de bibliografia
campo DDE / DDEAUTO / LINK não atualizaEssas referenciam uma fonte OLE externa que não está disponível no ambiente atualEsperado fora do contexto original Windows/OLE – trate o Result armazenado como o último valor conhecido

FAQ

Qual é a diferença entre FieldRef e FieldStyleRef?

FieldRef resolve para o conteúdo em um marcador nomeado (BookmarkName); FieldStyleRef resolve, em vez disso, para o parágrafo mais próximo formatado com um determinado StyleName, independentemente de marcadores.

Como insiro um hiperlink simples sem criar um Field manualmente?

Chame DocumentBuilder.InsertHyperlink().

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 nesta página são comuns Field subclasses no Aspose.Words.Fields namespace, o mesmo namespace abordado no guia de campos.

Como os campos de citação se relacionam ao modelo de dados da bibliografia?

FieldCitation and FieldBibliography renderizar conteúdo pesquisando SourceTag contra o Source registros descritos no guia de bibliografia – as classes de campo lidam com a renderização, e as Source / Contributor classes mantêm os dados subjacentes.


API Reference Resumo

ClasseDescrição
FieldHyperlinkHYPERLINK field; Address, SubAddress, ScreenTip, OpenInNewWindow
FieldRef / FieldPageRef / FieldNoteRefcampos REF / PAGEREF / NOTEREF; resolve o conteúdo em um BookmarkName
FieldStyleRefcampo STYLEREF; resolve para o parágrafo mais próximo em um estilo dado
FieldSetcampo SET; define um valor de texto marcado para REF resolver
FieldAsk / FieldFillIncampos ASK / FILLIN; solicite um valor durante a atualização
FieldDde / FieldDdeAuto / FieldLinkcampos DDE / DDEAUTO / LINK; conteúdo externo legado vinculado por OLE
FieldImport / FieldIncludePicturecampos IMPORT / INCLUDEPICTURE; conteúdo gráfico externo
FieldInclude / FieldIncludeTextcampos INCLUDE / INCLUDETEXT; documento externo ou conteúdo XML
FieldAutoText / FieldAutoTextList / FieldGlossarycampos AUTOTEXT / AUTOTEXTLIST / GLOSSARY; entradas de bloco de construção de referência
FieldCitation / FieldBibliographycampos CITATION / BIBLIOGRAPHY; renderizar dados de origem da bibliografia
FieldQuote / FieldShapecampos QUOTE / SHAPE; texto literal do campo
DocumentBuilder.InsertHyperlinkAtalho de inserção de hyperlink de alto nível
DocumentBuilder.StartBookmark / EndBookmark / MoveToBookmarkCriação e navegação de marcadores para alvos de referência

Ver também

 Português