Hiperlinks

  • Artigo

Os hiperlinks levam o usuário para outra parte do aplicativo, para outro aplicativo ou para iniciar um URI (Uniform Resource Identifier) específico usando um aplicativo de navegador separado. Há duas maneiras como um hiperlink pode ser adicionado a um aplicativo XAML: o elemento de texto Hyperlink e o controle HyperlinkButton.

Um botão de hiperlink

Esse é o controle correto?

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

Escolha o tipo correto 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 uma quebra de texto automática e não precisar necessariamente de um destino de toque grande. O texto do hiperlink pode ser pequeno e ser difícil de direcionar, especialmente para toque.
  • Use um HyperlinkButton para hiperlinks autônomos. Um HyperlinkButton é um controle de botão especializado que você pode usar em qualquer lugar onde usaria um botão.
  • Use um HyperlinkButton com uma (Imagem como seu conteúdo para criar uma imagem clicável.

Recomendações

  • Só use hiperlinks para navegação; não os utilize para outras ações.
  • Use o estilo Body da rampa de tipos para hiperlinks baseados em texto. Leia sobre fontes e a rampa de tipos do Windows.
  • Mantenha hiperlinks diferentes distantes o suficiente para que o usuário possa diferenciar entre eles e tenha facilidade ao selecionar cada uma deles.
  • Adicione dicas de ferramentas aos hiperlinks que indicam para onde o usuário será direcionado. Se o usuário for direcionado para um site externo, inclua o nome do domínio de nível superior na dica de ferramenta e defina o estilo do texto com uma cor de fonte secundária.

UWP e WinUI 2

Importante

As informações e exemplos neste artigo são otimizados para aplicativos que usam o SDK do Aplicativo Windows e o WinUI 3, mas geralmente são aplicáveis a aplicativos UWP que usam o WinUI 2. Consulte a referência da API da UWP para obter informações e exemplos específicos da plataforma.

Esta seção contém informações necessárias para usar o controle em um aplicativo UWP ou WinUI 2.

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

Criar um elemento de texto de hiperlink

Este exemplo mostra como usar um elemento de texto de hiperlink 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:

Exemplo de um hiperlink como um elemento de texto

Dica

Quando você usa um Hiperlink em um controle de texto com outros elementos de texto em XAML, coloque o conteúdo em um contêiner span e aplique o xml:space="preserve" atributo ao Span para manter o espaço em branco entre o Hiperlink e outros elementos.

Criar um HyperlinkButton

Abra o aplicativo Galeria do WinUI 3 e veja os Hiperlinks em ação.

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

Abaixo estão as instruções de como usar um HyperlinkButton com texto e 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 Contoso também é um hiperlink clicável:

Exemplo de um hiperlink como um controle de botão

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");

Manipular a navegação

Para os dois tipos de hiperlinks, você manipula a navegação da mesma maneira. Você pode definir a propriedade NavigateUri ou manipular o evento Click.

Para usar o hiperlink para navegar para 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 à parte do aplicativo.

Observação

Um URI é representado pela classe Windows.Foundation.Uri. Ao programar com .NET, essa classe fica oculta e você terá que usar a classe System.Uri. Para obter mais informações, confira as páginas de referência para essas classes.

Você não precisa usar esquemas http: nem https:. Poderá usar esquemas como ms-appx:, ms-appdata: ou ms-resources: se houver conteúdo de recurso nesses locais que seja apropriado carregar em um navegador. No entanto, o esquema file: é especificamente bloqueado. Para obter mais informações, consulte Esquemas de URI.

Quando um usuário clica no hiperlink, o valor da propriedade NavigateUri é passado para um manipulador do sistema para esquemas e tipos de URI. Em seguida, o sistema inicia o aplicativo que está registrado 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 código que faça o que você quer.

Manipular o evento Click.

Use o evento Click para ações que não sejam 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 de seu manipulador de eventos Click para navegar para a nova página do aplicativo. Se você quiser que um URI absoluto externo seja carregado dentro de um controle de WebView que também existe em seu aplicativo, chame WebView como parte da lógica de seu manipulador de cliques.

Você normalmente não manipula o evento Click tão bem quanto especifica um valor de NavigateUri, uma vez que esses representam duas maneiras diferentes de usar o elemento hyperlink. 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ê pode 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.

Por padrão, os hiperlinks são sublinhados. Esse sublinhado é importante porque ele ajuda a atender a requisitos de acessibilidade. Usuários daltônicos usam o sublinhado para distinguir entre os hiperlinks e outros textos. Se você desabilitar os sublinhados, deverá considerar a adição de algum outro tipo de formatação diferente para distinguir hiperlinks de outros textos, como FontWeight ou FontStyle.

Elementos de texto de hiperlink

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

HyperlinkButton

Por padrão, o HyperlinkButton aparece como texto sublinhado quando você configura 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 da 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 sem sublinhado, considere usar um controle de botão padrão e aplicar o recurso interno do sistema TextBlockButtonStyle para sua propriedade Style.

Observações para o elemento de texto de hiperlink

Esta seção aplica-se apenas ao elemento de texto de hiperlink, não para o controle HyperlinkButton.

Eventos de entrada

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

Conteúdo

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

O hiperlink não herda Control, portanto, ele não tem uma propriedade Style ou um Template. Você pode editar as propriedades que são herdadas de TextElement, como Foreground ou FontFamily, para alterar a aparência de um hiperlink, mas você não pode usar um estilo ou modelo comum para aplicar as alterações. Em vez de usar um modelo, considere usar recursos comuns para valores de propriedades de hiperlink para fornecer consistência. Algumas propriedades de hiperlink usam padrões de um valor de extensão de marcação {ThemeResource} fornecidos pelo sistema. Isso permite que a aparência do hiperlink seja alternada 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.

Obter o código de exemplo