IItemsPanelTemplate模版

一、先搞懂：它到底是什么？

一句话核心定义

ItemsPanelTemplate = 列表控件的「布局容器」

大白话解释

WPF 里所有列表控件（ListBox/ListView/ComboBox/ItemsControl）：

• ItemTemplate：决定每一项长什么样（数据模板）
• ItemsPanelTemplate：决定这些项怎么排列、放在哪里（布局模板）

官方作用

• 用来指定 ItemsControl 如何排列其子项
• 默认是 垂直 StackPanel
• 你可以替换成：水平排列、网格排列、环绕排列、自定义面板...

最重要的区别（必记）

• DataTemplate：管项的内容（头像、文字、按钮）
• ItemsPanelTemplate：管项的布局（横着排、竖着排、网格排、环绕排）

二、核心语法（超级简单）

<ListBox>
    <ListBox.ItemsPanel>
        <ItemsPanelTemplate>
            <!-- 这里写布局控件：StackPanel/WrapPanel/Grid/UniformGrid -->
        </ItemsPanelTemplate>
    </ListBox.ItemsPanel>
</ListBox>

里面只能放一个布局面板，不能放其他控件。

三、默认布局是什么？

所有列表控件默认布局都是：

<ItemsPanelTemplate>
    <StackPanel Orientation="Vertical"/>
</ItemsPanelTemplate>

所以默认从上到下垂直排列。

四、实战示例 1：水平排列 ListBox（最常用）

把默认垂直 → 水平滚动 / 水平排列

<ListBox>
    <!-- 修改项布局面板 -->
    <ListBox.ItemsPanel>
        <ItemsPanelTemplate>
            <StackPanel Orientation="Horizontal"/>
        </ItemsPanelTemplate>
    </ListBox.ItemsPanel>

    <!-- 列表项 -->
    <ListBoxItem>项目 1</ListBoxItem>
    <ListBoxItem>项目 2</ListBoxItem>
    <ListBoxItem>项目 3</ListBoxItem>
</ListBox>

效果

所有项 从左到右横着排

 

五、实战示例 2：流式布局（自动换行 WrapPanel）

项目中超级常用，比如图片列表、标签列表、商品流

<ListBox>
    <ListBox.ItemsPanel>
        <ItemsPanelTemplate>
            <!-- 自动换行面板 -->
            <WrapPanel/>
        </ItemsPanelTemplate>
    </ListBox.ItemsPanel>

    <ListBoxItem Width="100" Height="100" Margin="5">项目 1</ListBoxItem>
    <ListBoxItem Width="100" Height="100" Margin="5">项目 2</ListBoxItem>
    <ListBoxItem Width="100" Height="100" Margin="5">项目 3</ListBoxItem>
    <ListBoxItem Width="100" Height="100" Margin="5">项目 4</ListBoxItem>
</ListBox>

效果

• 一行排不下
• 自动换到下一行
• 完美流式布局

六、实战示例 3：网格布局 UniformGrid

自动等分网格，适合相册、宫格布局

<ListBox>
    <ListBox.ItemsPanel>
        <ItemsPanelTemplate>
            <!-- 每行 3 个，自动分行 -->
            <UniformGrid Columns="3" Rows="0"/>
        </ItemsPanelTemplate>
    </ListBox.ItemsPanel>

    <ListBoxItem>1</ListBoxItem>
    <ListBoxItem>2</ListBoxItem>
    <ListBoxItem>3</ListBoxItem>
    <ListBoxItem>4</ListBoxItem>
    <ListBoxItem>5</ListBoxItem>
    <ListBoxItem>6</ListBoxItem>
</ListBox>

效果

• 严格 3 列网格
• 自动等分宽度、高度
• 适合做九宫格、相册、图标面板

七、实战示例 4：结合 DataTemplate（真实项目用法）

真实项目一定是：
数据绑定 + 项模板 + 布局面板 一起用

步骤 1：准备数据类

public class Product
{
    public string Name { get; set; }
    public double Price { get; set; }
}

步骤 2：窗口加载数据

public MainWindow()
{
    InitializeComponent();
    listBox.ItemsSource = new List<Product>
    {
        new Product{Name="商品1", Price=99},
        new Product{Name="商品2", Price=199},
        new Product{Name="商品3", Price=299},
        new Product{Name="商品4", Price=399},
    };
}

步骤 3：XAML 完整代码（可直接复制运行）

<ListBox x:Name="listBox">

    <!-- 1. ItemsPanel：布局方式（流式换行） -->
    <ListBox.ItemsPanel>
        <ItemsPanelTemplate>
            <WrapPanel/>
        </ItemsPanelTemplate>
    </ListBox.ItemsPanel>

    <!-- 2. ItemTemplate：每一项长什么样 -->
    <ListBox.ItemTemplate>
        <DataTemplate>
            <Border Width="150" Height="100" Background="LightBlue" Margin="5">
                <StackPanel>
                    <TextBlock Text="{Binding Name}" FontSize="18"/>
                    <TextBlock Text="{Binding Price}" Foreground="Red"/>
                </StackPanel>
            </Border>
        </DataTemplate>
    </ListBox.ItemTemplate>

</ListBox>

最终效果

• 流式自动换行布局
• 每个商品展示名称 + 价格
• 标准商城商品列表

八、可以用哪些布局面板？

你几乎可以用 WPF 所有布局：

• StackPanel（水平 / 垂直）
• WrapPanel（流式自动换行）
• UniformGrid（宫格）
• Grid（自定义网格）
• DockPanel
• 第三方布局 / 自定义布局

九、最关键的一张总结图

模板    作用    管什么
ControlTemplate    控件外观    控件本身长啥样
DataTemplate    数据呈现    每一项内容长啥样
ItemsPanelTemplate    项布局    所有项怎么排列

终极口诀

内容看 DataTemplate，排列看 ItemsPanelTemplate！

十、必须记住的 4 个要点

1. 只用于列表控件：ListBox/ListView/ItemsControl/ComboBox
2. 里面只能放布局面板
3. 默认是垂直 StackPanel
4. 和 DataTemplate 配合使用，构成完整列表