Compartilhar via

Hiperlinks

  • Artigo

Os hiperlinks direcionam o usuário para outra parte do aplicativo, para outro aplicativo ou iniciam um URI (Uniform Resource Identifier) 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.

Um botão de hiperlink

Esse é o controle correto?

Use um hiperlink quando precisar de um 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 destino de resultado grande. O texto do hiperlink pode ser pequeno e difícil de segmentar, especialmente para toque.
  • Use um HyperlinkButton para hiperlinks autônomos. Um HyperlinkButton é um controle Button especializado que você pode usar em qualquer lugar que usaria um Button.
  • Use um HyperlinkButton com uma imagem como seu conteúdo para criar uma imagem clicável.

Recomendações

  • Use hiperlinks apenas para navegação; não os use para outras ações.
  • Use o estilo Corpo da rampa de tipos para hiperlinks baseados em texto. Leia sobre fontes e a rampa de tipos do Windows.
  • Mantenha os hiperlinks discretos distantes 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.

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 de 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 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:

Exemplo de um hiperlink como um elemento de texto

Dica

Ao usar um Hyperlink 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 Hyperlink 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

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:

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

Lidar com 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 .

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.

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 tipos e esquemas de URI. Em seguida, o sistema inicia o aplicativo 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 o código que faz 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 no 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 no manipulador de eventos Click para navegar até a nova página do aplicativo. Se você quiser que um URI externo absoluto seja carregado em um controle WebView que também existe em seu aplicativo, chame WebView.Navigate como parte da lógica do manipulador de cliques.

Normalmente, você não manipula o evento Click, bem como especifica um valor NavigateUri, pois eles 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ê 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 cancelado de dentro do manipulador de eventos Click.

Por padrão, os hiperlinks são sublinhados. Este sublinhado é importante porque ajuda a atender aos requisitos de acessibilidade. Usuários daltônicos usam o sublinhado para distinguir entre hiperlinks e outros textos. 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 hiperlink

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.

HyperlinkButton

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:

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 TextBlockButtonStyle sistema à 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 de elemento de interface do usuário, como Tapped, PointerPressed e assim por diante. Em vez disso, um Hyperlink tem seu próprio evento Click, além do comportamento implícito do sistema que carrega qualquer URI especificado como NavigateUri. O sistema lida com todas as ações de entrada que devem invocar as ações de hiperlink e gera o evento Click em resposta.

Sumário

O hiperlink tem restrições sobre o conteúdo que pode existir em sua coleção Inlines . Especificamente, um hiperlink permite apenas Run e outros tipos de Span que não são outro Hyperlink. 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.

O hiperlink não herda de 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 de hiperlink 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 Hyperlink 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.

Obter o código de exemplo