ant-design-blazor List 列表组件完全指南:基础渲染、栅格响应式、分页与加载更多实战
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}");
}
}
这里有几个关键点需要理解:
context上下文变量:ListItem、ListItemMeta等子组件通过CascadingValue(级联值)从AntList拿到当前迭代元素。在 AntList.razor 中,遍历DataSource时每个元素都会包一层<CascadingValue Value="this" IsFixed>,并把ChildContent(item)作为渲染内容,因此模板里可以直接用context访问当前条目数据。TItem显式指定:当DataSource的类型无法从属性推断(例如List<BasicItem>赋值给IEnumerable<TItem>)时,需要显式写出TItem="BasicItem"。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-borderedSize=Large→ant-list-lg;Size=Small→ant-list-sm(SizeCls 映射)ItemLayout=Vertical→ant-list-verticalLoading=true→ant-list-loadingGrid != 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,最终组合出适合你业务形态的列表方案。