Ant Design Blazor 栅格列表(Grid List)实战指南:基于 ListGridType 的列数与响应式布局详解

原创2026-10-09 21:39:571,688 阅读
文章标签:UI组件前端

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 视口下的列数

几点需要特别注意:

  1. Column 与响应式断点互斥:Column 提供的是不随视口变化的固定列数;而 Xs~Xxl 六个断点用于实现响应式栅格。若同时设置,Column 只在组件初始化时被读取一次(见下文"实现原理"),而断点值会在窗口尺寸变化时覆盖列宽计算,因此两者一般二选一使用。
  2. 所有属性均为 int 而非可空类型:断点值为 0 表示"该断点不生效"。从 AntList 的 OnBreakpoint 处理逻辑可以看到,只有 column > 0 时才会更新列宽(if (column > 0) { _columnWidth = 100d / column; })。
  3. 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 类驱动,而是组件在运行时动态计算的百分比宽度,链路如下:

  1. 初始化:在 AntList.OnInitialized() 中读取 Grid?.Column ?? 0,若 Column > 0 则计算 _columnWidth = 100d / Grid.Column(AntList.razor.cs)。例如 Column = 4 时,_columnWidth = 25(即 25%)。
  2. 列宽注入: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 中形成均分的一行。

  1. 参数变更响应: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 固定列数。

六、常见问题与调试建议

  1. 设置了 Grid 但列表仍是普通列表形态:确认 Grid 参数确实传入且非 null(如 <AntList Grid="grid">),并检查 ClassMapper 是否出现 ant-list-grid 类。DataSource 为空时列表直接渲染为空占位(min-height:53px 的占位 div),不会出现栅格结构。
  2. 固定列数与响应式断点混用:Column 只在初始化和参数变更时生效,窗口缩放过程中会被断点值覆盖,容易造成列数跳变,建议二者只取其一。
  3. 栅格子项宽度不均:请勿在 ListItem 模板外层再包自定义宽度的容器,栅格宽度由 ListItem 内部按 ColumnWidth% 控制,外层包裹会破坏均分布局。
  4. 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)可作为继续深入与验证的入口。

登录后查看全文
ant-design-blazor