Ant Design Blazor 栅格列表(Grid List)实战指南:基于 ListGridType 的列数与响应式布局详解
Ant Design Blazor 栅格列表(Grid List)实战指南:基于 ListGridType 的列数与响应式布局详解
导读
栅格列表是 Ant Design Blazor 中 AntList 组件的重要形态:它把普通垂直列表的布局交给网格系统接管,让每一条数据以卡片、图块等富内容形式按指定列数排列,是数据展示类页面的高频场景。本文以官方演示文档 Grid(栅格列表) 为骨架,结合 ListGridType、AntList 与 Row 的源码实现与单元测试,系统讲解 grid 属性的配置方式、column 与响应式断点的取值规则、以及底层布局原理,读完即可在项目中落地可复制的栅格列表与响应式栅格列表。
一、栅格列表是什么:grid 属性的作用与使用场景
官方文档对栅格列表的定义非常简洁:通过设置 List 的 grid 属性即可实现栅格列表,column 用于设置期望显示的列数(原文档见 demo/grid.md)。
在 Ant Design Blazor 中,AntList<TItem> 组件(源码见 AntList.razor.cs)暴露了一个类型为 ListGridType 的 <a href="https://link.gitcode.com/i/149ceafb2945d9bf6a0031448a581f84" target="_blank">Parameter] Grid。当该参数为 null(默认值)时,AntList 渲染为传统的 <ul class="ant-list-items"> 垂直列表;一旦为 Grid 赋值,渲染逻辑就会切换到网格布局分支(见 [AntList.razor):
@if (Grid != null)
{
<Row Gutter="Grid.Gutter" OnBreakpoint="OnBreakpoint">
@foreach (var item in DataSource)
{
<CascadingValue Value="this" IsFixed>
@ChildContent(item)
</CascadingValue>
}
</Row>
}
else
{
<ul class="ant-list-items">...</ul>
}
同时,组件在 SetClassMap() 中会为根元素追加 ant-list-grid 类(条件为 Grid != null),用于应用栅格列表的专属样式。
典型使用场景包括:
- 卡片式数据展示:如图片墙、商品橱窗、成员列表,每条数据渲染成一张
Card; - Dashboard 模块网格:把若干功能卡片按固定列数排布;
- 瀑布流式内容列表:配合
Header、LoadMore、Pagination等参数组合成完整的信息流页面。
二、ListGridType 参数详解:Gutter、Column 与六个响应式断点
ListGridType 是栅格列表的配置载体,定义于 ListGridType.cs,共 8 个属性,含义与 Ant Design 的 Layout Grid 断点体系完全一致:
| 属性 | 类型 | 默认值 | 含义 |
|---|---|---|---|
Gutter |
int |
0 |
栅格之间的水平间距(单位 px),会透传给内部 Row 的 Gutter |
Column |
int |
0 |
固定列数,所有屏幕尺寸下都使用该列数 |
Xs |
int |
0 |
<576px 视口下的列数 |
Sm |
int |
0 |
≥576px 视口下的列数 |
Md |
int |
0 |
≥768px 视口下的列数 |
Lg |
int |
0 |
≥992px 视口下的列数 |
Xl |
int |
0 |
≥1200px 视口下的列数 |
Xxl |
int |
0 |
≥1600px 视口下的列数 |
几点需要特别注意:
Column与响应式断点互斥:Column提供的是不随视口变化的固定列数;而Xs~Xxl六个断点用于实现响应式栅格。若同时设置,Column只在组件初始化时被读取一次(见下文"实现原理"),而断点值会在窗口尺寸变化时覆盖列宽计算,因此两者一般二选一使用。- 所有属性均为
int而非可空类型:断点值为0表示"该断点不生效"。从AntList的OnBreakpoint处理逻辑可以看到,只有column > 0时才会更新列宽(if (column > 0) { _columnWidth = 100d / column; })。 Gutter是纯水平间距:在AntList中Gutter被直接绑定为<Row Gutter="Grid.Gutter">。相比Row组件本身支持(horizontal, vertical)元组形式的复杂 gutter(见 Row.razor.cs),ListGridType.Gutter只接受单一int,即只控制水平间距,垂直方向的行间距由网格自动换行时的row-gap逻辑处理。
三、固定列数栅格:column 的用法与完整示例
官方演示 Grid.razor 给出了最直接的固定列数用法——4 列、间距 16px 的卡片列表:
<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="grid":把ListGridType实例绑定到列表的grid参数,这是切换为栅格形态的唯一开关;DataSource与ListItem模板:数据源中的每一项都会进入ChildContent(item),在栅格模式下ListItem自动被Col包裹(详见第四节);Card作为栅格子项:这是最典型的内容形态,Title="@(context.Title)"中的context是RenderFragment<TItem>的隐式上下文参数,即当前数据项;Column = 4:无论屏幕多宽,始终一行显示 4 列;Gutter = 16表示列与列之间 16px 水平间距。
若数据量大于列数,栅格会自动换行,多出的项进入下一行,无需任何额外处理。
四、底层原理:列宽如何从 Column 变为百分比
从源码看,栅格列表的列宽并非 CSS 类驱动,而是组件在运行时动态计算的百分比宽度,链路如下:
- 初始化:在
AntList.OnInitialized()中读取Grid?.Column ?? 0,若Column > 0则计算_columnWidth = 100d / Grid.Column(AntList.razor.cs)。例如Column = 4时,_columnWidth = 25(即 25%)。 - 列宽注入:
ListItem在栅格模式下渲染为如下结构(ListItem.razor):
<div style="width: @(AntList.ColumnWidth)%; max-width: @(AntList.ColumnWidth)%;">
<AntDesign.Col Flex="1">
<div class="ant-list-item" ...>
@itemChildren(this)
</div>
</AntDesign.Col>
</div>
外层 <div> 通过内联样式 width/max-width 撑满百分比宽度,内层 Col 负责 gutter 间距的负 margin 补偿与 padding 处理,从而在 Row 中形成均分的一行。
- 参数变更响应:
OnParametersSet()中会比对_columns与最新的Grid?.Column,不一致时重新计算_columnWidth(AntList.razor.cs)。这一行为有单元测试覆盖:测试 Grid_is_reacting_to_change 先以Gutter=16, Column=4渲染,再通过SetParametersAndRender改为Gutter=8, Column=2,断言行内样式从原值变为"width: 50%; max-width: 50%;",验证了列宽对参数变化的实时响应。
五、响应式栅格列表:六档断点配置与实现机制
官方文档在 resposive.md 中说明:响应式的栅格列表,尺寸与 Layout Grid 的 Col 保持一致(断点阈值即上表 Xs/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" },
};
public class BasicItem
{
public string Title { get; set; }
}
}
该示例展示了从手机到超宽屏的完整适配曲线:超小屏 1 列 → 小屏 2 列 → 中屏 4 列 → 大屏 4 列 → 特大屏 6 列 → 超特大屏 3 列。
底层实现机制:响应式切换依赖 Row 组件提供的断点回调。AntList 在渲染栅格时把自身的 OnBreakpoint 方法挂到 <Row OnBreakpoint="OnBreakpoint"> 上(AntList.razor);Row 在 OnAfterRenderAsync 中通过 JS 互操作获取窗口宽度,并监听 window.resize 事件,一旦视口跨越断点阈值便回调(Row.razor.cs)。AntList.OnBreakpoint 随后按当前断点读取对应的列数值并重算百分比列宽(AntList.razor.cs):
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;
}
}
可见:断点值大于 0 时该断点生效并覆盖列宽;所有断点均未配置(全为 0)时,响应式分支不会触发任何列宽更新,此时应使用 Column 固定列数。
六、常见问题与调试建议
- 设置了
Grid但列表仍是普通列表形态:确认Grid参数确实传入且非null(如<AntList Grid="grid">),并检查ClassMapper是否出现ant-list-grid类。DataSource为空时列表直接渲染为空占位(min-height:53px的占位 div),不会出现栅格结构。 - 固定列数与响应式断点混用:
Column只在初始化和参数变更时生效,窗口缩放过程中会被断点值覆盖,容易造成列数跳变,建议二者只取其一。 - 栅格子项宽度不均:请勿在
ListItem模板外层再包自定义宽度的容器,栅格宽度由ListItem内部按ColumnWidth%控制,外层包裹会破坏均分布局。 Gutter未生效:确认Gutter是正数;Row只有在horizontalGutter > 0时才生成负 margin 样式(Row.razor.cs),Gutter = 0等价于无间距。
结语
栅格列表是 AntList 在数据展示场景下的关键形态:一个 ListGridType 实例即可同时控制间距、固定列数与六个响应式断点,底层由 AntList + Row + Col 三组件协作完成百分比列宽计算与断点监听。无论是 Column = 4 的固定卡片墙,还是 Xs=1 ... Xxl=3 的全尺寸适配,都只需绑定 grid 参数即可实现。相关源码与测试(AntList.razor.cs、ListItem.razor、Row.razor.cs、List.Render.Tests.razor)可作为继续深入与验证的入口。