Collegamenti ipertestuali

  • Articolo

I collegamenti ipertestuali passano all'utente a un'altra parte dell'app, a un'altra app o avviano un URI (Uniform Resource Identifier) specifico usando un'app del browser separata. Esistono due modi per aggiungere un collegamento ipertestuale a un'app XAML: l'elemento di testo Hyperlink e il controllo HyperlinkButton.

A hyperlink button

È il controllo giusto?

Usare un collegamento ipertestuale quando è necessario un testo che risponde quando viene premuto e sposta l'utente a ulteriori informazioni sul testo premuto.

Scegliere il tipo corretto di collegamento ipertestuale in base alle esigenze:

  • Utilizzare un elemento di testo Hyperlink inline all'interno di un controllo di testo. Un elemento Hyperlink scorre con altri elementi di testo ed è possibile usarlo in qualsiasi InlineCollection. Usare un collegamento ipertestuale di testo se si vuole eseguire il wrapping automatico del testo e non è necessario necessariamente un obiettivo di hit di grandi dimensioni. Il testo del collegamento ipertestuale può essere piccolo e difficile da indirizzare, soprattutto per il tocco.
  • Utilizzare un controllo HyperlinkButton per collegamenti ipertestuali autonomi. Un controllo HyperlinkButton è un controllo Button specializzato che è possibile usare ovunque si usi un pulsante.
  • Usare un controllo HyperlinkButton con un'immagine come contenuto per creare un'immagine selezionabile.

Consigli

  • Utilizza solo collegamenti ipertestuali per la navigazione; non usarli per altre azioni.
  • Utilizzare lo stile Corpo dalla rampa di tipo per i collegamenti ipertestuali basati su testo. Informazioni sui tipi di carattere e sulla rampa dei tipi di Windows.
  • Mantenere i collegamenti ipertestuali discreti abbastanza distanti in modo che l'utente possa distinguere tra di essi e ha un tempo semplice per la selezione di ognuno di essi.
  • Aggiungere descrizioni comando ai collegamenti ipertestuali che indicano dove verrà indirizzato l'utente. Se l'utente verrà indirizzato a un sito esterno, includere il nome di dominio di primo livello all'interno della descrizione comando e applicare uno stile al testo con un colore del carattere secondario.

Piattaforma UWP e WinUI 2

Importante

Le informazioni e gli esempi in questo articolo sono ottimizzati per le app che usano Windows App SDK e WinUI 3, ma sono generalmente applicabili alle app UWP che usano WinUI 2. Per informazioni ed esempi specifici della piattaforma, consultare le indicazioni di riferimento sulle API UWP.

Questa sezione contiene informazioni necessarie per usare il controllo in un'app UWP o WinUI 2.

Le API per questo controllo esistono nello spazio dei nomi Windows.UI.Xaml.Controls.

Creare un elemento di testo Hyperlink

In questo esempio viene illustrato come usare un elemento di testo Hyperlink all'interno di un controllo 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>

Il collegamento ipertestuale viene visualizzato inline e scorre con il testo circostante:

Example of a hyperlink as a text element

Suggerimento

Quando si usa un collegamento ipertestuale in un controllo di testo con altri elementi di testo in XAML, posizionare il contenuto in un contenitore Span e applicare l'attributo xml:space="preserve" all'elemento Span per mantenere lo spazio vuoto tra il collegamento ipertestuale e gli altri elementi.

Creare un controllo HyperlinkButton

Aprire l'app Raccolta WinUI 3 e visualizzare Hyperlinks in azione.

L'app Raccolta WinUI 3 include esempi interattivi della maggior parte dei controlli e delle funzionalità di WinUI 3. Scaricare l'app da Microsoft Store od ottenere il codice sorgente su GitHub

Ecco come usare un controllo HyperlinkButton, sia con testo che con un'immagine.

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

I pulsanti collegamento ipertestuale con contenuto di testo vengono visualizzati come testo contrassegnato. L'immagine del logo Contoso è anche un collegamento ipertestuale selezionabile:

Example of a hyperlink as a button control

Questo esempio mostra come creare un controllo HyperlinkButton nel codice.

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

Gestire la navigazione

Per entrambi i tipi di collegamenti ipertestuali, si gestisce lo stesso modo di navigazione; è possibile impostare la proprietà NavigateUri o gestire l'evento Click .

Per usare il collegamento ipertestuale per passare a un URI, impostare la proprietà NavigateUri. Quando un utente fa clic o tocca il collegamento ipertestuale, l'URI specificato viene aperto nel browser predefinito. Il browser predefinito viene eseguito in un processo separato dall'app.

Nota

Un URI è rappresentato dalla classe Windows.Foundation.Uri. Quando si programma con .NET, questa classe è nascosta, quindi si consiglia di usare la classe System. URI. Per altre info, vedi le pagine di riferimento per queste classi.

Non devi necessariamente usare gli schemi http: o https:. Puoi usare schemi come ms-appx:, ms-appdata: o ms-resources: se in queste posizioni è presente contenuto di risorse appropriato per il caricamento in un browser. Lo schema file: è tuttavia specificatamente bloccato. Per altre informazioni, vedere Schemi URI.

Quando un utente fa clic sul collegamento ipertestuale, il valore della proprietà NavigateUri viene passato a un gestore di sistema per tipi e schemi URI. Il sistema avvia quindi l'app registrata per lo schema dell'URI fornito per NavigateUri.

Se non si vuole che il collegamento ipertestuale carichi contenuto in un Web browser predefinito (e non si vuole che venga visualizzato un browser), non impostare un valore per NavigateUri. Gestire invece l'evento Click e scrivere codice che esegue le operazioni desiderate.

Gestire l'evento Click

Usa l'evento Click per azioni diverse dall'avvio di un URI in un browser, ad esempio lo spostamento all'interno dell'app. Ad esempio, se vuoi caricare una nuova pagina dell'app anziché aprire un browser, chiama un metodo Frame.Navigate all'interno del gestore eventi Click per passare alla nuova pagina dell'app. Se si vuole che un URI esterno assoluto venga caricato all'interno di un controllo WebView presente anche nell'app, chiamare WebView.Navigate come parte della logica del gestore Click.

In genere non si gestisce l'evento Click e si specifica un valore NavigateUri, perché rappresentano due modi diversi di usare l'elemento hyperlink. Se la finalità consiste nell'aprire l'URI nel browser predefinito e si è specificato un valore per NavigateUri, non gestire l'evento Click. Viceversa, se si gestisce l'evento Click, non specificare un NavigateUri.

Non è possibile eseguire alcuna operazione all'interno del gestore eventi Click per impedire al browser predefinito di caricare qualsiasi destinazione valida specificata per NavigateUri; tale azione viene eseguita automaticamente (in modo asincrono) quando il collegamento ipertestuale viene attivato e non può essere annullato dall'interno del gestore eventi Click.

Per impostazione predefinita, i collegamenti ipertestuali sono sottolineati. Questa sottolineatura è importante perché consente di soddisfare i requisiti di accessibilità. Gli utenti color-blind usano la sottolineatura per distinguere tra collegamenti ipertestuali e altro testo. Se si disabilitano le sottolineature, è consigliabile aggiungere un altro tipo di differenza di formattazione per distinguere i collegamenti ipertestuali da altro testo, ad esempio FontWeight o FontStyle.

Elementi di testo Hyperlink

È possibile impostare la proprietà UnderlineStyle per disabilitare la sottolineatura. In tal caso, è consigliabile usare FontWeight o FontStyle per differenziare il testo del collegamento.

HyperlinkButton

Per impostazione predefinita, hyperlinkButton viene visualizzato come testo sottolineato quando si imposta una stringa come valore per la proprietà Content .

Il testo non viene sottolineato nei casi seguenti:

  • Impostare textBlock come valore per la proprietà Content e impostare la proprietà Text su TextBlock.
  • È possibile modificare nuovamente il modello HyperlinkButton e modificare il nome della parte del modello ContentPresenter .

Se è necessario un pulsante visualizzato come testo non sottolineato, è consigliabile usare un controllo Pulsante standard e applicare la risorsa di sistema predefinita TextBlockButtonStyle alla relativa proprietà Style.

Note per l'elemento di testo Hyperlink

Questa sezione si applica solo all'elemento di testo Hyperlink, non al controllo HyperlinkButton.

Eventi di input

Poiché un oggetto Hyperlink non è un oggetto UIElement, non dispone del set di eventi di input degli elementi dell'interfaccia utente, ad esempio Tapped, PointerPressed e così via. Al contrario, un oggetto Hyperlink ha un proprio evento Click, oltre al comportamento implicito del sistema che carica qualsiasi URI specificato come NavigateUri. Il sistema gestisce tutte le azioni di input che devono richiamare le azioni Hyperlink e genera l'evento Click in risposta.

Sommario

Il collegamento ipertestuale presenta restrizioni sul contenuto che può esistere nella raccolta Inlines . In particolare, un collegamento ipertestuale consente solo l'esecuzione e altri tipi span che non sono un altro collegamento ipertestuale. InlineUIContainer non può trovarsi nell'insieme Inlines di un oggetto Hyperlink. Il tentativo di aggiungere contenuto con restrizioni genera un'eccezione di argomento non valida o un'eccezione di analisi XAML.

Il collegamento ipertestuale non eredita da Control, quindi non dispone di una proprietà Style o di un modello. È possibile modificare le proprietà ereditate da TextElement, ad esempio Foreground o FontFamily, per modificare l'aspetto di un collegamento ipertestuale, ma non è possibile usare uno stile o un modello comuni per applicare le modifiche. Invece di usare un modello, è consigliabile usare le risorse comuni per i valori delle proprietà Collegamento ipertestuale per garantire la coerenza. Alcune proprietà di Hyperlink usano le impostazioni predefinite di un valore di estensione di markup {ThemeResource} fornito dal sistema. Ciò consente all'aspetto collegamento ipertestuale di passare in modi appropriati quando l'utente modifica il tema di sistema in fase di esecuzione.

Il colore predefinito del collegamento ipertestuale è il colore principale del sistema. È possibile impostare la proprietà Foreground su cui eseguire l'override.

Scaricare il codice di esempio