带批注的滚动条可帮助用户轻松浏览大型项目集合。 它将替换默认滚动条，并且可与任何可滚动容器结合使用。 使用此垂直滚动条，用户可以上下滚动浏览集合中的项。 用户可以沿滚动条区域查看类别标签，以提供其集合中位置的视觉参考。 平移指示器（主题色线条）指示用户当前在集合中的位置。 当用户将鼠标悬停在滚动条区域时，将会显示工具提示。 此工具提示包含一个标签，可向用户提供有关其在集合中当前位置的详细信息。 滚动箭头位于滚动条区域的顶部和底部。 它们可以用来将当前位置按较小的增量进行移动
带批注滚动条可与 ItemsView 控件结合使用，以重新创建照片库体验。 类别标签可以设置为不同的年份，以帮助用户导航到其照片集合中的特定位置。
交互
悬停时，将会显示一个工具提示，以便预览该位置。 然后，用户可以单击以导航到该特定位置。 用户还可以单击并拖动滚动条区域中的任意位置，以导航到其集合中的新位置。 拖动时，平移指示器将附加到鼠标光标，内容则会滚动以反映新位置。 用户也可以使用鼠标滚轮来滚动浏览其集合。 上下滚动鼠标滚轮可移动其在集合中的位置，并按固定量向上或向下移动相应的平移指示器。
注释
与在 ScrollBar 控件中不同，你将无法单击并拖动滑块。 拇指是一个非交互式元素，仅用于可视化当前视口位置。 滑块具有固定高度，但该高度不代表视区高度。
标签行为
- 对于针对触摸输入而优化的体验，用户可以点击并按住滚动条区域以查看工具提示。 工具提示将被略微提升，使触屏用户更容易阅读。 点击和拖动滚动条区域的任意位置将类似于使用鼠标进行单击和拖动。
- 工具提示标签永远不会截断，因为它的目的是显示解释性文本。 相反，如果文本超过工具提示的最大宽度 360px，则文本会换行。
- 如果文本超过滚动条区域的宽度，则会剪裁类别标签。
- 如果两个类别标签之间发生冲突（例如，当窗口大小减小且两个标签相互重叠时），将会移除顶部标签。 作为此规则的例外，集合的第一个标签将始终保留，因为它有助于向用户指示集合的范围。 两个类别标签之间应始终至少留出 4px（上下各 2px），否则将触发标签冲突。
这是正确的控制吗？
建议在处理大型项目集合或预期发生大量滚动时使用带批注的滚动条，而不是默认滚动条。 带批注的滚动条将为用户提供一种简单的方法，以在集合中定位自己并遍历它。
对于仅包含少数项目或只需要少量滚动的集合，建议使用默认滚动条。
Recommendations
- 仅当向用户提供有用信息时，才添加类别标签
- 尽可能保持用于类别标签和工具提示的字符串简洁
- 如果垂直空间足够，最好使用带批注的滚动条。 在受限的垂直空间中使用带批注的滚动条会减少可见标签的数量
- 不要将使用带批注的滚动条作为用户在集合中定位自身的唯一方法。 建议在整个集合中使用粘滞标题或类别标签来补充带批注的滚动条。
创建带批注的滚动条
WinUI 3 示例库应用包含 WinUI 控件和功能的交互式示例。 从 Microsoft Store 或浏览 GitHub 上的源代码获取应用。
要使用 AnnotatedScrollBar，需要完成以下几个步骤：
- 将 AnnotatedScrollBar 连接到滚动容器。
- 将标签添加到滚动条。
- 添加详细信息标签（工具提示）。
将 AnnotatedScrollBar 连接到滚动容器
要使用 AnnotatedScrollBar，请通过 IScrollController 接口将其连接到可滚动容器。 AnnotatedScrollBar 可通过其 ScrollController 属性提供 IScroller 实现，而 ScrollView 会通过其 ScrollPresenter 属性（特别是 ScrollPresenter.VerticalScrollController）来使用它。
注释
ScrollView 控件内置了对使用 IScrollController 接口的支持。 对于其他滚动容器（如 ScrollViewer），必须编写适用于 IScrollController 的适配器。 请参阅本文后面的示例。
在这里，ItemsView 的 VerticalScrollController 属性已绑定到 AnnotatedScrollBar 的 ScrollController。 （ItemsView.VerticalScrollPresenter 属性传递给 ItemsView 内部 ScrollView 的 ScrollPresenter.VerticalScrollController 值。）
<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：显示标签内容的偏移量值。
标签（如果已指定）将始终在滚动条上可见，除非它们与其他标签发生冲突，或超出轨道边界。 （请参阅标签行为，以了解详细信息。）
标签偏移值的计算取决于应用的详细信息及其数据。 有关如何计算偏移量的一个示例，请参阅 GitHub 上的 WinUI 3 画廊示例。
详细信息标签
详细信息标签是当光标位于滚动条上时显示的工具提示元素。 要创建详细信息标签，请处理 DetailLabelRequested 事件。 事件参数提供了显示工具提示标签的 ScrollOffset。 使用此值可确定要为该位置显示的正确标签，并将标签设置为事件参数的 Content 属性。
滚动
用户可以通过单击滚动条顶部和底部的箭头按钮来滚动 AnnotatedScrollBar。 可以设置 SmallChange 属性以指定箭头按钮滚动内容的幅度。
可以处理 Scrolling 事件，以确定如何执行滚动、在发生滚动时执行操作或取消滚动操作。
获取示例代码
- WinUI 3 Gallery 示例 - 查看交互式格式的所有 XAML 控件。
