在 Avalonia 中实现 ListBox 水平滚动，需同时满足三个条件：1. 设置 ItemsPanel 为水平 StackPanel 或 WrapPanel；2. 用 ScrollViewer 外层包裹并设 HorizontalScrollBarVisibility="Auto"、VerticalScrollBarVisibility="Disabled"；3. 确保内容总宽度超出 ScrollViewer 可视区域。

在 Avalonia 中，ListBox 默认是垂直滚动的，若要实现**水平滚动**，关键不是直接给 ListBox 设置水平滚动，而是通过嵌套 ScrollViewer 并控制其滚动方向，同时调整 ItemsPanel 为水平布局（如 StackPanel 或 WrapPanel 横向排列）。

1. 设置 ListBox 的 ItemsPanel 为水平 StackPanel

默认 ListBox 使用垂直 StackPanel，需显式替换为水平方向：

2. 包裹 ScrollViewer 并启用水平滚动

ListBox 本身不直接暴露 HorizontalScrollBarVisibility 属性，需用 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 是无效的。