Аннотированный элемент управления полосой прокрутки

Аннотированная полоса прокрутки помогает пользователям легко перемещаться по большой коллекции элементов. Он заменяет полосу прокрутки по умолчанию и может использоваться в сочетании с любым прокручиваемым контейнером. Эта вертикальная полоса прокрутки позволяет пользователям прокручивать вверх и вниз по элементам в коллекции. Пользователи могут видеть метки категорий вдоль области полосы прокрутки, чтобы предоставить визуальную ссылку на то, где они находятся в своей коллекции. Индикатор сдвига (линия акцентного цвета) указывает текущее положение пользователя в коллекции. Подсказка отображается при наведении указателя мыши на область полосы прокрутки. Эта подсказка содержит метку, чтобы предоставить пользователю дополнительные сведения о текущей позиции в коллекции. Стрелки прокрутки расположены в верхней и нижней части области полосы прокрутки. Их можно использовать для перемещения текущей позиции небольшим шагом

Снимок экрана, на котором показана аннотированная полоса прокрутки в приложении

Аннотированная полоса прокрутки может использоваться вместе с элементом управления ItemsView для повторного создания интерфейса коллекции фотографий. Метки категорий можно задать на определенные годы, чтобы пользователи могли переходить к определенному моменту времени в коллекции фотографий.

Взаимодействия

При наведении указателя появляется подсказка с предварительным просмотром этого места. Затем пользователи могут нажать, чтобы перейти к этому определённому местоположению. Пользователи также могут щелкнуть и перетащить его в любое место в области полосы прокрутки, чтобы перейти к новой позиции в коллекции. По мере перетаскивания индикатор сдвига остается прикрепленным к курсору мыши, а содержимое прокручивается, чтобы отразить новую позицию. Пользователи также могут прокручивать свою коллекцию с помощью колесика мыши. Прокрутка вверх или вниз на колесике мыши перемещает их положение в коллекции и соответствующий индикатор перемещения вверх или вниз на фиксированное расстояние.

Замечание

В отличие от элемента управления ScrollBar , вы не можете щелкнуть и перетащить пальцем. Большой палец — это неинтерактивный элемент, который предназначен только для визуализации текущей позиции окна просмотра. Большой палец имеет фиксированную высоту, которая не является представителем высоты окна просмотра.

Поведение меток

Для возможностей, оптимизированных для сенсорного ввода, пользователи могут касаться и удерживать область прокрутки, чтобы увидеть подсказку. Подсказка будет немного выше, чтобы упростить чтение пользователями сенсорных экранов. Касание и перетаскивание в любом месте области полосы прокрутки будет работать аналогично щелчку и перетаскиванию с помощью мыши.
Метка подсказки никогда не усечена, так как ее цель заключается в отображении текста, объясняющего. Вместо этого текст переносится на новую строку, если его ширина превышает максимальную ширину подсказки в 360px.
Метки категорий обрезаются, если текст больше ширины области полосы прокрутки.
Если между двумя метками категорий возникает столкновение (например, когда размер окна уменьшается, а две метки перекрываются друг друга), верхняя метка удаляется. В качестве исключения из этого правила первая метка коллекции всегда хранится, так как она помогает указать диапазон коллекции для пользователей. Метки категорий всегда должны иметь не менее 4px (2px выше, 2px ниже) между ними, в противном случае активируется столкновение меток.

Это правильный контроль?

Рекомендуется использовать аннотированную полосу прокрутки, а не полосу прокрутки по умолчанию, при работе с большой коллекцией элементов или когда ожидается большое количество прокрутки. Аннотированная полоса прокрутки позволит пользователям легко ориентироваться в своей коллекции и перемещаться по ней.

Для коллекций с несколькими элементами или для которых требуется только небольшое количество прокрутки, рекомендуется использовать полосу прокрутки по умолчанию.

Recommendations

Добавить метку категории только в том случае, если она предоставляет полезные сведения пользователям
Сохраняйте строки, используемые для меток категорий и всплывающих подсказок, как можно более краткими
Аннотированная полоса прокрутки лучше всего используется, если достаточно вертикального пространства. Использование аннотированной полосы прокрутки в ограниченном вертикальном пространстве уменьшит количество видимых меток
Не используйте аннотированную полосу прокрутки в качестве единственного способа, чтобы пользователи нашли себя в коллекции. Мы рекомендуем использовать липкие заголовки или метки категорий во всей коллекции, чтобы дополнить аннотированную полосу прокрутки.

Создать аннотированную полосу прокрутки

Важные API:класс AnnotatedScrollBar, класс ScrollView, интерфейс IScrollController

Откройте приложение WinUI 3 Gallery и понаблюдайте за AnnotatedScrollBar в действии

Приложение WinUI 3 Gallery содержит интерактивные примеры элементов управления и функций WinUI. Получите приложение из Microsoft Store или просмотрите исходный код GitHub.

Чтобы использовать AnnotatedScrollBar, необходимо выполнить несколько действий:

Подключите AnnotatedScrollBar к контейнеру прокрутки.
Добавьте метки на полосу прокрутки.
Добавьте детализированные метки (подсказки).

Подключение AnnotatedScrollBar к контейнеру прокрутки

Чтобы использовать AnnotatedScrollBar, подключите его к прокручиваемому контейнеру через интерфейс IScrollController . AnnotatedScrollBar предоставляет реализацию IScrollController через его свойство ScrollController , а ScrollView использует его через его свойство ScrollPresenter (в частности, ScrollPresenter.VerticalScrollController).

Замечание

Элемент управления ScrollView имеет встроенную поддержку использования интерфейса IScrollController. Для других контейнеров прокрутки, таких как ScrollViewer, необходимо написать адаптер для IScrollController. См. пример далее в этой статье.

Здесь свойство VerticalScrollController объекта ItemsView связано с ScrollController объекта AnnotatedScrollBar. Свойство ItemsView.VerticalScrollPresenter передается в значение свойства ScrollPresenter.VerticalScrollController внутреннего элемента ScrollView.

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

Вы также можете связать их в коде, как показано здесь. В этом примере ScrollView используется для обёртывания ItemsRepeater и предоставления функции прокрутки. AnnotatedScrollBar заменяет полосу прокрутки 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;
}

Наклейки

AnnotatedScrollBar может отображать два типа меток, оба из которых являются необязательными.

Подписи категорий

Вы добавляете метки, заполняя коллекцию меток . Каждая метка представлена классом AnnotatedScrollBarLabel и требует двух частей информации:

Содержимое: содержимое, отображаемое на полосе прокрутки.
ScrollOffset: значение смещения, по которому отображается содержимое метки.

Метки (если они указаны) всегда отображаются на полосе прокрутки, если они не сталкиваются с другими метками или не расширяют границы рельса. (См. Поведение меток для получения дополнительных сведений.)

Вычисление значения смещения метки зависит от сведений о приложении и его данных. Пример того, как может быть вычислено смещение, можно найти в примере коллекции WinUI 3 на GitHub.

Метки деталей

Детальная метка — это элемент подсказки, который отображается, когда курсор находится над полосой прокрутки. Чтобы создать детальную метку, нужно обработать событие DetailLabelRequested. Аргументы событий предоставляют ScrollOffset , где будет отображаться метка подсказки. Используйте это значение, чтобы определить правильную метку, которую следует отобразить для этой позиции, и установите метку как свойство Content аргументов события.

Прокрутка

Пользователь может прокручивать annotatedScrollBar, щелкнув кнопки со стрелками в верхней и нижней части полосы прокрутки. Можно задать свойство SmallChange , чтобы указать объем, по которому кнопки со стрелками прокручивают содержимое.

Можно обработать событие прокрутки , чтобы определить, как выполняется прокрутка, выполнить действие при прокрутке или отменить действие прокрутки.

Получите пример кода

WinUI 3 Gallery sample — просмотр всех элементов управления XAML в интерактивном формате.

Класс ScrollView

Кері байланыс

Бет пайдалы болды ма?

Last updated on 2025-11-25