Hyperlinks

Os hiperlinks navegam o usuário para outra parte do aplicativo, para outro aplicativo ou iniciam um URI (identificador uniforme de recursos) específico usando um aplicativo de navegador separado. Há duas maneiras de adicionar um hiperlink a um aplicativo XAML: o elemento de texto Hyperlink e o controle HyperlinkButton .

Será este o controlo correto?

Use um hiperlink quando precisar de texto que responda quando pressionado e navegue o usuário para obter mais informações sobre o texto que foi pressionado.

Escolha o tipo certo de hiperlink com base em suas necessidades:

• Use um elemento de texto Hyperlink embutido dentro de um controle de texto. Um elemento Hyperlink flui com outros elementos de texto e você pode usá-lo em qualquer InlineCollection. Use um hiperlink de texto se quiser quebra automática de texto e não precisar necessariamente de um alvo de visitas grande. O texto do hiperlink pode ser pequeno e difícil de segmentar, especialmente em dispositivos de toque.
• Use uma HyperlinkButton para hiperlinks autónomos. Um HyperlinkButton é um controle Button especializado que você pode usar em qualquer lugar que você usaria um Button.
• Use um HyperlinkButton com uma Imagem como conteúdo para criar uma imagem clicável.

Recommendations

• Utilize apenas hiperligações para navegação; não os use para outras ações.
• Use o estilo Corpo da rampa de texto para hiperlinks baseados em texto. Leia sobre fontes e a hierarquia tipográfica do Windows.
• Mantenha hiperlinks discretos separados o suficiente para que o usuário possa diferenciá-los e tenha facilidade em selecionar cada um.
• Adicione dicas de ferramentas a hiperlinks que indicam para onde o usuário será direcionado. Se o usuário for direcionado para um site externo, inclua o nome de domínio de nível superior dentro da dica de ferramenta e estilize o texto com uma cor de fonte secundária.

Criar um elemento de texto Hyperlink

Este exemplo mostra como usar um elemento de texto Hyperlink dentro de um TextBlock.

<StackPanel Width="200">
    <TextBlock Text="Privacy" Style="{StaticResource SubheaderTextBlockStyle}"/>
    <TextBlock TextWrapping="WrapWholeWords">
        <Span xml:space="preserve"><Run>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Read the </Run><Hyperlink NavigateUri="http://www.contoso.com">Contoso Privacy Statement</Hyperlink><Run> in your browser.</Run> Donec pharetra, enim sit amet mattis tincidunt, felis nisi semper lectus, vel porta diam nisi in augue.</Span>
    </TextBlock>
</StackPanel>

O hiperlink aparece embutido e flui com o texto ao redor:

Criar um Botão de Hiperlink

O aplicativo WinUI 3 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 3. Obtenha o aplicativo no da Microsoft Store ou obtenha o código-fonte em do GitHub

Veja como usar um HyperlinkButton, tanto com texto quanto com uma imagem.

<StackPanel>
    <TextBlock Text="About" Style="{StaticResource TitleTextBlockStyle}"/>
    <HyperlinkButton NavigateUri="http://www.contoso.com">
        <Image Source="Assets/ContosoLogo.png"/>
    </HyperlinkButton>
    <TextBlock Text="Version: 1.0.0001" Style="{StaticResource CaptionTextBlockStyle}"/>
    <HyperlinkButton Content="Contoso.com" NavigateUri="http://www.contoso.com"/>
    <HyperlinkButton Content="Acknowledgments" NavigateUri="http://www.contoso.com"/>
    <HyperlinkButton Content="Help" NavigateUri="http://www.contoso.com"/>
</StackPanel>

Os botões de hiperlink com conteúdo de texto aparecem como texto marcado. A imagem do logotipo da Contoso também é um hiperlink clicável:

Este exemplo mostra como criar um HyperlinkButton no código.

HyperlinkButton helpLinkButton = new HyperlinkButton();
helpLinkButton.Content = "Help";
helpLinkButton.NavigateUri = new Uri("http://www.contoso.com");

Gerir a navegação

Para ambos os tipos de hiperlinks, você lida com a navegação da mesma maneira; você pode definir a propriedade NavigateUri ou manipular o evento Click.

Navegar até um URI

Para usar o hiperlink para navegar até um URI, defina a propriedade NavigateUri. Quando um usuário clica ou toca no hiperlink, o URI especificado é aberto no navegador padrão. O navegador padrão é executado em um processo separado do seu aplicativo.

Você não precisa usar http: ou https:. Você pode usar esquemas como ms-appx:, ms-appdata:, ou ms-resources:, se houver conteúdo de recursos nesses locais apropriado para carregar em um navegador. No entanto, o esquema file: está especificamente bloqueado. Para saber mais, veja Esquemas de URI.

Quando um usuário clica no hiperlink, o valor da propriedade NavigateUri é passado para um manipulador de sistema para tipos e esquemas de URI. Em seguida, o sistema inicia a aplicação que está registada para o esquema do URI fornecido para NavigateUri.

Se você não quiser que o hiperlink carregue conteúdo em um navegador da Web padrão (e não quiser que um navegador apareça), não defina um valor para NavigateUri. Em vez disso, manipule o evento Click e escreva um código que faça o que você deseja.

Manipular o evento Click

Use o evento Click para ações diferentes de iniciar um URI em um navegador, como navegação dentro do aplicativo. Por exemplo, se você quiser carregar uma nova página de aplicativo em vez de abrir um navegador, chame um método Frame.Navigate dentro do manipulador de eventos Click para navegar até a nova página do aplicativo. Se você quiser que um URI externo absoluto seja carregado dentro de um controle WebView que também existe em seu aplicativo, chame WebView.Navigate como parte da lógica do manipulador Click.

Normalmente, você não manipula o evento Click nem especifica um valor NavigateUri, pois eles representam duas maneiras diferentes de usar o elemento de hiperlink. Se sua intenção for abrir o URI no navegador padrão e você tiver especificado um valor para NavigateUri, não manipule o evento Click. Por outro lado, se você manipular o evento Click, não especifique um NavigateUri.

Não há nada que você possa fazer no manipulador de eventos Click para impedir que o navegador padrão carregue qualquer destino válido especificado para NavigateUri; essa ação ocorre automaticamente (de forma assíncrona) quando o hiperlink é ativado e não pode ser cancelada de dentro do manipulador de eventos Click.

Sublinhados de hiperligações

Por padrão, os hiperlinks são sublinhados. Este sublinhado é importante porque ajuda a cumprir os requisitos de acessibilidade. Os daltónicos utilizam o sublinhado para distinguir entre hiperligações e outro texto. Se você desabilitar sublinhados, considere adicionar algum outro tipo de diferença de formatação para distinguir hiperlinks de outro texto, como FontWeight ou FontStyle.

Elementos de texto de hiperligações

Você pode definir a propriedade UnderlineStyle para desabilitar o sublinhado. Se você fizer isso, considere usar FontWeight ou FontStyle para diferenciar o texto do link.

Botão de Hiperligação

Por padrão, o HyperlinkButton aparece como texto sublinhado quando você define uma cadeia de caracteres como o valor da propriedade Content .

O texto não aparece sublinhado nos seguintes casos:

• Você define um TextBlock como o valor para a propriedade Content e define a propriedade Text no TextBlock.
• Você remodela o HyperlinkButton e altera o nome da parte do modelo ContentPresenter .

Se você precisar de um botão que apareça como texto não sublinhado, considere usar um controle Button padrão e aplicar o recurso interno do sistema TextBlockButtonStyle à sua propriedade Style.

Notas para o elemento de texto Hyperlink

Esta seção se aplica somente ao elemento de texto Hyperlink, não ao controle HyperlinkButton.

Eventos de entrada

Como um Hyperlink não é um UIElement, ele não tem o conjunto de eventos de entrada do elemento da interface do usuário, como Tapped, PointerPressed e assim por diante. Em vez disso, um Hyperlink tem o seu próprio evento de clique, além do comportamento implícito do sistema ao carregar qualquer URI especificado como NavigateUri. O sistema lida com todas as ações de entrada que devem invocar as ações Hyperlink e gera o evento Click em resposta.

Content

Hyperlink tem restrições sobre o conteúdo que pode existir em sua coleção Inlines . Especificamente, um Hiperlink só permite Run e outros tipos de Span que não sejam outro Hiperlink. InlineUIContainer não pode estar na coleção Inlines de um Hyperlink. A tentativa de adicionar conteúdo restrito gera uma exceção de argumento inválido ou uma exceção de análise XAML.

Comportamento de hiperlink e tema/estilo

O hiperlink não herda do Control, portanto, não tem uma propriedade Style ou um Template. Você pode editar as propriedades herdadas de TextElement, como Foreground ou FontFamily, para alterar a aparência de um Hyperlink, mas não pode usar um estilo ou modelo comum para aplicar alterações. Em vez de usar um modelo, considere o uso de recursos comuns para valores de propriedades Hyperlink para fornecer consistência. Algumas propriedades do Hyperlink usam padrões de um valor de extensão de marcação {ThemeResource} fornecido pelo sistema. Isso permite que a aparência do hiperlink alterne de maneiras apropriadas quando o usuário altera o tema do sistema em tempo de execução.

A cor padrão do hiperlink é a cor de destaque do sistema. Você pode definir a propriedade Foreground para substituir isso.

UWP e WinUI 2

As APIs para esse controle existem no namespace Windows.UI.Xaml.Controls .

Artigos relacionados

• Controles de texto
• Diretrizes para dicas de ferramentas
• Classe de hiperlink
• classe HyperlinkButton