在 Avalonia 中，
ListBox默认是垂直滚动的，若要实现**水平滚动**，关键不是直接给
ListBox设置水平滚动，而是通过嵌套
ScrollViewer并控制其滚动方向，同时调整
ItemsPanel为水平布局（如
StackPanel或
WrapPanel横向排列）。
1. 设置 ListBox 的 ItemsPanel 为水平 StackPanel
默认
ListBox使用垂直
StackPanel，需显式替换为水平方向：
<ListBox>
<ListBox.ItemsPanel>
<ItemsPanelTemplate>
<StackPanel Orientation="Horizontal"/>
</ItemsPanelTemplate>
</ListBox.ItemsPanel>
<!-- ItemTemplate 和 ItemsSource 略 -->
</ListBox>2. 包裹 ScrollViewer 并启用水平滚动
ListBox本身不直接暴露
HorizontalScrollBarVisibility属性，需用
ScrollViewer显式包裹，并设置其行为：
<ScrollViewer HorizontalScrollBarVisibility="Auto" VerticalScrollBarVisibility="Disabled">
<ListBox>
<ListBox.ItemsPanel>
<ItemsPanelTemplate>
<StackPanel Orientation="Horizontal"/>
</ItemsPanelTemplate>
</ListBox.ItemsPanel>
</ListBox>
</ScrollViewer>注意：
-
VerticalScrollBarVisibility="Disabled"防止出现双滚动条；
-
HorizontalScrollBarVisibility可设为
Auto、
Visible或
Hidden；
-
ScrollViewer必须放在
ListBox外层（不能放 inside
ControlTemplate除非重写模板）。
3. 可选：优化项宽与换行（避免单行过长）
若希望内容自动换行或限制宽度，可用
WrapPanel替代
StackPanel，并设置
ItemWidth或容器约束： 用
WrapPanel+
Orientation="Horizontal"实现“横向优先、自动折行” 为每个
ListBoxItem设置固定
Width或使用
MaxWidth防止撑开 确保外层
ScrollViewer宽度受限（如父容器有固定宽或
HorizontalAlignment="Stretch"）
4. 注意事项与常见问题
以下细节容易被忽略，但直接影响效果：
ListBox默认有内边距和项间距，可能干扰滚动范围 —— 检查
Padding和
ItemContainerStyle中的
Margin若滚动条不出现，请确认内容总宽度确实超出
ScrollViewer可视区域（可临时加
Background="Red"查看实际尺寸） Avalonia 11+ 支持
ScrollViewer.CanHorizontallyScroll绑定，但通常无需手动设，由内容自动判断 自定义
ControlTemplate时，确保模板中保留
ScrollViewer且正确命名 PART_ScrollViewer
不复杂但容易忽略的是：必须同时满足「水平布局」+「外层 ScrollViewer」+「内容超宽」三个条件，缺一不可。直接在 ListBox 上设 ScrollBarVisibility 是无效的。
