Ant Design Blazor 栅格列表(Grid List)完全指南:从基础配置到响应式布局源码解析
Ant Design Blazor 栅格列表(Grid List)完全指南:从基础配置到响应式布局源码解析
AntList 的 grid 属性让列表从"垂直堆叠"切换为"多列栅格"布局,是 Ant Design Blazor 组件库中最常用的数据展示布局手段之一。本指南以 栅格列表演示文档 为核心,结合组件源码完整讲解 ListGridType 的每个配置项、栅格列表的渲染原理、以及响应式栅格列表的断点适配方案,读完即可在真实项目中直接落地使用。
什么是栅格列表
栅格列表(Grid List)指的是通过设置 List 的 grid 属性,将列表项按指定的列数(column)进行多列排布,并可在列之间设置间距(gutter)的一种列表形态。它非常适合卡片化内容的展示场景——例如产品卡片、图片画廊、报表入口等——在有限的屏幕宽度内尽可能多地展示信息。
在 Ant Design Blazor 中,栅格列表的入口非常简单:给 AntList 组件绑定一个 ListGridType 类型的 Grid 参数即可:
<AntList Grid="grid" DataSource="@Data">
<ListItem>
<Card Bordered Title="@(context.Title)">
<Body>
Card context
</Body>
</Card>
</ListItem>
</AntList>
@code {
public ListGridType grid = new ListGridType { Gutter = 16, Column = 4 };
public List<BasicItem> Data = new List<BasicItem>
{
new BasicItem { Title = "Title 1"},
new BasicItem { Title = "Title 2"},
new BasicItem { Title = "Title 3"},
new BasicItem { Title = "Title 4"},
};
public class BasicItem
{
public string Title { get; set; }
}
}
上述示例(源码见 Grid.razor)展示了栅格列表的最小完整用法:设置 Gutter = 16(列间距 16px)、Column = 4(固定 4 列),然后在 ListItem 中使用 context 接收 DataSource 中当前迭代的每一项,渲染成卡片。数据、子项模板、栅格配置三者共同构成了一个可运行的栅格列表。
ListGridType 全部配置项详解
Grid 参数的类型是 ListGridType,其属性定义如下:
| 属性 | 类型 | 说明 |
|---|---|---|
Gutter |
int |
列与列之间的间距(单位 px) |
Column |
int |
期望显示的固定列数 |
Xs |
int |
视口宽度 < 576px 时的列数 |
Sm |
int |
视口宽度 ≥ 576px 时的列数 |
Md |
int |
视口宽度 ≥ 768px 时的列数 |
Lg |
int |
视口宽度 ≥ 992px 时的列数 |
Xl |
int |
视口宽度 ≥ 1200px 时的列数 |
Xxl |
int |
视口宽度 ≥ 1600px 时的列数 |
其中 Column 与 Xs ~ Xxl 的关系可以这样理解:
Column是静态基准列数:设置后列表在所有屏幕尺寸下都固定按此列数渲染,实现"期望显示的列数";Xs~Xxl是响应式列数:一旦设置了这些断点列数,组件会监听视口变化,根据当前屏幕宽度自动切换列数,从而实现响应式栅格列表。
响应式属性对应的断点取值与组件库的 BreakpointType 枚举完全一致(见 BreakpointType.cs:Xs = 480、Sm = 576、Md = 768、Lg = 992、Xl = 1200、Xxl = 1600),这也印证了文档中"尺寸与 Layout Grid 保持一致"的说法(参见 响应式演示文档)。
使用提示:若同时设置
Column与响应式断点列数,OnInitialized阶段会先用Column计算初始列宽,随后OnBreakpoint回调会依据当前断点覆盖列数(详见下文源码解析)。因此在响应式场景中,建议只使用Xs~Xxl系列属性,避免两种模式互相干扰。
固定列数栅格列表:Gutter 与 Column 实战
固定列数模式是最常用的形态。只需要关注两个属性:
Column:决定一行显示几列,同时决定每一项的宽度。组件内部会将列宽计算为100 / Column的百分比,例如Column = 4时每项宽度为 25%;Gutter:决定列之间的水平间距,由底层Row组件负责通过负 margin + padding 的方式实现视觉上的等间距效果。
在栅格模式下,AntList 内部不再渲染普通的 <ul class="ant-list-items">,而是切换到 Row 布局容器,并将 Gutter 直接透传给 Row 的 Gutter 参数(见 AntList.razor 第 18 行)。从 Row 的源码(Row.razor.cs)可以看到,其 Gutter 参数通过 OneOf 联合类型支持多种赋值方式:
using GutterType = OneOf<
int,
Dictionary<string, int>,
(int, int),
(Dictionary<string, int>, int),
(int, Dictionary<string, int>),
(Dictionary<string, int>, Dictionary<string, int>)>;
即 Gutter 既可以是单一 int(如示例中的 16),也可以传按断点区分的字典形式 Dictionary<string, int>(例如 { "xs": 8, "lg": 16 }),甚至带垂直间距的元组形式,用于实现不同屏幕下的差异化间距。栅格列表场景中默认的整型 Gutter 最常用。
ListItem 在栅格模式下的渲染也发生了改变(见 ListItem.razor 第 4-19 行):当从级联参数拿到 Grid 时,它不再输出 <li>,而是输出一个宽度为 AntList.ColumnWidth 的百分比 div,内部再包裹 AntDesign.Col 并设置 Flex="1",从而在 Row 栅格中均匀分布。这一级联关系通过 CascadingValue 传递(AntList.razor 中每次迭代都会以 IsFixed 方式下推自身实例),IAntList 接口(见 IAntList.cs)暴露了 Grid、ItemLayout 和 ColumnWidth 三个只读成员供 ListItem 消费。
响应式栅格列表:断点列数源码解析
当需要让列表在不同设备上自适应列数时,使用 Xs ~ Xxl 系列属性。官方演示(见 Resposive.razor)给出了一个完整的响应式配置:
<AntList Grid="grid" DataSource="@Data">
<ListItem>
<Card Bordered Title="@(context.Title)">
<Body>
Card context
</Body>
</Card>
</ListItem>
</AntList>
@code {
private ListGridType grid = new()
{
Gutter = 16,
Xs = 1,
Sm = 2,
Md = 4,
Lg = 4,
Xl = 6,
Xxl = 3,
};
public List<BasicItem> Data = new List<BasicItem>
{
new BasicItem { Title = "Title 1"},
new BasicItem { Title = "Title 2"},
new BasicItem { Title = "Title 3"},
new BasicItem { Title = "Title 4"},
new BasicItem { Title = "Title 5"},
new BasicItem { Title = "Title 6"},
};
}
该配置的含义:极小屏(<576px)每行 1 列,小屏(≥576px)每行 2 列,中屏(≥768px)与大屏(≥992px)每行 4 列,超大屏(≥1200px)每行 6 列,超超大屏(≥1600px)回落到 3 列。注意这里刻意不设置 Column,完全交由断点控制。
断点切换的底层实现
响应式列数的切换逻辑在 AntList.razor.cs 中实现,核心是 Row 组件触发的 OnBreakpoint 回调:
private void OnBreakpoint(BreakpointType breakPoint)
{
var column = breakPoint switch
{
BreakpointType.Xs => Grid.Xs,
BreakpointType.Sm => Grid.Sm,
BreakpointType.Md => Grid.Md,
BreakpointType.Lg => Grid.Lg,
BreakpointType.Xl => Grid.Xl,
BreakpointType.Xxl => Grid.Xxl,
_ => 4,
};
if (column > 0)
{
_columnWidth = 100d / column;
}
}
Row 会在视口跨越断点阈值时回调 OnBreakpoint,AntList 据此取出对应断点的列数,重新计算每项的百分比宽度 _columnWidth = 100 / column。由于 ListItem 的宽度直接绑定 AntList.ColumnWidth(见 ListItem.razor 第 12 行),列数变化会立即反映到每个列表项的宽度上,从而实现无需刷新页面的平滑响应式布局。
列宽初始化的流程则依赖 Column 属性:
protected override void OnInitialized()
{
SetClassMap();
_columns = Grid?.Column ?? 0;
if (_columns > 0)
{
_columnWidth = 100d / Grid.Column;
}
base.OnInitialized();
_isInitialized = true;
}
protected override void OnParametersSet()
{
base.OnParametersSet();
if (_isInitialized && _columns != (Grid?.Column ?? 0))
{
_columnWidth = 100d / Grid.Column;
}
}
即:初始渲染时,若 Column > 0 则以固定列数计算列宽;若后续参数更新导致 Column 变化(例如运行时动态修改 Grid.Column),OnParametersSet 会同步刷新列宽。若 Grid 为 null(未启用栅格),则走常规的 <ul class="ant-list-items"> 列表分支(见 AntList.razor 第 29-37 行),且 ListItem 渲染为 <li> 元素。
断点优先级的注意点
结合上述两段代码可以推断出栅格列表的优先级规则:响应式断点列数在运行时优先于静态 Column——只要 OnBreakpoint 被触发且对应断点列数大于 0,列宽就会覆盖初始化时由 Column 算出的值。因此在响应式场景中应只配置 Xs ~ Xxl,而在需要"任何屏幕下都固定 N 列"的场景中则只配置 Column,二者按需取一即可。
栅格模式下的 CSS 类变化
启用栅格后,AntList 的样式也会随之调整。SetClassMap(见 AntList.razor.cs)中的关键规则:
ClassMapper.Clear()
.Add(PrefixName) // ant-list
.If($"{PrefixName}-split", () => Split) // ant-list-split
.If($"{PrefixName}-bordered", () => Bordered) // ant-list-bordered
.If($"{PrefixName}-vertical", () => ItemLayout == ListItemLayout.Vertical)
.If($"{PrefixName}-loading", () => (Loading))
.If($"{PrefixName}-grid", () => Grid != null) // 启用栅格时追加 ant-list-grid
.If($"{PrefixName}-something-after-last-item", () => IsSomethingAfterLastItem);
当 Grid != null 时组件会追加 ant-list-grid 类,样式系统据此移除列表项之间的分割线等与栅格布局冲突的默认样式。同时,Split 参数(默认 true)仍控制着 ant-list-split 的添加,若要在栅格模式下保留分割效果可自行通过该参数与 CSS 调整。
与其他 AntList 特性的组合
栅格列表可以与 AntList 的其他参数自由组合,常用的搭配包括:
Header/Footer:在栅格列表上方或下方渲染列表头尾内容,栅格主体仍保持多列排布(见 AntList.razor 的渲染结构);LoadMore:栅格底部渲染"加载更多"区域,IsSomethingAfterLastItem会随之追加ant-list-something-after-last-item类以保持间距正确;Bordered:为整个栅格列表容器加边框;Size:通过ListSize.Large/ListSize.Small切换列表整体密度(SizeCls会映射为ant-list-lg/ant-list-sm);Loading:配合内置Spin在栅格渲染期间显示加载状态(AntList.razor中用Spin Spinning="Loading"包裹内容)。
若希望查看更多列表形态的完整示例,可继续阅读同目录下的其他演示文档,例如 基础列表、加载更多、无限滚动 等;栅格相关的样式定义可在 components/list/style 目录中查阅。
总结
| 配置需求 | 推荐做法 |
|---|---|
| 任意屏幕下固定 N 列 | 只设置 ListGridType.Column = N,可选搭配 Gutter 控制列间距 |
| 不同屏幕显示不同列数 | 只设置 Xs / Sm / Md / Lg / Xl / Xxl,不设置 Column |
| 与 Ant Design 栅格体系保持一致 | 断点阈值即 BreakpointType(480 / 576 / 768 / 992 / 1200 / 1600),与 Row / Col 的断点完全一致 |
| 动态修改列数 | 运行时更新 Grid.Column,OnParametersSet 会自动重算列宽 |
| 卡片式内容展示 | 在 ListItem 中嵌套 Card,配合 context 绑定数据项 |
栅格列表的核心就一句话:grid 属性 + ListGridType 配置。理解 Column 与断点列数的工作方式、Row 栅格与 OnBreakpoint 的联动机制后,无论是固定多列的产品卡片墙,还是从手机到宽屏都表现良好的自适应列表,都可以用 Ant Design Blazor 的 AntList 简洁地实现。