ant-design-blazor List 组件完全指南:从基础列表到响应式栅格、加载更多与分页配置
ant-design-blazor List 组件完全指南:从基础列表到响应式栅格、加载更多与分页配置
导读
本文围绕 ant-design-blazor 组件库中的 List(列表)组件展开,系统讲解其核心 API、栅格布局、列表项(ListItem)与元数据(ListItemMeta)的组合方式,并结合仓库内真实 demo 与单元测试给出可直接落地的 Blazor 代码示例。读完本文,你将掌握如何用 AntList 快速构建后台数据展示页、实现垂直/水平布局、响应式栅格、加载更多以及列表项交互等完整实战方案。
List 是典型的"数据展示"型组件,定义于 components/list 目录,核心实现由 AntList.razor.cs、ListItem.razor.cs 与 ListItemMeta.razor.cs 三部分构成,本仓库文档源文件为 site/AntDesign.Docs/Demos/Components/List/doc/index.en-US.md。
组件简介与适用场景
官方文档对 List 的定位是 "Simple List"(通用列表)。其典型适用场景是:
展示同一主题下的相关内容,内容可以由多种不同类型、不同尺寸的元素组成。
从中文文档的表述来看,它是"最基础的列表展示,可承载文字、列表、图片、段落,常用于后台数据展示页面"。在 ant-design-blazor 中,AntList<TItem> 是一个泛型组件,配合 ListItem、ListItemMeta 可以组合出从"简单文本列表"到"带头像、标题、描述、操作区、额外内容"的完整列表形态。
核心 API 详解:AntList 参数
原文档的 API 表格源自 Ant Design React 设计体系,在 Blazor 实现中,参数以 <a href="https://link.gitcode.com/i/6936bd31892a8a40d139c649c9425511" target="_blank">Parameter] 特性声明于 [AntList.razor.cs。下表完整继承原文档,并对照给出当前仓库 Blazor 实现中的实际对应关系:
| 原文档参数 | 说明 | Blazor 实现对应 | 默认值 |
|---|---|---|---|
| bordered | 是否展示边框 | Bordered(bool) |
false |
| footer | 列表底部 | Footer(RenderFragment) |
- |
| grid | 列表栅格配置 | Grid(ListGridType) |
- |
| header | 列表头部 | Header(RenderFragment) |
- |
| itemLayout | 列表项布局,vertical 为竖直、默认横排 |
ItemLayout(ListItemLayout 枚举) |
Horizontal |
| loading | 内容加载中显示占位 | Loading(bool) |
false |
| loadMore | 加载更多 | LoadMore(RenderFragment) |
- |
| locale | 默认文案(含空数据文案) | 源码中对应 NoResult,当前标注 "Currently unused" |
- |
| pagination | 分页配置,设为 false 不显示 |
Pagination(PaginationOptions) |
null |
| size | 列表尺寸 | Size(ListSize 枚举) |
ListSize.Default |
| split | 是否展示分割线 | Split(bool) |
true |
| dataSource | 列表数据源 | DataSource(IEnumerable<TItem>) |
- |
| renderItem | 自定义渲染列表项 | ChildContent(RenderFragment<TItem>) |
- |
| OnItemClick | 列表项点击事件 | 见下文 ListItem.OnClick |
- |
几点值得注意:
- 类型差异:原文档中
footer/header/loadMore为string|ReactNode,Blazor 版本统一收敛为RenderFragment,意味着头部、底部、加载更多区域都可以直接嵌套任意 Razor 内容。 - rowKey:原文档存在
rowKey(项的唯一键)参数,但从当前 AntList.razor.cs 的源码结构看,该参数尚未在 Blazor 实现中落地,列表项渲染直接遍历DataSource。 - locale 与空数据文案:源码中声明了
NoResult参数但注释为 "Currently unused"(见 AntList.razor.cs),因此原文档中emptyText: '暂无数据'的空态文案能力在当前版本中尚未启用。
数据源与模板渲染机制
DataSource 配合 ChildContent(泛型 RenderFragment<TItem>)是 List 的基本用法。渲染时,AntList.razor 使用 CascadingValue 将当前 AntList 实例传递给每一个列表项,ListItem 再通过 <a href="https://link.gitcode.com/i/6e63cc9f9ef730aa77a26033214c9511" target="_blank">CascadingParameter] IAntList(见 [IAntList.cs)读取栅格与布局信息:
<AntList DataSource="@data" TItem="BasicItem">
<ChildContent Context="item">
<ListItem>
<span>@item.Title</span>
</ListItem>
</ChildContent>
</AntList>
渲染细节:
- 当
DataSource?.Any() == true时,列表体包在<ul class="ant-list-items">中,逐项输出<li>;栅格模式下则改用Row+Col布局。 - 当数据源为空时,渲染一个
min-height:53px的占位 div,保证页面结构稳定。 - 列表体被
Spin(Spinning="Loading")包裹,加载时自动显示 Spin 占位,这与loading参数一一对应。
头部、底部与加载更多
Header、Footer、LoadMore 三个 RenderFragment 分别渲染在列表体的前、后:
<AntList Bordered DataSource="@data">
<Header>Header</Header>
<ChildContent Context="item">
<ListItem><span>@item</span></ListItem>
</ChildContent>
<Footer>Footer</Footer>
<LoadMore>
<Button OnClick="OnLoadMore">加载更多</Button>
</LoadMore>
</AntList>
源码中 IsSomethingAfterLastItem(AntList.razor.cs)判断 LoadMore || Footer || Pagination 任一存在,则给根节点追加 ant-list-something-after-last-item 样式类,用于让最后一项仍显示分割线(对应 style/index.less 中的 &-split&-something-after-last-item 规则)。
边框、分割线与尺寸
Bordered、Split、Size 通过 ClassMapper 动态映射为 CSS 类(见 AntList.razor.cs):
| 参数 | 生成的 CSS 类 | 效果 |
|---|---|---|
Split=true |
ant-list-split |
列表项之间显示分割线(border-bottom,最后一项去除) |
Bordered=true |
ant-list-bordered |
列表整体边框 |
Size=Small |
ant-list-sm |
缩小列表项内边距 |
Size=Large |
ant-list-lg |
增大列表项内边距 |
ItemLayout=Vertical |
ant-list-vertical |
竖直布局 |
ListSize 枚举定义于 ListSize.cs:Small / Default / Large;ListItemLayout 枚举定义于 ListItemLayout.cs:Horizontal / Vertical。
分页配置
Pagination 参数的类型是 PaginationOptions(定义于 PaginationOptions.razor.cs),它是从 Pagination 组件中抽取的配置载体,支持:
| 配置项 | 说明 | 默认值 |
|---|---|---|
Total |
数据总条数 | 0 |
Current / DefaultCurrent |
当前页 / 初始页 | 1 |
PageSize / DefaultPageSize |
每页条数 | 10 |
PageSizeOptions |
每页条数可选值 | { 10, 20, 50, 100 } |
Disabled |
禁用分页 | false |
OnChange |
页码变化回调 | - |
OnPageSizeChanged |
每页条数变化回调 | - |
原文档同时强调,分页还支持 position 配置(top | bottom | both,默认 bottom),即指定 Pagination 显示位置;更多分页细节可参考 Pagination 组件。需要说明的是:从当前 AntList.razor 的模板结构看,Pagination 参数已定义并在样式层预留了 ant-list-pagination 规则(见 style/index.less),但模板内暂未直接渲染分页器,实际项目中建议配合 Pagination 组件自行实现分页逻辑。
栅格布局:ListGridType 与响应式列数
grid 参数对应 ListGridType 类型(ListGridType.cs),字段与原文档表格完全一致:
| 字段 | 说明 | 默认值 |
|---|---|---|
Column |
列数 | 0 |
Gutter |
栅格间隔 | 0 |
Xs |
<576px 展示的列数 |
0 |
Sm |
≥576px 展示的列数 |
0 |
Md |
≥768px 展示的列数 |
0 |
Lg |
≥992px 展示的列数 |
0 |
Xl |
≥1200px 展示的列数 |
0 |
Xxl |
≥1600px 展示的列数 |
0 |
实现机制(从源码结构看):
- 开启栅格后,AntList.razor 用
Row Gutter="Grid.Gutter" OnBreakpoint="OnBreakpoint"承载列表项,每项外层包裹Col Flex="1",列宽按100 / 列数计算。 Row组件会在窗口断点变化时触发OnBreakpoint(见 Row.razor.cs 与 Row.razor.cs),AntList据此切换Xs/Sm/Md/Lg/Xl/Xxl对应列数并重算_columnWidth(AntList.razor.cs)。- 固定列数时,
OnInitialized中按Grid.Column计算列宽;OnParametersSet中还检测Grid.Column变化并同步重算,保证动态修改栅格配置即时生效。
响应式栅格示例(取自 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,
};
}
注意:断点阈值与 Layout Grid 的 Col 保持一致,即 xs <576px / sm ≥576px / md ≥768px / lg ≥992px / xl ≥1200px / xxl ≥1600px。
ListItem:操作组、额外内容与点击事件
ListItem 是列表项容器,参数定义于 ListItem.razor.cs:
| 参数 | 说明 |
|---|---|
Extra(RenderFragment) |
额外内容:ItemLayout 为 vertical 时展示在右侧,horizontal 时展示在最右侧 |
Actions(RenderFragment[]) |
操作组:vertical 布局下显示在底部,否则显示在最右侧 |
ChildContent(RenderFragment) |
列表项主体内容 |
OnClick(EventCallback) |
列表项点击回调,点击时通过 HandleClick 触发(ListItem.razor.cs) |
NoFlex(bool) |
是否不使用 flex 布局 |
渲染逻辑(ListItem.razor):
- 非栅格模式输出
<li class="ant-list-item">;栅格模式输出按列宽包裹的Col。 IsVerticalAndExtra(ItemLayout == Vertical && Extra != null)为真时,主体与Actions进入ant-list-item-main,Extra单独放在ant-list-item-extra;否则主体、操作组、额外内容顺序平铺。Actions以<ul class="ant-list-action">渲染,项之间用<em class="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>...</Footer>
</AntList>
点击事件示例(取自 Basic.razor):OnClick 是 EventCallback,可直接绑定到当前项:
<AntList DataSource="@data" TItem="BasicItem">
<ListItem OnClick="()=>ItemClick(context.Title)">
<ListItemMeta AvatarTemplate="avatar" Description="...">
<TitleTemplate><a href="https://ng.ant.design">@context.Title</a></TitleTemplate>
</ListItemMeta>
</ListItem>
</AntList>
ListItemMeta:头像、标题与描述
ListItemMeta 负责列表项的元信息展示,参数定义于 ListItemMeta.razor.cs:
| 参数 | 说明 | 优先级说明 |
|---|---|---|
Avatar(string) |
头像图片地址,渲染为 <Avatar Src="..."> |
AvatarTemplate 优先 |
AvatarTemplate(RenderFragment) |
自定义头像内容 | 优先于 Avatar |
Title(string) |
标题文本 | TitleTemplate 优先 |
TitleTemplate(RenderFragment) |
自定义标题(如超链接) | 优先于 Title |
Description(string) |
描述文本 | DescriptionTemplate 优先 |
DescriptionTemplate(RenderFragment) |
自定义描述 | 优先于 Description |
渲染结构为:头像区 ant-list-item-meta-avatar + 内容区 ant-list-item-meta-content(内含 ant-list-item-meta-title 的 <h4> 与 ant-list-item-meta-description),详见 ListItemMeta.razor。原文档中 avatar/title/description 的类型为 ReactNode,Blazor 实现通过"字符串 + 模板"双参数(Template 优先)覆盖了同样能力。
实战组合:完整页面示例
基础列表
直接使用 DataSource + ListItemMeta 组合(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 List<BasicItem> data = new() { new BasicItem { Title = "Ant Design Title 1" }, /* ... */ };
public void ItemClick(string title) => Console.WriteLine($"item was clicked: {title}");
}
带头部/底部与三种尺寸
Simple.razor 展示了 Bordered + Header/Footer + Size 的组合,可通过 Size="ListSize.Small"、Size="ListSize.Large" 快速切换紧凑/宽松样式。
栅格 + 卡片
Grid.razor 演示固定列数:new ListGridType { Gutter = 16, Column = 4 },每项内嵌 Card,适合"卡片墙"式后台页面。
加载更多
Loadmore.razor 演示完整加载更多流程:Loading 控制 Spin 状态,LoadMore 渲染按钮,点击后通过 HttpClient 拉取新数据并 AddRange 追加到 DataSource,最后重置 Loading。这是"滚动/点击加载更多"的标准写法。
拖拽排序
List 本身不内置拖拽,但 Draggable.razor 展示了基于 HTML5 draggable + @ondragstart/@ondrop 事件在列表项上实现拖拽重排的可行方案,data 变更后调用 StateHasChanged() 刷新。
样式机制与测试验证
样式体系
List 的样式由 style/index.less 定义,核心规则包括:列表项 flex 布局与 justify-content: space-between、ant-list-item-meta 的弹性布局、ant-list-item-action 操作组间距、垂直布局下 -main/-extra 的分栏结构,以及 responsive.less(style/responsive.less)中针对 ≤768px、≤576px 的换行与内边距适配。类名统一基于 ant-list 前缀,与组件 ClassMapper 生成的类一一对应。
单元测试佐证
仓库在 tests/AntDesign.Tests/List/List.Render.Tests.razor 提供了两项关键测试:
Render_basic_list:断言基础列表渲染出ant-list、ant-list-header、ant-list-spin-wrapper、ant-list-items、ant-list-item、ant-list-footer等完整 DOM 结构,验证了 Header/Footer/ChildContent 的组合输出。Grid_is_reacting_to_change:先以{Gutter=16, Column=4}渲染,再通过SetParametersAndRender改为{Gutter=8, Column=2},断言栅格列宽样式从变化前更新为width: 50%; max-width: 50%;,直接验证了OnParametersSet中的列宽重算逻辑。
小结
ant-design-blazor 的 List 组件以 AntList<TItem> 泛型容器 + ListItem + ListItemMeta 的组合,完整承接了 Ant Design 列表设计语言:横排/竖排布局、边框与分割线控制、三种尺寸、固定/响应式栅格、头部底部与加载更多区块、操作组与额外内容、点击回调等能力一应俱全。配合仓库内 demo 目录 的九个示例(基础、简单、垂直、栅格、响应式、加载更多、无限滚动、拖拽等),可以快速映射到后台管理页、数据概览页、消息列表等常见业务场景。需要注意的是,原文档中源自 React 版的 locale、rowKey 等参数在当前 Blazor 实现中尚未完全落地,使用时应以本仓库源码为准。