ant-design-blazor List 列表组件完全指南:基础渲染、栅格响应式、分页与加载更多实战

原创2026-10-11 22:14:471,699 阅读
文章标签:前端UI组件设计系统WebAssembly

ant-design-blazor List 列表组件完全指南:基础渲染、栅格响应式、分页与加载更多实战

导读

List(列表)是 ant-design-blazor 中最基础的"数据展示"组件之一,负责把一组同构数据以横向或纵向的条目形式整齐呈现,常用于后台管理系统的数据展示页面。本文以 List 官方文档 为骨架,结合组件源码、官方示例与单元测试,系统讲解 List 的每一个配置参数、ListItem 与 ListItemMeta 的组合用法、栅格响应式布局、分页与"加载更多"等完整实战方案。读完本文,你将能够在自己的 Blazor 项目中熟练使用 List 搭建数据列表页,并掌握其底层渲染原理。

一、List 是什么,何时使用

按官方文档的定义,List 是"通用列表",适用于最基础的列表展示场景:可以承载文字、列表、图片、段落,常用于后台数据展示页面。它的定位与 Table 不同——Table 侧重结构化、可排序筛选的表格数据,而 List 更强调灵活自由的条目布局,一个条目里可以自由组合标题、描述、头像、图片、操作按钮等任意内容。

从组件分类看,它属于 数据展示(DataDisplay) 组件。组件本身是泛型实现 AntList<TItem>(见 AntList.razor.cs),TItem 即数据源 DataSource 的元素类型,这使得它可以与任意业务模型强类型配合,在编译期保证类型安全。

二、基础用法:从一段可运行的代码开始

最简单的 List 只需要两个要素:DataSource(数据源)和 ListItem(条目模板)。参考官方示例 Basic.razor:

<AntList DataSource="@data" TItem="BasicItem">
    <ListItem OnClick="()=>ItemClick(context.Title)">
        <ListItemMeta AvatarTemplate="avatar" Description="Ant Design, a design language for background applications, is refined by Ant UED Team">
            <TitleTemplate>
                <a href="https://ng.ant.design">@context.Title</a>
            </TitleTemplate>
        </ListItemMeta>
    </ListItem>
</AntList>

@code{
    RenderFragment avatar = @<Avatar Src="https://zos.alipayobjects.com/rmsportal/ODTLcjxAfvqbxHnVXCYX.png"></Avatar>;

    public class BasicItem
    {
        public string Title { get; set; }
    }

    public List<BasicItem> data = new List<BasicItem>
    {
        new BasicItem { Title = "Ant Design Title 1"},
        new BasicItem { Title = "Ant Design Title 2"},
        new BasicItem { Title = "Ant Design Title 3"},
        new BasicItem { Title = "Ant Design Title 4"},
    };

    public void ItemClick(string title)
    {
        Console.WriteLine($"item was clicked: {title}");
    }
}

这里有几个关键点需要理解:

  1. context 上下文变量:ListItem、ListItemMeta 等子组件通过 CascadingValue(级联值)从 AntList 拿到当前迭代元素。在 AntList.razor 中,遍历 DataSource 时每个元素都会包一层 <CascadingValue Value="this" IsFixed>,并把 ChildContent(item) 作为渲染内容,因此模板里可以直接用 context 访问当前条目数据。
  2. TItem 显式指定:当 DataSource 的类型无法从属性推断(例如 List<BasicItem> 赋值给 IEnumerable<TItem>)时,需要显式写出 TItem="BasicItem"。
  3. OnClick 点击回调:ListItem 的 OnClick 是 EventCallback,在 ListItem.razor.cs 中通过 HandleClick 触发,点击时回调参数是 ListItem 实例本身。上面的示例用 lambda 捕获了 context.Title,实现"点击某一条目拿到它的标题"。

注意:示例代码中的图片地址与跳转链接属于官方演示数据,实际项目请替换为自己的资源地址。

渲染结构与测试验证

从 List.Render.Tests.razor 的 Render_basic_list 测试可以看到真实渲染出的 DOM 结构:div.ant-list 根节点 → div.ant-list-header → div.ant-list-spin-wrapper(内部包一层 Spin)→ ul.ant-list-items → 多个 li.ant-list-item → 最后是 div.ant-list-footer。这条链路印证了 AntList.razor 的模板组织方式:Header 在最上、条目列表居中、Footer 与 LoadMore 在最下。

三、List 组件 API 参数详解

以下表格完整继承自官方文档,并结合源码补充了 Blazor 实现中的实际类型与默认行为。

List 主组件参数

参数 说明 Blazor 类型 默认值 源码依据
bordered 是否展示边框 bool false AntList.razor.cs
footer 列表底部内容 RenderFragment - AntList.razor.cs
grid 列表栅格配置 ListGridType - AntList.razor.cs
header 列表头部内容 RenderFragment - AntList.razor.cs
itemLayout 条目布局,Vertical 则竖直样式,默认横排 ListItemLayout Horizontal AntList.razor.cs、ListItemLayout.cs
loading 内容加载中的占位展示 bool false AntList.razor.cs
loadMore 加载更多内容 RenderFragment - AntList.razor.cs
locale 默认文案设置(含空数据文案) - - 官方文档定义
pagination 分页配置,null 时不显示 PaginationOptions - AntList.razor.cs
size 列表尺寸 ListSize ListSize.Default AntList.razor.cs、ListSize.cs
split 是否展示分割线 bool true AntList.razor.cs
dataSource 列表数据源 IEnumerable<TItem> - AntList.razor.cs
renderItem 数据源渲染模板(React 概念,Blazor 中用 ChildContent 实现) RenderFragment<TItem>(即 ChildContent) - AntList.razor.cs
OnItemClick 列表项点击事件 见下文说明 - 官方文档定义

几点 Blazor 化差异需要特别说明:

  • 官方文档来自 React 版 Ant Design,其中 renderItem 是函数式渲染。Blazor 版用 ChildContent(泛型模板) 等价实现,模板参数即当前条目,写作 <ChildContent Context="item">...@item...</ChildContent> 或直接在 <ListItem> 中省略 ChildContent 包装。
  • OnItemClick 在 Blazor 版中由 ListItem 的 OnClick 承担(EventCallback,回调参数为 ListItem),见 ListItem.razor.cs。注意 AntList.razor.cs 中还有一个 NoResult 参数,源码注释标注"Currently unused"(当前未使用),空数据时的空文案展示与 React 版存在差异,从 AntList.razor 的源码结构看,数据为空时目前只渲染一个 min-height:53px 的占位区域,并未渲染空文案。
  • Loading 为 bool(React 版是 boolean|object)。实际占位效果由内置的 Spin 组件完成:AntList.razor 中用 <Spin Spinning="Loading" WrapperClassName="ant-list-spin-wrapper"> 包裹条目区域,Loading=true 时自动展示加载动画。

List 的 CSS 类名映射(源码视角)

SetClassMap()(AntList.razor.cs)集中体现了各参数如何落到 DOM 类名上,这是理解样式行为的捷径:

  • Split=true → ant-list-split(条目间分割线)
  • Bordered=true → ant-list-bordered
  • Size=Large → ant-list-lg;Size=Small → ant-list-sm(SizeCls 映射)
  • ItemLayout=Vertical → ant-list-vertical
  • Loading=true → ant-list-loading
  • Grid != null → ant-list-grid
  • Footer / LoadMore / Pagination 任一存在 → ant-list-something-after-last-item

四、Header / Footer / Bordered / Size / Split:快速搭建列表外壳

参考官方示例 Simple.razor,一个带边框、有头有尾的列表是这样写的:

<Divider Orientation="DividerOrientation.Left">Default Size</Divider>

<AntList Bordered DataSource="@data">
    <Header>Header</Header>
    <ChildContent Context="item">
        <ListItem>
            <span><Text Mark>[ITEM]</Text></span>@item
        </ListItem>
    </ChildContent>
    <Footer>Footer</Footer>
</AntList>

<Divider Orientation="DividerOrientation.Left">Small Size</Divider>

<AntList Bordered DataSource="@data" Size="ListSize.Small">
    <!-- 同上结构 -->
</AntList>

<Divider Orientation="DividerOrientation.Left">Large Size</Divider>

<AntList Bordered DataSource="@data" Size="ListSize.Large">
    <!-- 同上结构 -->
</AntList>

要点:

  • Header / Footer 是 RenderFragment,可放任意内容(标题、统计、按钮等),渲染在 ant-list-header / ant-list-footer 容器中。
  • Size 是 ListSize 枚举(Small / Default / Large),控制条目的内边距与字体大小,对应类名 ant-list-sm / ant-list-lg。
  • Split 默认 true,控制条目间是否显示分割线,适合紧凑型列表时置为 false。
  • 在这个示例里 ChildContent 显式使用了 Context="item" 命名模板参数,写法与直接写在 <ListItem> 中完全等价。

五、ListItem 详解:Actions 操作组与 Extra 附加内容

ListItem 是单条数据的容器,核心参数有三个(见 ListItem.razor.cs):

参数 说明 类型
Extra 额外内容:Vertical 布局时显示在条目右侧,Horizontal 布局时显示在最右侧 RenderFragment
Actions 操作组:根据 itemLayout 不同,位置在条目底部(垂直)或最右侧(水平) RenderFragment[]
ChildContent 条目主体内容 RenderFragment

Actions 与 Extra 的布局逻辑在 ListItem.razor 中清晰可见:当 IsVerticalAndExtra(即 ItemLayout==Vertical 且设置了 Extra)为真时,条目主体与操作组包在 ant-list-item-main 中、Extra 放在右侧 ant-list-item-extra;否则 Actions 与 Extra 依次排放在主体之后。操作组内部的每个操作项间会自动插入 ant-list-item-action-split 分割符(ListItem.razor)。

官方示例 Vertical.razor 展示了操作组 + 附加图片的完整用法:

<AntList DataSource="@ListData" ItemLayout="@ListItemLayout.Vertical">
    <ChildContent Context="item">
        <ListItem Extra="@extra" Actions="@(new[] { iconText(("start","156")),iconText(("like","156")),iconText(("message","2")) })">
            <ListItemMeta Description="@item.Description">
                <AvatarTemplate>
                    @avatar
                </AvatarTemplate>
                <TitleTemplate>
                    <a href="@item.Href">@item.Title</a>
                </TitleTemplate>
            </ListItemMeta>
            @item.Content
        </ListItem>
    </ChildContent>
    <Footer>
        <div>
            <b>ant design</b> footer part
        </div>
    </Footer>
</AntList>

其中 Actions 是一个 RenderFragment[],每个元素可以是由 Icon + 文本 组合而成的操作(收藏、点赞、评论等),渲染后呈现在条目底部,操作之间自动带分割线。

另外,ListItem 还提供了 NoFlex 参数:默认条目使用 flex 布局,当内容结构特殊导致 flex 影响排版时,可设置 NoFlex=true 关闭(见 ListItem.razor.cs 及类名 ant-list-item-no-flex 映射)。

六、ListItemMeta:头像 + 标题 + 描述的黄金组合

ListItemMeta 提供列表元素的标准元信息展示,是列表条目的"三件套"(参数见 ListItemMeta.razor.cs):

参数 说明 类型 优先级
avatar 列表元素的头像图片地址 string 与 AvatarTemplate 二选一
AvatarTemplate 头像内容(可放任意组件,如自定义 <Avatar>) RenderFragment 优先于 Avatar
title 列表元素的标题文本 string 与 TitleTemplate 二选一
TitleTemplate 标题内容(可放链接、富文本) RenderFragment 优先于 Title
description 描述文本 string 与 DescriptionTemplate 二选一
DescriptionTemplate 描述内容 RenderFragment 优先于 Description

注意一个与 React 版不同的设计:每个字段都同时提供字符串与模板两个版本,且模板版优先。从 ListItemMeta.razor 的渲染逻辑看,Title / Description 仅在对应的字符串参数非空时输出,否则渲染 Template 版。因此"标题要带超链接"这种需求,直接写 <TitleTemplate><a href="...">@context.Title</a></TitleTemplate> 即可,无需额外处理字符串拼接。

渲染结构为 ant-list-item-meta-avatar(头像区)+ ant-list-item-meta-content(内容区,内含 ant-list-item-meta-title 与 ant-list-item-meta-description)。ListItemMeta 通过 <a href="https://link.gitcode.com/i/d37b829d5022890ccd1b17be33c94bbe" target="_blank">CascadingParameter] ListItem([ListItemMeta.razor.cs)感知所在条目,必须嵌套在 ListItem 内部使用。

七、栅格布局 ListGridType:列数、间距与响应式断点

React 版文档中 List 的 grid 配置是一个对象,Blazor 中对应强类型类 ListGridType.cs,参数完全一致:

参数 说明 类型 默认值
column 列数 int -
gutter 栅格间隔 int 0
xs <576px 屏展示的列数 int -
sm ≥576px 屏展示的列数 int -
md ≥768px 屏展示的列数 int -
lg ≥992px 屏展示的列数 int -
xl ≥1200px 屏展示的列数 int -
xxl ≥1600px 屏展示的列数 int -

固定列数的栅格

参考 Grid.razor,4 列卡片式列表:

<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 };
    // ...Data 为 List<BasicItem>
}

响应式断点栅格

参考 Resposive.razor,在不同屏幕宽度下自动切换列数:

private ListGridType grid = new()
{
    Gutter = 16,
    Xs = 1,
    Sm = 2,
    Md = 4,
    Lg = 4,
    Xl = 6,
    Xxl = 3,
};

栅格底层原理

当 Grid != null 时,AntList.razor 不再渲染 ul 列表,而是改用 <Row Gutter="Grid.Gutter" OnBreakpoint="OnBreakpoint"> 包裹每个条目,条目套上 <Col Flex="1">(见 ListItem.razor),其宽度由 width: @(AntList.ColumnWidth)% 控制——ColumnWidth 由 AntList.razor.cs 的 OnBreakpoint 回调根据当前断点计算(100 / 断点列数)。这也解释了为什么 List.Render.Tests.razor 中 Grid_is_reacting_to_change 测试断言:把 Column 从 4 改为 2 后,条目宽度样式变为 width: 50%; max-width: 50%;——断点与列数变化都会实时反映到每个条目的宽度上。

实战提示:只设置 column 时,固定列数对所有屏幕生效;需要移动端适配时,务必配置 xs/sm 等断点列数,让列表在手机上退化为单列/双列。

八、分页配置:Pagination 与 PaginationOptions

官方文档规定:pagination 参数可传 false 或分页配置对象;配置项中 position 决定分页显示位置(top | bottom | both,默认 bottom),其余配置项与 Pagination 组件一致。

在 Blazor 版中,AntList 的 Pagination 参数类型为 PaginationOptions(见 AntList.razor.cs),其常用配置项可从 PaginationOptions.razor.cs 与 Pagination.razor.cs 中确认:

参数 说明 默认值
Current 当前页码 1
PageSize 每页条数 -
Total 数据总条数 0
PageSizeOptions 每页条数切换选项 { 10, 20, 50, 100 }(源码定义)
ShowSizeChanger 是否显示每页条数切换器 依据 TotalBoundaryShowSizeChanger(默认 50)自动决定,见 Pagination.razor.cs
ShowQuickJumper 是否显示快速跳页输入框 false
HideOnSinglePage 只有一页时是否隐藏分页 false
ShowTotal 显示总条数文案 -
Disabled 禁用分页 false
ChangeSize 每页条数变化回调 EventCallback<int>
QuickGo 跳转页码回调 EventCallback<int>

一个典型的分页列表写法:

<AntList DataSource="@pagedData" TItem="BasicItem"
         Pagination="new PaginationOptions { Current = 1, PageSize = 10, Total = total, ShowSizeChanger = true, ShowQuickJumper = true }">
    <ListItem>
        <ListItemMeta Title="@(context.Title)" />
    </ListItem>
</AntList>

关于 position 的说明:React 版通过 position 控制分页位于顶部或底部;从当前仓库源码结构看,AntList.razor 的模板(Header → 条目区 → Footer → LoadMore)中并没有直接渲染分页器的位置分支,Pagination 参数目前主要参与 IsSomethingAfterLastItem 判定(AntList.razor.cs,用于追加 ant-list-something-after-last-item 类名)。如果你的需求是"列表底部带完整分页器",更稳妥的做法是使用独立的 Pagination 组件放在 Footer 中,配合 Total、Current、OnChange 实现数据切片;这也是社区常见的组合方式。使用前请以你实际引入的组件版本行为为准。

九、Loading 与 LoadMore:异步加载两种主流模式

1. Loading 占位

Loading="true" 时,条目区域被 Spin 的转圈动画覆盖(见 AntList.razor),适合首屏从接口拉数据的场景。注意 Loading 与数据源是否为空无关,需要你在数据到达后手动置回 false。

2. LoadMore 加载更多

LoadMore 是 RenderFragment,渲染在列表最底部。参考官方示例 Loadmore.razor,经典"加载更多"模式如下:

<AntList Class="demo-loadmore-list" DataSource="@Data" ItemLayout="ListItemLayout.Horizontal" Loading="@InitLoading">
    <ChildContent Context="item">
        <ListItem Actions="actions">
            <ListItemMeta AvatarTemplate="avatar" Description="Ant Design, a design language for background applications, is refined by Ant UED Team">
                <TitleTemplate>
                    <a href="https://ant.design">@item.Name.Last</a>
                </TitleTemplate>
            </ListItemMeta>
            <div>content</div>
        </ListItem>
    </ChildContent>
    <LoadMore>
        @if (!InitLoading && !Loading)
        {
            <div class="demo-loadmore-btn-content ">
                <Button OnClick="OnLoadMore">loading more</Button>
            </div>
        }
    </LoadMore>
</AntList>

配套的后端逻辑要点:

  • InitLoading 控制首屏加载动画,数据到达后置 false;
  • OnLoadMore 中将 Loading=true,拉取新数据后用 Data.AddRange(res) 追加到数据源,再置回 false;
  • LoadMore 区域内通过 !InitLoading && !Loading 条件控制按钮显示,避免加载期间重复触发;
  • Class="demo-loadmore-list" 可自定义列表高度等样式(示例中配合 <style> 块设置 min-height,让加载按钮吸附在固定高度底部)。

该示例通过 HttpClient.GetFromJsonAsync 从演示接口拉取数据(Loadmore.razor),生产环境请替换为你自己的数据服务。

十、进阶:拖拽排序列表(Draggable)

借助 Blazor 原生拖拽事件,可以在 List 之上直接实现条目的拖拽排序,无需额外 JS 库。参考官方示例 Draggable.razor:

<AntList Bordered DataSource="@data">
    <Header>Header</Header>
    <ChildContent Context="item">
        <ListItem>
            <div draggable="true" @ondrop="e=>OnDrop(e, item)" @ondragstart="e=>OnDragStart(e, item)" ondragover="event.preventDefault()">
                <span><Text Mark>[ITEM]</Text></span>@item
            </div>
        </ListItem>
    </ChildContent>
    <Footer>Footer</Footer>
</AntList>

@code {
    string _dragging;
    void OnDrop(DragEventArgs e, string s)
    {
        if (!string.IsNullOrEmpty(s) && !string.IsNullOrEmpty(_dragging)) {
            int index = data.IndexOf(s);
            data.Remove(_dragging);
            data.Insert(index, _dragging);
            _dragging = null;
            StateHasChanged();
        }
    }

    void OnDragStart(DragEventArgs e, string s)
    {
        e.DataTransfer.DropEffect = "move";
        e.DataTransfer.EffectAllowed = "move";
        _dragging = s;
    }
}

原理:@ondragstart 记录被拖动的条目文本,@ondrop 时按目标条目下标将记录元素移除并插入,最后 StateHasChanged() 强制重渲染,List 会依据更新后的 DataSource 自动重排。

十一、完整参数速查与使用建议

最后汇总一遍各子组件的参数表,便于开发时快速查阅:

List.Item

参数 说明 类型 默认值
actions 列表操作组:Vertical 布局在底部,Horizontal 布局在最右侧 RenderFragment[] -
extra 额外内容:Vertical 布局显示右侧,Horizontal 布局显示最右侧 RenderFragment -
OnClick 条目点击回调,参数为当前 ListItem EventCallback -
NoFlex 置 true 时条目不使用 flex 布局 bool false

List.Item.Meta

参数 说明 类型 默认值
avatar 头像图片地址 string -
AvatarTemplate 头像内容模板(优先于 Avatar) RenderFragment -
description 描述文本 string -
DescriptionTemplate 描述内容模板(优先于 Description) RenderFragment -
title 标题文本 string -
TitleTemplate 标题内容模板(优先于 Title) RenderFragment -

实战选型建议

  • 纯文本/元信息列表:AntList + ListItemMeta,配合 Header/Footer/Bordered/Size/Split 即可覆盖 80% 的后台展示需求;
  • 卡片瀑布/图文网格:设置 Grid 的 Column 与响应式断点,条目内放 Card;
  • Feed 流/长列表:Vertical 布局 + Actions 操作组 + Extra 附加图 + LoadMore 加载更多;
  • 海量数据分页:DataSource 按页切片 + Footer 内嵌 Pagination,或直接使用 Pagination 参数并按组件实际支持程度调整。

结语

List 组件看似简单,但 AntList<TItem> + ListItem + ListItemMeta 的三层组合、ListGridType 的响应式栅格、LoadMore 异步加载模式共同构成了后台数据展示页的高频骨架。本文的每个结论都能在仓库源码(components/list 目录)、官方示例(AntList 示例)与单元测试(List.Render.Tests.razor)中找到对应依据。动手实践时,建议从 Basic 示例出发,逐步叠加 Grid、Vertical、LoadMore,最终组合出适合你业务形态的列表方案。

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