Controllo barra di scorrimento con annotazioni

Una barra di scorrimento con annotazioni consente agli utenti di spostarsi facilmente in un'ampia raccolta di elementi. Sostituisce la barra di scorrimento predefinita e può essere usata insieme a qualsiasi contenitore scorrevole. Questa barra di scorrimento verticale consente agli utenti di scorrere verso l'alto e verso il basso gli elementi di una raccolta. Gli utenti possono visualizzare le etichette di categoria lungo l'area della barra di scorrimento per fornire un riferimento visivo di dove si trovano all'interno della raccolta. Un indicatore di scorrimento (linea colorata in evidenza) indica la posizione corrente dell'utente nella raccolta. Un suggerimento viene visualizzato quando un utente passa il mouse nell'area della barra di scorrimento. Questo tooltip contiene un'indicazione per fornire ulteriori informazioni all'utente sulla loro posizione corrente nella raccolta. Le frecce di scorrimento si trovano nella parte superiore e inferiore dell'area della barra di scorrimento. Possono essere usati per spostare la posizione corrente con un piccolo incremento

La barra di scorrimento con annotazioni può essere usata insieme a un controllo ItemsView per ricreare un'esperienza da galleria fotografica. Le etichette di categoria possono essere impostate su anni diversi per consentire agli utenti di passare a una posizione specifica all'interno della raccolta di foto.

Interazioni

Al passaggio del mouse, viene visualizzata una descrizione comando per visualizzare un'anteprima di tale posizione. Gli utenti possono quindi fare clic per passare a quella posizione specifica. Gli utenti possono anche fare clic e trascinare in un punto qualsiasi dell'area della barra di scorrimento per passare a una nuova posizione all'interno della raccolta. Durante il trascinamento, l'indicatore di panoramica rimane collegato al cursore del mouse e il contenuto scorre per riflettere la nuova posizione. Gli utenti possono anche scorrere la raccolta usando la rotellina del mouse. Lo scorrimento verso l'alto o verso il basso sulla rotellina del mouse sposta la posizione nella raccolta e l'indicatore di panoramica corrispondente verso l'alto o verso il basso di un importo fisso.

Comportamento delle etichette

• Per esperienze ottimizzate per il tocco, gli utenti possono toccare e tenere premuto nell'area della barra di scorrimento per visualizzare il tooltip. Il tooltip sarà leggermente più elevato per semplificare la lettura agli utenti touch. Il tocco e il trascinamento in qualsiasi punto dell'area della barra di scorrimento funzioneranno in modo analogo a un clic e trascinamento con il mouse.
• L'etichetta del tooltip non viene mai troncata perché il suo scopo è visualizzare testo esplicativo. Il testo viene invece sottoposto a wrapping se supera la larghezza massima della descrizione comando di 360px.
• Le etichette delle categorie vengono troncate se il testo è più lungo della larghezza dell'area della barra di scorrimento.
• Quando si verifica un conflitto tra due etichette di categoria(ad esempio, quando le dimensioni della finestra diminuiscono e due etichette si sovrappongono tra loro), l'etichetta superiore viene rimossa. Come eccezione a questa regola, la prima etichetta della raccolta viene sempre mantenuta perché consente di indicare l'intervallo della raccolta agli utenti. Le etichette di categoria devono avere sempre un minimo di 4 px (2 px sopra, 2 px inferiore) tra di loro, altrimenti viene attivato un conflitto di etichette.

Questo è il controllo giusto?

È consigliabile usare una barra di scorrimento con annotazioni, anziché una barra di scorrimento predefinita, quando si tratta di una raccolta di elementi di grandi dimensioni o quando è prevista una grande quantità di scorrimento. La barra di scorrimento con annotazioni fornirà agli utenti un modo semplice per individuarsi nella raccolta e attraversarla.

Per le raccolte con solo alcuni elementi o che richiedono solo una piccola quantità di scorrimento, è consigliabile usare una barra di scorrimento predefinita.

Recommendations

• Aggiungere un'etichetta di categoria solo se fornisce informazioni utili agli utenti
• Mantenere le stringhe usate per le etichette di categoria e il tooltip il più concise possibile.
• La barra di scorrimento con annotazioni viene usata meglio quando è disponibile spazio verticale sufficiente. L'uso della barra di scorrimento con annotazioni in uno spazio verticale limitato ridurrà il numero di etichette visibili
• Non usare la barra di scorrimento con annotazioni come unico modo per consentire agli utenti di individuarsi all'interno di una raccolta. È consigliabile usare intestazioni permanenti o etichette di categoria in tutta la raccolta per integrare la barra di scorrimento con annotazioni.

Creare una barra di scorrimento con annotazioni

L'app Raccolta WinUI 3 include esempi interattivi di controlli e funzionalità WinUI. Ottenere l'app dal Microsoft Store o esplorare il codice sorgente in GitHub.

Per usare un oggetto AnnotatedScrollBar, è necessario completare diversi passaggi:

• Connetti AnnotatedScrollBar a un contenitore di scorrimento.
• Aggiungere etichette alla barra di scorrimento.
• Aggiungere etichette di dettaglio (suggerimenti).

Connetti l'AnnotatedScrollBar a un contenitore di scorrimento

Per utilizzare un AnnotatedScrollBar, connetterlo a un contenitore scorrevole tramite l'interfaccia IScrollController. AnnotatedScrollBar fornisce un'implementazione IScrollController tramite la relativa proprietà ScrollController, mentre ScrollView lo utilizza tramite la relativa proprietà ScrollPresenter (in particolare ScrollPresenter.VerticalScrollController).

In questo caso, la proprietà VerticalScrollController di un oggetto ItemsView è associata a ScrollController di un oggetto AnnotatedScrollBar. La proprietà ItemsView.VerticalScrollPresenter viene passata al valore ScrollPresenter.VerticalScrollController dell'oggetto ScrollView interno di ItemsView.

<Grid ColumnDefinitions="*,Auto">
    <ItemsView VerticalScrollController="{x:Bind annotatedScrollBar.ScrollController}"/>
    <AnnotatedScrollBar x:Name="annotatedScrollBar" Grid.Column="1"/>
</Grid>

Puoi anche collegarli in codice, come mostrato qui. In questo esempio viene utilizzato uno ScrollView per incapsulare un ItemsRepeater e fornire funzionalità di scorrimento. AnnotatedScrollBar sostituisce la barra di scorrimento predefinita di ScrollView.

<Grid ColumnDefinitions="*, Auto">
    <ScrollView x:Name="scrollView"
                Background="LightGray" 
                MaxWidth="800" MaxHeight="500"
                VerticalScrollBarVisibility="Hidden">
        <ItemsRepeater x:Name="itemsRepeater"
                ItemsSource="{x:Bind ColorCollection}"
                Margin="2"
                SizeChanged="ItemsRepeater_SizeChanged">
            <ItemsRepeater.Layout>
                <UniformGridLayout/>
            </ItemsRepeater.Layout>
            <ItemsRepeater.ItemTemplate>
                <DataTemplate x:DataType="media:SolidColorBrush">
                    <Grid Background="{x:Bind}" Width="112" Height="82" 
                          CornerRadius="4" Margin="4"/>
                </DataTemplate>
            </ItemsRepeater.ItemTemplate>
        </ItemsRepeater>
    </ScrollView>
                
    <AnnotatedScrollBar x:Name="annotatedScrollBar" Grid.Column="1"
        Margin="4,0,48,0" MaxHeight="500" HorizontalAlignment="Right"
        DetailLabelRequested="AnnotatedScrollBar_DetailLabelRequested"/>
</Grid>

private void AnnotatedScrollBarPage_Loaded(object sender, Microsoft.UI.Xaml.RoutedEventArgs e)
{
    scrollView.ScrollPresenter.VerticalScrollController = annotatedScrollBar.ScrollController;
}

Etichette

AnnotatedScrollBar può visualizzare due tipi di etichette, entrambe facoltative.

Etichette categoria

È possibile aggiungere etichette popolando l'insieme Labels . Ogni etichetta è rappresentata dalla classe AnnotatedScrollBarLabel e richiede due informazioni:

• Contenuto: contenuto visualizzato sulla barra di scorrimento.
• ScrollOffset: valore di offset in corrispondenza del quale viene visualizzato il contenuto dell'etichetta.

Le etichette (se specificate) sono sempre visibili sulla barra di scorrimento, a meno che non si scontrano con altre etichette o si estendano oltre i limiti della barra. (Vedere Comportamento delle etichette per altre info.

Il calcolo del valore di offset dell'etichetta dipende dai dettagli dell'app e dai relativi dati. Per un esempio di come calcolare l'offset, vedere l'esempio di WinUI 3 Gallery su GitHub.

Etichette dettagli

Un'etichetta dettagliata è un elemento suggerimento visualizzato quando il cursore si trova sulla barra di scorrimento. Per creare un'etichetta di dettaglio, si gestisce l'evento DetailLabelRequested . Gli argomenti dell'evento indicano il ScrollOffset in cui verrà visualizzata l'etichetta tooltip. Usare questo valore per determinare l'etichetta corretta da visualizzare per tale posizione e impostare l'etichetta come proprietà Content degli argomenti di evento.

Scorrimento

L'utente può scorrere annotatedScrollBar facendo clic sui pulsanti freccia nella parte superiore e inferiore della barra di scorrimento. È possibile impostare la proprietà SmallChange per specificare la quantità in base alla quale i pulsanti freccia scorrono il contenuto.

È possibile gestire l'evento Scrolling per determinare la modalità di esecuzione dello scorrimento, eseguire un'azione durante lo scorrimento o annullare l'azione di scorrimento.

Scaricare il codice di esempio

• Galleria di esempi di WinUI 3 - Vedi tutti i controlli XAML in un formato interattivo.

Argomenti correlati

• Classe ScrollView