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 umFieldHyperlinksomente quando precisar de propriedades comoScreenTipouIsImageMapque o atalho do construtor não expõe. FieldRef,FieldPageRef,FieldNoteRefeFieldSetcoordenam-se todos através deBookmarkName– certifique-se de que o marcador de destino existe (viaDocumentBuilder.StartBookmark()/EndBookmark()) antes que o campo que o referencia seja atualizado.- Conjunto
FieldOptions.UserPromptRespondent(veja o guia de campos) antes de atualizar um documento contendoFieldAskorFieldFillIncampos em um pipeline não supervisionado. FieldDdeeFieldDdeAutomodelam um mecanismo legado de vinculação OLE do Windows – trateAutoUpdateeIsLinkedcomo 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
Sourceos registros existem – veja o guia de bibliografia para construí-los.
Problemas comuns
| Problema | Causa | Correção |
|---|---|---|
REF / PAGEREF / NOTEREF campo exibe um resultado de erro | O BookmarkName que ele visa não existe no documento | Crie o marcador com DocumentBuilder.StartBookmark() / EndBookmark() antes de atualizar o campo |
O campo ASK / FILLIN bloqueia uma atualização não supervisionada | Nenhum IFieldUserPromptRespondent está atribuído | Atribua FieldOptions.UserPromptRespondent, ou defina DefaultResponse no campo |
O campo CITATION ou BIBLIOGRAPHY exibe vazio | O SourceTag não corresponde a nenhum Source nos dados de bibliografia do documento | Adicione a correspondência Source – veja o guia de bibliografia |
campo DDE / DDEAUTO / LINK não atualiza | Essas referenciam uma fonte OLE externa que não está disponível no ambiente atual | Esperado 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
| Classe | Descrição |
|---|---|
FieldHyperlink | HYPERLINK field; Address, SubAddress, ScreenTip, OpenInNewWindow |
FieldRef / FieldPageRef / FieldNoteRef | campos REF / PAGEREF / NOTEREF; resolve o conteúdo em um BookmarkName |
FieldStyleRef | campo STYLEREF; resolve para o parágrafo mais próximo em um estilo dado |
FieldSet | campo SET; define um valor de texto marcado para REF resolver |
FieldAsk / FieldFillIn | campos ASK / FILLIN; solicite um valor durante a atualização |
FieldDde / FieldDdeAuto / FieldLink | campos DDE / DDEAUTO / LINK; conteúdo externo legado vinculado por OLE |
FieldImport / FieldIncludePicture | campos IMPORT / INCLUDEPICTURE; conteúdo gráfico externo |
FieldInclude / FieldIncludeText | campos INCLUDE / INCLUDETEXT; documento externo ou conteúdo XML |
FieldAutoText / FieldAutoTextList / FieldGlossary | campos AUTOTEXT / AUTOTEXTLIST / GLOSSARY; entradas de bloco de construção de referência |
FieldCitation / FieldBibliography | campos CITATION / BIBLIOGRAPHY; renderizar dados de origem da bibliografia |
FieldQuote / FieldShape | campos QUOTE / SHAPE; texto literal do campo |
DocumentBuilder.InsertHyperlink | Atalho de inserção de hyperlink de alto nível |
DocumentBuilder.StartBookmark / EndBookmark / MoveToBookmark | Criação e navegação de marcadores para alvos de referência |