Blocco di testo

  • Articolo

Il blocco di testo è il controllo principale per la visualizzazione di testo in sola lettura nelle app. È possibile usarlo per visualizzare testo su riga singola o su più righe, collegamenti ipertestuali inline e testo con formattazione come grassetto, corsivo o sottolineato.

È il controllo giusto?

Un blocco di testo è più facile da usare e fornisce prestazioni di rendering del testo migliori rispetto a un blocco di testo RTF, quindi è preferibile per la maggior parte del testo dell'interfaccia utente delle app. È possibile accedere e usare facilmente il testo da un blocco di testo nell'app ottenendo il valore della proprietà Text. Offre anche molte delle stesse opzioni di formattazione per personalizzare il rendering del testo.

Anche se puoi inserire interruzioni di riga nel testo, un blocco di testo è progettato per visualizzare un singolo paragrafo e non supporta il rientro del testo. Usare un RichTextBlock quando è necessario il supporto per più paragrafi, testo a più colonne o altri layout di testo complessi o elementi dell'interfaccia utente inline, ad esempio immagini.

Per altre informazioni su come scegliere il controllo di testo più appropriato, vedi l'articolo Controlli di testo.

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 sono presenti nello spazio dei nomi Windows.UI.Xaml.Controls.

È consigliabile usare la versione più recente di WinUI 2 per ottenere gli stili, i modelli e le funzionalità più recenti per tutti i controlli.

Creare un blocco di testo

Aprire l'app Raccolta WinUI 3 e vedere TextBlock 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 definire un semplice controllo TextBlock e impostarne la proprietà Text su una stringa.

<TextBlock Text="Hello, world!" />

TextBlock textBlock1 = new TextBlock();
textBlock1.Text = "Hello, world!";

Modello di contenuto

Sono disponibili due proprietà per aggiungere contenuto a un elemento TextBlock: Text e Inlines.

Il modo più comune per visualizzare testo consiste nell'impostare la proprietà Text su un valore stringa, come mostra l'esempio precedente.

È anche possibile aggiungere contenuto inserendo elementi di contenuto del flusso inline nella proprietà TextBox.Inlines, come illustrato di seguito.

<TextBlock>Text can be <Bold>bold</Bold>, <Underline>underlined</Underline>, 
    <Italic>italic</Italic>, or a <Bold><Italic>combination</Italic></Bold>.</TextBlock>

Gli elementi derivati dalla classe Inline come Bold, Italic, Run, Span e LineBreak consentono una formattazione diversa per parti diverse del testo. Per altre informazioni, vedere la sezione Formattazione del testo. L'elemento Hyperlink inline permette di aggiungere un collegamento ipertestuale al testo. Tuttavia, l'uso di Inlines disabilita anche il rendering del testo del percorso rapido, ovvero l'argomento della sezione successiva.

Considerazioni sulle prestazioni

Quando possibile, XAML usa un percorso di codice più efficiente per il layout del testo. Questo percorso rapido riduce l'uso complessivo della memoria e il tempo della CPU per misurare e disporre il testo. Questo percorso rapido si applica solo a TextBlock, pertanto preferirlo quando possibile rispetto a RichTextBlock.

Alcune condizioni richiedono il fallback di TextBlock a un percorso di codice più funzionale e con uso intensivo di CPU per il rendering del testo. Per mantenere il rendering del testo sul percorso rapido, assicurarsi di seguire queste linee guida nell'impostare le proprietà elencate qui.

  • Text: la condizione più importante è che il percorso rapido venga usato solo quando si imposta il testo impostando in modo esplicito la proprietà Text, in XAML o nel codice, come mostrato negli esempi precedenti. Con l'impostazione del testo tramite la raccolta Inlines di TextBlock (ad esempio <TextBlock>Inline text</TextBlock>) verrà disabilitato il percorso rapido a causa della potenziale complessità dei formati multipli.
  • CharacterSpacing: solo il valore predefinito 0 è il percorso rapido.
  • TextTrimming: solo i valori None, CharacterEllipsis e WordEllipsis sono il percorso rapido. Il valore Clip disabilita il percorso rapido.

Nota Prima di Windows 10, versione 1607, proprietà aggiuntive influiscono sul percorso rapido. Se l'app viene eseguita in una versione precedente di Windows, queste condizioni causano anche il rendering del testo sul percorso lento. Per altre informazioni sulle versioni, vedere Codice adattivo per la versione.

  • Typography: solo i valori predefiniti per le varie proprietà Typography sono il percorso rapido.
  • LineStackingStrategy: se LineHeight è diverso da 0, i valori BaselineToBaseline e MaxHeight disabilitano il percorso rapido.
  • IsTextSelectionEnabled: solo false è il percorso rapido. L'impostazione di questa proprietà su true disabilita il percorso rapido.

È possibile impostare la proprietà DebugSettings.IsTextPerformanceVisualizationEnabled su true durante il debug per determinare se il testo usa il rendering del percorso rapido. Quando questa proprietà è impostata su true, il testo che si trova sul percorso rapido viene visualizzato in un colore verde brillante.

Suggerimento Questa funzionalità è illustrata in modo approfondito in questa sessione dalla Build 2015 - Prestazioni XAML: tecniche per massimizzare le esperienze app di Windows universale create con XAML.

In genere, le impostazioni di debug vengono impostate nell'override del metodo OnLaunched nella pagina code-behind per App.xaml, come illustrato di seguito.

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
#if DEBUG
    if (System.Diagnostics.Debugger.IsAttached)
    {
        this.DebugSettings.IsTextPerformanceVisualizationEnabled = true;
    }
#endif

// ...

}

In questo esempio si esegue il rendering del primo oggetto TextBlock usando il percorso rapido, non del secondo.

<StackPanel>
    <TextBlock Text="This text is on the fast path."/>
    <TextBlock>This text is NOT on the fast path.</TextBlock>
<StackPanel/>

Quando si esegue questo XAML in modalità debug con IsTextPerformanceVisualizationEnabled impostato su true, il risultato è simile al seguente.

Text rendered in debug mode

Attenzione

Il colore del testo che non si trova sul percorso rapido non viene modificato. Se è presente del testo nell'app con il colore specificato come verde brillante, viene sempre visualizzato in verde brillante quando si trova sul percorso di rendering più lento. Fare attenzione a non confondere il testo impostato su verde nell'app con il testo verde sul percorso rapido a causa delle impostazioni di debug.

Formattazione di testo

Anche se la proprietà Text archivia testo normale, è possibile applicare varie opzioni di formattazione al controllo TextBlock per personalizzare il rendering del testo nell'app. È possibile impostare proprietà di controlli standard come FontFamily, FontSize, FontStyle, Foreground e CharacterSpacing per modificare l'aspetto del testo. È anche possibile usare elementi di testo inline e proprietà associate Typography per formattare il testo. Queste opzioni influiscono solo sul modo in cui TextBlock mostra il testo in locale, pertanto se si copia e incolla il testo in un controllo di testo RTF, ad esempio, non viene applicata alcuna formattazione.

Nota

Come indicato nella sezione precedente, il rendering degli elementi di testo inline e dei valori tipografici non predefiniti non viene eseguito sul percorso rapido.

Elementi inline

Lo spazio dei nomi Microsoft.UI.Xaml.Documents fornisce una varietà di elementi di testo inline che è possibile usare per formattare il testo come Bold, Italic, Run, Span e LineBreak.

È possibile visualizzare una serie di stringhe in un controllo TextBlock, in cui ogni stringa ha una formattazione diversa. A tale scopo, è possibile usare un elemento Run per visualizzare ogni stringa con la relativa formattazione e separando ogni elemento Run con un elemento LineBreak.

Ecco come definire diverse stringhe di testo formattate in modo diverso in un TextBlock usando oggetti Run separati da un elemento LineBreak.

<TextBlock FontFamily="Segoe UI" Width="400" Text="Sample text formatting runs">
    <LineBreak/>
    <Run Foreground="Gray" FontFamily="Segoe UI Light" FontSize="24">
        Segoe UI Light 24
    </Run>
    <LineBreak/>
    <Run Foreground="Teal" FontFamily="Georgia" FontSize="18" FontStyle="Italic">
        Georgia Italic 18
    </Run>
    <LineBreak/>
    <Run Foreground="Black" FontFamily="Arial" FontSize="14" FontWeight="Bold">
        Arial Bold 14
    </Run>
</TextBlock>

Ecco il risultato.

Text formatted with run elements

Tipografia

Le proprietà associate della classe Typography consentono di accedere a un set di proprietà tipografiche Microsoft OpenType. È possibile impostare queste proprietà associate su TextBlock o su singoli elementi di testo inline. Questi esempi mostrano entrambi.

<TextBlock Text="Hello, world!"
           Typography.Capitals="SmallCaps"
           Typography.StylisticSet4="True"/>

TextBlock textBlock1 = new TextBlock();
textBlock1.Text = "Hello, world!";
Typography.SetCapitals(textBlock1, FontCapitals.SmallCaps);
Typography.SetStylisticSet4(textBlock1, true);

<TextBlock>12 x <Run Typography.Fraction="Slashed">1/3</Run> = 4.</TextBlock>

Scaricare il codice di esempio