Kommenterad rullningslistkontroll

En kommenterad rullningslist hjälper användarna att enkelt navigera genom en stor samling objekt. Den ersätter standardrullningslisten och kan användas tillsammans med valfri rullningsbar container. Med den här lodräta rullningslisten kan användarna rulla upp och ned genom objekten i en samling. Användare kan se kategorietiketter längs rullningslistområdet för att ge en visuell referens till var de befinner sig i sin samling. En panoreringsindikator (dekorfärgad linje) anger användarens aktuella position i samlingen. En knappbeskrivning visas när en användare för muspekaren över rullningslistan. Den här knappbeskrivningen innehåller en etikett för att ge användaren mer information om deras aktuella position i samlingen. Rullningspilar finns längst upp och ned i rullningslistområdet. De kan användas för att flytta den aktuella positionen med en liten ökning

Den kommenterade rullningslisten kan användas tillsammans med en ItemsView-kontroll för att återskapa en bildgalleriupplevelse. Kategorietiketterna kan ställas in på olika år för att hjälpa användare att navigera till en specifik plats i sin fotosamling.

Interaktioner

Vid hovring visas ett verktygstips för att visa en förhandsvisning av platsen. Användarna kan sedan klicka för att navigera till den specifika platsen. Användarna kan också klicka och dra var som helst i rullningslistområdet för att navigera till en ny position i samlingen. När de drar förblir panoreringsindikatorn kopplad till musmarkören och innehållet rullar för att återspegla den nya positionen. Användare kan också bläddra igenom sin samling med hjälp av mushjulet. Om du rullar upp eller ned på mushjulet flyttas deras position i samlingen och motsvarande panoreringsindikator uppåt eller nedåt med en fast mängd.

Etikettbeteende

• För upplevelser som är optimerade för pekinmatning kan användarna trycka och hålla ned på rullningsområdet för att se verktygstipset. Verktygstipset kommer att bli något högre placerad för att göra det lättare att läsa för pekskärmsanvändare. Om du trycker och drar var som helst i rullningslistområdet fungerar det på samma sätt som när du klickar och drar med musen.
• Knappbeskrivningsetiketten trunkeras aldrig eftersom syftet är att visa text som är förklarande. I stället omsluts texten om den går över knappbeskrivningens maximala bredd på 360 px.
• Kategorietiketter klipps bort om texten är längre än bredden på rullningslistens område.
• När det uppstår en kollision mellan två kategorietiketter (till exempel när fönsterstorleken minskar och två etiketter överlappar varandra) tas den översta etiketten bort. Som ett undantag till den här regeln behålls alltid samlingens första etikett eftersom den hjälper till att ange samlingens intervall för användarna. Kategorietiketter ska alltid ha minst 4 px (2 px ovan, 2 px nedan) däremellan, annars utlöses en etikettkollision.

Är det här rätt kontroll?

Vi rekommenderar att du använder en kommenterad rullningslist i stället för en standardrullningslist när du hanterar en stor samling objekt eller när en stor mängd rullning förväntas. Den kommenterade rullningslisten ger ett enkelt sätt för användare att hitta sig själva i sin samling och bläddra igenom den.

För samlingar som bara har ett fåtal objekt eller som bara kräver en liten mängd rullning rekommenderar vi att du använder en standardrullningslist.

Recommendations

• Lägg bara till en kategorietikett om den ger användbar information till användare
• Behåll de strängar som används för kategorietiketterna och knappbeskrivningen så koncisa som möjligt
• Den kommenterade rullningslisten används bäst när det finns tillräckligt med lodrätt utrymme. Om du använder den kommenterade rullningslisten i ett begränsat lodrätt utrymme minskar antalet synliga etiketter
• Använd inte den kommenterade rullningslisten som det enda sättet för användare att hitta sig själva i en samling. Vi rekommenderar att du använder kladdiga rubriker eller kategorietiketter i hela samlingen för att komplettera den kommenterade rullningslisten.

Skapa en kommenterad rullningslist

WinUI 3-galleriappen innehåller interaktiva exempel på WinUI-kontroller och funktioner. Hämta appen från Microsoft Store eller bläddra i källkoden på GitHub.

Om du vill använda en AnnotatedScrollBar måste du utföra flera steg:

• Anslut AnnotatedScrollBar till en rullningscontainer.
• Lägg till etiketter i rullningslisten.
• Lägg till informationsetiketter (verktygstips).

Ansluta AnnotatedScrollBar till en rullningscontainer

Om du vill använda en AnnotatedScrollBar ansluter du den till en rullningsbar container via gränssnittet IScrollController . AnnotatedScrollBar tillhandahåller en IScrollController-implementering via dess ScrollController-egenskap , medan ScrollView använder den via egenskapen ScrollPresenter (specifikt ScrollPresenter.VerticalScrollController).

Här är egenskapen VerticalScrollController för en ItemsView bunden till ScrollController för en AnnotatedScrollBar. Egenskapen ItemsView.VerticalScrollPresenter skickas vidare till ScrollPresenter.VerticalScrollController-värdet för ItemsViews interna ScrollView.

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

Du kan också ansluta dem i kod, som du ser här. I det här exemplet används en ScrollView för att omsluta en ItemsRepeater och tillhandahålla rullningsfunktioner för den. AnnotatedScrollBar ersätter ScrollViews standardrullningslist.

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

Etiketter

AnnotatedScrollBar kan visa två typer av etiketter, som båda är valfria.

Kategorietiketter

Du lägger till etiketter genom att fylla i samlingen Etiketter . Varje etikett representeras av klassen AnnotatedScrollBarLabel och kräver två typer av information:

• Innehåll: Innehållet som visas i rullningslisten.
• ScrollOffset: Förskjutningsvärdet som etikettinnehållet visas med.

Etiketter (om de anges) visas alltid på rullningslisten, såvida de inte kolliderar med andra etiketter eller sträcker sig förbi rälsens gränser. (Mer information finns i Etikettbeteende .)

Beräkningen av etikettförskjutningsvärdet beror på informationen om din app och dess data. Ett exempel på hur förskjutningen kan beräknas finns i galleriexemplet WinUI 3 på GitHub.

Detaljetiketter

En detaljetikett är ett knappbeskrivningselement som visas när markören är över rullningslisten. Om du vill skapa en informationsetikett hanterar du händelsen DetailLabelRequested . Händelseargumenten tillhandahåller ScrollOffset där verktygstipsetiketten kommer att visas. Använd det här värdet för att fastställa rätt etikett för att visa för den positionen och ange etiketten som egenskapen Innehåll för händelsen args.

Rullning

Användaren kan bläddra i AnnotatedScrollBar genom att klicka på pilknapparna längst upp och ned i rullningslisten. Du kan ange egenskapen SmallChange för att ange hur mycket pilknapparna ska rulla innehållet med.

Du kan hantera rullningshändelsen för att avgöra hur rullningen utförs, vidta en åtgärd när rullning sker eller för att avbryta rullningsåtgärden.

Hämta exempelkoden

• WinUI 3-galleriexempel – Se alla XAML-kontroller i ett interaktivt format.

Relaterade ämnen

• ScrollView-klass