ant-design-blazor PageHeader 页头组件完全指南:参数详解、模块化布局与响应式实践
ant-design-blazor PageHeader 页头组件完全指南:参数详解、模块化布局与响应式实践
本文以 ant-design-blazor 仓库中的 PageHeader 官方文档 为主体,结合 PageHeader 组件源码、页面模板、主题样式 以及官方演示(Demo)代码,系统讲解 PageHeader 页头的定位、全部 API 参数、八大可插槽组成部分,并给出可直接复制使用的实战示例与源码级原理说明。
一、PageHeader 是什么:页头的定位与适用场景
页头(Page Header)位于页容器中、页容器顶部,起到内容概览和引导页级操作的作用。它通常由以下几类元素组成:
- 面包屑(导航路径)
- 标题(当前页面名称)
- 页面内容简介
- 页面级操作(如“新建”“导出”等按钮)
- 页面级导航(如页签、下拉菜单)
从组件分类看,PageHeader 在 ant-design-blazor 中属于**导航(Navigation)**类组件(见文档 frontmatter 的 type: 导航 字段)。
何时使用
根据官方文档的说明,PageHeader 适用于两类场景:
- 帮助用户快速理解当前页是什么:页头集中展示页面主题、关键信息与相关操作,使用户一进入页面就能建立认知;
- 方便用户使用页面功能:页头承担页面级操作入口和页面间导航职责,通常也可被用作页面间导航。
简单来说,当你的页面需要“一个明确的标题 + 若干关键操作 + 可能的面包屑/简介”时,PageHeader 就是最合适的骨架组件。
二、快速上手:标准页头的最小用法
最简示例
只需一行代码即可渲染一个标准页头:
<PageHeader Class="site-page-header" Title="Title" Subtitle="This is a subtitle" />
其中 Title 显示主标题,Subtitle 显示副标题。这是官方演示 Basic.razor 中的基础形态,适合“需要简单描述”的场景。
带返回按钮的标准用法
页头最常见的场景之一是从详情页返回列表页。PageHeader 内置返回按钮,默认行为是调用浏览器 history.back():
<PageHeader BackIcon="true" Class="site-page-header">
<PageHeaderTitle>Title</PageHeaderTitle>
<PageHeaderSubtitle>This is a subtitle</PageHeaderSubtitle>
<PageHeaderExtra>
<Button>Operation</Button>
<Button>Operation</Button>
<Button Type="ButtonType.Primary">Primary</Button>
</PageHeaderExtra>
<PageHeaderContent>
<Descriptions Size="DescriptionsSize.Small" Column="3">
<DescriptionsItem Title="Created" Span="1">Lili Qu</DescriptionsItem>
<DescriptionsItem Title="Association" Span="1"><a>421421</a></DescriptionsItem>
<DescriptionsItem Title="Creation Time" Span="1">2017-01-10</DescriptionsItem>
<DescriptionsItem Title="Effective Time" Span="1">2017-10-10</DescriptionsItem>
<DescriptionsItem Title="Remarks" Span="2">
Gonghu Road, Xihu District, Hangzhou, Zhejiang, China
</DescriptionsItem>
</Descriptions>
</PageHeaderContent>
</PageHeader>
三、API 参数详解
PageHeader 的核心参数不多,但每一个都直接决定页头的结构与行为。下表来自官方文档,并结合源码补充了说明:
| 参数 | 说明 | 类型 | 默认值 | 全局配置 |
|---|---|---|---|---|
Ghost |
使背景色透明 | boolean |
true |
- |
Title |
title 文字 | string | RenderFragment |
- | - |
Subtitle |
subTitle 文字 | string | RenderFragment |
- | - |
BackIcon |
自定义 back icon | bool? | string | RenderFragment |
- | - |
OnBack |
返回按钮的点击事件 | EventCallback |
未订阅该事件时默认调用 history.back | - |
下面逐一结合源码深入分析。
Ghost:控制背景透明度
Ghost 决定页头是否使用透明背景。默认情况下(文档标注默认值为 true)页头呈现透明底色;当需要页头拥有自己的背景色时,可显式设置 Ghost="false",此时会走组件默认的 background-color: @component-background(白底)。
官方演示 Ghost.razor 即为“白底模式”:
<div class="site-page-header-ghost-wrapper">
<PageHeader BackIcon="true" Ghost="false">
<PageHeaderTitle>Title</PageHeaderTitle>
<PageHeaderSubtitle>This is a subtitle</PageHeaderSubtitle>
<PageHeaderExtra>
<Button>Operation</Button>
<Button>Operation</Button>
<Button Type="ButtonType.Primary">Primary</Button>
</PageHeaderExtra>
<PageHeaderContent>
<Descriptions Size="DescriptionsSize.Small" Column="3">
<!-- ... -->
</Descriptions>
</PageHeaderContent>
</PageHeader>
</div>
在 PageHeader.razor.cs 的 SetClassMap() 中可以看到:
.ClassMapper
.Add("ant-page-header")
.If("ant-page-header-ghost", () => this.Ghost)
即 Ghost=true 时追加 ant-page-header-ghost 类,样式层在 index.less 中定义 background-color: @page-header-ghost-bg,主题默认值为 inherit(见 default.less 的 PageHeader 变量段),从而实现透明继承效果。需要说明的是:源码中 Ghost 属性本身的默认值为 false(bool 默认值),文档表格标注的默认值 true 与演示文案“默认 PageHeader 是透明底色”一致;当对背景有确定要求时,建议总是显式传入 Ghost,避免歧义。
Title / Subtitle:标题与副标题
Title 与 Subtitle 既支持普通字符串,也支持 RenderFragment 模板(对应参数 TitleTemplate / SubtitleTemplate,源码见 PageHeader.razor.cs)。在渲染优先级上,TitleTemplate(模板)优先于 Title(字符串);SubtitleTemplate 优先于 Subtitle。
页头模板中的渲染逻辑(PageHeader.razor)为:
@if (TitleTemplate != null || Title != null)
{
<span class="ant-page-header-heading-title">
@if (TitleTemplate != null)
@TitleTemplate
else
@Title
</span>
}
else
{
if (PageHeaderTitle != null)
{
<div class="ant-page-header-heading-title">
@PageHeaderTitle
</div>
}
}
注意:PageHeaderTitle / PageHeaderSubtitle 这两个旧的 RenderFragment 参数在源码中已被标记为 <a href="https://link.gitcode.com/i/94413461f41398b9c0e4b4ec47dfe928" target="_blank">Obsolete("Use TitleTemplate instead")](见 [PageHeader.razor.cs),官方演示为了兼容性仍在使用,新代码建议优先使用 Title / Subtitle 或 TitleTemplate / SubtitleTemplate。
BackIcon:自定义返回图标
BackIcon 支持三种形式(源码中对应 OneOf<bool?, string> 与 BackIconTemplate 两个参数,见 PageHeader.razor.cs):
bool:true表示显示默认的返回箭头(ArrowLeft);string:指定一个图标类型名,如IconType.Outline.Backward;RenderFragment(通过BackIconTemplate传入):完全自定义返回按钮内容。
模板中的渲染分支(PageHeader.razor)依次判断:有自定义模板 → 用模板;传了字符串图标 → 用该图标;否则 → 默认 ArrowLeft 箭头。返回按钮仅在 BackIconTemplate != null || BackIcon.Value != null || OnBack.HasDelegate 三者之一成立时才渲染。
OnBack:返回事件与默认行为
OnBack 是返回按钮的点击回调,类型为 EventCallback。源码中的处理逻辑(PageHeader.razor.cs)非常清晰:
private async Task OnBackClick(MouseEventArgs eventArgs)
{
if (OnBack.HasDelegate)
{
await OnBack.InvokeAsync(eventArgs);
}
else
{
await JsInvokeAsync("history.back");
}
}
即:订阅了 OnBack 时执行自定义回调;未订阅时自动调用浏览器 history.back(),与文档描述的默认行为完全一致。
四、八大组成部分:模块化插槽详解
除顶层参数外,PageHeader 还通过 8 个 RenderFragment 槽位(“组成部分”)支持自由组合内容。官方文档表格如下:
| 元素 | 说明 |
|---|---|
PageHeaderTitle |
title 部分,Title 优先级更高 |
PageHeaderSubtitle |
subtitle 部分,Subtitle 优先级更高 |
PageHeaderContent |
内容部分 |
PageHeaderFooter |
底部部分 |
PageHeaderTags |
title 旁的 tag 列表容器 |
PageHeaderExtra |
title 的行尾操作区部分 |
PageHeaderBreadcrumb |
面包屑部分 |
PageHeaderAvatar |
头像部分 |
页头的 DOM 骨架(PageHeader.razor)自上而下为:PageHeaderBreadcrumb(面包屑)→ heading 区(返回按钮 + PageHeaderAvatar + 标题/副标题 + PageHeaderTags + PageHeaderExtra)→ PageHeaderContent(内容区)→ PageHeaderFooter(页脚区)。
PageHeaderTitle / PageHeaderSubtitle
标题与副标题槽位,分别渲染到 ant-page-header-heading-title 和 ant-page-header-heading-sub-title 容器。如前文所述,Title/Subtitle 参数优先级高于这两个旧槽位,且后者已被标记过时。
PageHeaderBreadcrumb:面包屑
适合层级较深的页面,让用户快速导航。官方演示 PageHeaderBreadcrumb.razor:
<PageHeader Class="site-page-header" Title="Title" Subtitle="This is a subtitle">
<PageHeaderBreadcrumb>
<Breadcrumb>
<BreadcrumbItem>First-level Menu</BreadcrumbItem>
<BreadcrumbItem>
<a>Second-level Menu</a>
</BreadcrumbItem>
<BreadcrumbItem>Third-level Menu</BreadcrumbItem>
</Breadcrumb>
</PageHeaderBreadcrumb>
</PageHeader>
从样式上看,当存在面包屑时页头会追加 has-breadcrumb 类并收紧顶部内边距(@page-header-padding-breadcrumb,见 index.less)。
PageHeaderAvatar:头像
在标题前展示头像,常用于个人中心、项目主页等需要品牌/用户标识的场景:
<PageHeaderAvatar>
<Avatar Src="https://avatars0.githubusercontent.com/u/22736418?s=88&v=4" />
</PageHeaderAvatar>
PageHeaderTags:标签容器
紧跟在标题右侧,用于展示状态标签(如“Running”“Pending”):
<PageHeaderTags>
<Tag Color="TagColor.Blue">Running</Tag>
</PageHeaderTags>
PageHeaderExtra:行尾操作区
位于标题行最右侧,是页面级操作按钮的常规放置位置,可放置按钮、下拉菜单等:
<PageHeaderExtra>
<Button>Operation</Button>
<Button>Operation</Button>
<Button Type="ButtonType.Primary">Primary</Button>
<Dropdown Placement="Placement.BottomRight">
<Overlay>
<Menu>
<MenuItem>1st menu item</MenuItem>
<MenuItem>2nd menu item</MenuItem>
<MenuItem>3rd menu item</MenuItem>
</Menu>
</Overlay>
<ChildContent>
<Button><Icon Type="@IconType.Outline.Ellipsis" /></Button>
</ChildContent>
</Dropdown>
</PageHeaderExtra>
PageHeaderContent:内容区
标题下方的正文区,适合放置 Descriptions、Statistic、Row 等复杂信息,帮助用户快速了解页面信息:
<PageHeaderContent>
<Row>
<Statistic Title="Status" Value=@("Pending") />
<Statistic Title="Price" Value="568.08" Prefix="$" Style="margin: 0 32px" />
<Statistic Title="Balance" Value="3345.08" Prefix="$" />
</Row>
</PageHeaderContent>
PageHeaderFooter:底部页脚
页头底部区域,常与 Tabs 配合形成页签导航(详见下文“响应式示例”)。
五、组合示例:完整使用所有能力
官方演示 Content.razor 展示了同时使用面包屑 + 头像 + 标题 + 副标题 + 标签 + 操作区 + 内容区的全部能力,是理解 PageHeader 布局能力的完整范本(核心结构):
<PageHeader Class="site-page-header">
<PageHeaderBreadcrumb>
<Breadcrumb>
<BreadcrumbItem>First-level Menu</BreadcrumbItem>
<BreadcrumbItem><a>Second-level Menu</a></BreadcrumbItem>
<BreadcrumbItem>Third-level Menu</BreadcrumbItem>
</Breadcrumb>
</PageHeaderBreadcrumb>
<PageHeaderAvatar>
<Avatar Src="https://avatars0.githubusercontent.com/u/22736418?s=88&v=4" />
</PageHeaderAvatar>
<PageHeaderTitle>Title</PageHeaderTitle>
<PageHeaderSubtitle>This is a subtitle</PageHeaderSubtitle>
<PageHeaderTags>
<Tag Color="TagColor.Blue">Running</Tag>
</PageHeaderTags>
<PageHeaderExtra>
<Button>Operation</Button>
<Button>Operation</Button>
<Button Type="ButtonType.Primary">Primary</Button>
<Dropdown Placement="Placement.BottomRight">
<!-- ... -->
</Dropdown>
</PageHeaderExtra>
<PageHeaderContent>
<Row>
<!-- 内容区:段落 + 快捷入口链接 + 示意图 -->
</Row>
</PageHeaderContent>
</PageHeader>
六、响应式适配:不同屏幕尺寸下的表现
官方文档指出“在不同大小的屏幕下,应该有不同的表现”。PageHeader 的响应式能力由源码内置实现:
- 组件通过
ResizeObserver监听自身尺寸(PageHeader.razor); - 当容器宽度小于 768px 时,
OnResize回调将_isCompact置为true(PageHeader.razor.cs),并追加ant-page-header-compact类; - 紧凑模式下标题行允许换行(
flex-wrap: wrap,见 index.less)。
配合内容区的自定义媒体查询,即可实现完整的响应式页头。官方演示 Responsive.razor 将 Statistic 统计信息放入 PageHeaderContent、将 Tabs 放入 PageHeaderFooter,并通过 @@media (max-width: 576px) 在窄屏下将 flex 布局切换为块级布局:
<PageHeader BackIcon="true" Class="site-page-header">
<PageHeaderTitle>Title</PageHeaderTitle>
<PageHeaderSubtitle>This is a subtitle</PageHeaderSubtitle>
<PageHeaderExtra>
<Button>Operation</Button>
<Button>Operation</Button>
<Button Type="ButtonType.Primary">Primary</Button>
</PageHeaderExtra>
<PageHeaderContent>
<!-- Statistic 统计信息区 -->
</PageHeaderContent>
<PageHeaderFooter>
<Tabs DefaultActiveKey="1">
<TabPane Key="1">
<TabTemplate>Details</TabTemplate>
</TabPane>
<TabPane Key="2">
<TabTemplate>Rule</TabTemplate>
</TabPane>
</Tabs>
</PageHeaderFooter>
</PageHeader>
@@media (max-width: 576px) {
.pageheader-content {
display: block;
}
.pageheader-main {
width: 100%;
margin-bottom: 12px;
}
.pageheader-extra {
width: 100%;
margin-left: 0;
text-align: left;
}
}
说明:demo 中的
@@media是 Razor 转义写法,实际渲染为 CSS 的@media。
七、返回按钮的自定义组合:Basic 演示全览
官方演示 Basic.razor 集中展示了 BackIcon 与 OnBack 的四种组合,可作为返回按钮的速查参考:
@* 默认样式,无返回按钮 *@
<PageHeader Class="site-page-header" Title="@_title" Subtitle="This is a subtitle" />
<br />
@* 自定义 OnBack 回调 *@
<PageHeader Class="site-page-header" Title="@_title" Subtitle="Custom `OnBack` callback"
OnBack="@(()=> { Console.WriteLine("OnBack");})" />
<br />
@* 自定义返回图标(字符串形式) *@
<PageHeader Class="site-page-header" Title="@_title" Subtitle="Custom Icon"
BackIcon="@IconType.Outline.Backward" />
<br />
@* 自定义返回图标(RenderFragment 形式)+ OnBack 回调 *@
<PageHeader Class="site-page-header" Title="@_title" Subtitle="Custom Icon and `OnBack` callback"
BackIconTemplate="icon" OnBack="@(()=> { Console.WriteLine("OnBack");})" />
@code{
private string _title = "Title";
RenderFragment icon = @<Icon Type="@IconType.Outline.Backward" />;
}
可以看到:仅传 BackIcon="true" 显示默认箭头;传图标字符串则替换图标;需要完全自定义内容时用 BackIconTemplate 传入 RenderFragment;OnBack 决定点击行为。
八、源码级实现与主题定制
渲染结构与类名映射
PageHeader 继承自 AntDomComponentBase,通过 ClassMapper 在初始化时(OnInitialized)动态拼接类名(PageHeader.razor.cs):
.ClassMapper
.Add("ant-page-header")
.If("ant-page-header-compact", () => _isCompact) // 窄屏紧凑模式
.If("has-footer", () => PageHeaderFooter != null) // 有页脚
.If("ant-page-header-ghost", () => this.Ghost) // 透明背景
.If("has-breadcrumb", () => PageHeaderBreadcrumb != null) // 有面包屑
.If("ant-page-header-rtl", () => RTL); // RTL 方向
样式层在 index.less 中定义了标题(heading-title,加粗 600、@heading-4-size)、副标题(heading-sub-title,次要色)、内容区、页脚(内置 Tabs 的无边框导航适配)等样式,并对标题/副标题做了单行省略(text-overflow-ellipsis)处理。
主题变量定制
PageHeader 的全部尺寸与颜色均可在主题中定制,变量集中在 default.less:
// PageHeader
@page-header-padding: @padding-lg;
@page-header-padding-vertical: @padding-md;
@page-header-padding-breadcrumb: @padding-sm;
@page-header-content-padding-vertical: @padding-sm;
@page-header-back-color: #000;
@page-header-ghost-bg: inherit;
@page-header-heading-title: @heading-4-size;
@page-header-heading-sub-title: 14px;
@page-header-tabs-tab-font-size: 16px;
其中 @page-header-ghost-bg 在 dark.less 中被设为 transparent,在 compact.less 中标题字号被压缩至 16px、内边距收紧至 16px/8px,variable.less 与 default 保持一致。如果你在使用暗色或紧凑主题,PageHeader 会自动适配。
RTL 方向支持
当组件处于 RTL 环境时,会追加 ant-page-header-rtl 类,配套的 rtl.less 会翻转返回按钮、标题、头像、副标题、标签、操作区与页脚的方向与边距,实现完整的从右到左布局支持。
九、总结
PageHeader 是 ant-design-blazor 导航体系中“页级骨架”组件:五个核心参数(Ghost、Title、Subtitle、BackIcon、OnBack)控制基础行为,八大组成部分(PageHeaderBreadcrumb、PageHeaderAvatar、PageHeaderTitle、PageHeaderSubtitle、PageHeaderTags、PageHeaderExtra、PageHeaderContent、PageHeaderFooter)自由拼装内容,配合内置的 768px 断点响应式、主题变量定制与 RTL 支持,可覆盖从“简单描述”到“复杂信息 + 页面级操作 + 页签导航”的绝大多数页头场景。相关演示与文档位于 site/AntDesign.Docs/Demos/Components/PageHeader,读者可结合源码与示例进一步探索。