ant-design-blazor Layout 布局组件完全指南:页面级布局容器、侧边栏与响应式导航
ant-design-blazor Layout 布局组件完全指南:页面级布局容器、侧边栏与响应式导航
导读
Layout 是 ant-design-blazor 中负责页面级整体布局的组件族,由 Layout、Header、Sider、Content、Footer 五个相互协作的容器组成,基于 flex 布局实现。本指南以官方组件文档(index.zh-CN.md)为骨架,结合仓库源码(components/layout)与 9 个真实 demo 示例,完整讲解设计尺寸规范、嵌套规则、全部 API 参数、响应式断点机制、侧边栏收起与自定义 trigger 的实现原理,并给出可直接复制运行的上中下、侧边、顶部-侧边等经典布局代码,帮助你在 Blazor 项目中快速搭建高可用页面骨架。
设计规则:尺寸、交互与视觉
在动手写代码之前,先理解 Layout 背后的设计规范,这些规则直接决定了导航栏的高度、宽度与强调样式的选择。
尺寸
一级导航项偏左靠近 logo 放置,辅助菜单偏右放置。尺寸遵循以下量化约定:
- 顶部导航(大部分系统):一级导航高度
64px,二级导航高度48px。 - 顶部导航(展示类页面):一级导航高度
80px,二级导航高度56px。 - 顶部导航高度的范围计算公式:
48 + 8n。 - 侧边导航宽度的范围计算公式:
200 + 8n。
从源码可以印证这些约定:Sider 展开宽度默认值为 200(见 Sider.razor.cs),正是公式 200 + 8n 中 n=0 的基础档位;收起宽度默认 80(Sider.razor.cs)。
交互
- 一级导航和末级的导航需要在可视化的层面被强调出来;
- 当前项应该在呈现上优先级最高;
- 当导航收起的时候,当前项的样式自动赋予给它的上一个层级;
- 左侧导航栏的收放交互同时支持手风琴和全展开的样式,根据业务的要求进行适当的选择。
交互规则对应到实现上:Sider 收起时会向内部 Menu 通知 CollapseUpdated,由菜单自身切换内联/收起态样式,因此 Sider 收起时内部 Menu 会自动联动切换为 ant-menu-inline-collapsed 样式(该行为由 Sider.razor.cs 的 AddMenu 方法建立关联,并在 ToggleCollapsed 中同步触发)。
视觉
导航样式上需要根据信息层级合理的选择样式:
- 大色块强调:建议用于底色为深色系时,当前页面父级的导航项。
- 高亮火柴棍:当导航栏底色为浅色系时使用,可用于当前页面对应导航项,建议尽量在导航路径的最终项使用。
- 字体高亮变色:从可视化层面,字体高亮的视觉强化力度低于大色块,通常在当前项的上一级使用。
- 字体放大:
12px、14px是导航的标准字号,14 号字体用在一、二级导航中。字号可以考虑导航项的等级做相应选择。
组件概述与嵌套规则
Layout 组件族包含 5 个成员,各有明确的定位与约束:
Layout:布局容器,其下可嵌套HeaderSiderContentFooter或Layout本身,可以放在任何父容器中。Header:顶部布局,自带默认样式,其下可嵌套任何元素,只能放在Layout中。Sider:侧边栏,自带默认样式及基本功能,其下可嵌套任何元素,只能放在Layout中。Content:内容部分,自带默认样式,其下可嵌套任何元素,只能放在Layout中。Footer:底部布局,自带默认样式,其下可嵌套任何元素,只能放在Layout中。
注意:采用 flex 布局实现,请注意浏览器兼容性问题(caniuse 查询结果为 flex 的支持范围)。
如果需要添加应用内的标签页,请搭配 ReuseTabs 组件使用,即仓库中的 ReuseTabs 文档。
嵌套关系的源码级印证
从源码看,组件族的协作机制非常清晰:
Layout渲染为<section>,默认类名为ant-layout(Layout.razor、Layout.razor.cs),并通过<CascadingValue Value="this" IsFixed="true">将自身级联给所有子组件,供内部的Sider反向注册。Header渲染为<header>,类名ant-layout-header(Header.razor)。Content渲染为<main>,类名ant-layout-content(Content.razor)。Footer渲染为<footer>,类名ant-layout-footer(Footer.razor)。Sider渲染为<aside>,类名以ant-layout-sider开头(Sider.razor)。
关键点:Sider 在 OnInitialized 时调用 Parent?.HasSider()(Sider.razor.cs),这会通知父级 Layout 设置 _hasSider = true 并为其追加 ant-layout-has-sider 类(Layout.razor.cs)。这就是 Layout 上 hasSider 参数的作用机制——当存在 Sider 子元素时,外层容器会自动获得 ant-layout-has-sider 类,用于调整布局的 flex 方向。
API 详解
典型的基础用法如下:
<Layout>
<Header>header</Header>
<Layout>
<Sider>left sidebar</Sider>
<Content>main content</Content>
<Sider>right sidebar</Sider>
</Layout>
<Footer>footer</Footer>
</Layout>
Layout:布局容器
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| className | 容器 className | string | - |
| hasSider | 表示子元素里有 Sider,一般不用指定。可用于服务端渲染时避免样式闪动 | boolean | - |
| style | 指定样式 | object | - |
| ChildContent | 容器内容 | RenderFragment | - |
Layout.HeaderLayout.FooterLayout.ContentAPI 与Layout相同(即都支持 className、style、ChildContent)。
在 Blazor 组件库中,className 与 style 继承自 AntDomComponentBase 基类,通过 ClassMapper 合并到渲染元素的 class 属性上(见 Layout.razor.cs)。hasSider 一般无需手动指定,因为 Sider 挂载时会自动触发 HasSider();手动指定主要服务于服务端渲染(SSR)场景,避免首屏样式闪动。
Layout.Sider:侧边栏
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| breakpoint | 触发响应式布局的断点 | xs | sm | md | lg | xl | xxl |
- |
| className | 容器 className | string | - |
| collapsed | 当前收起状态 | boolean | - |
| collapsedWidth | 收缩宽度,设置为 0 会出现特殊 trigger | number | 80 |
| collapsible | 是否可收起 | boolean | false |
| defaultCollapsed | 是否默认收起 | boolean | false |
| reverseArrow | 翻转折叠提示箭头的方向,当 Sider 在右边时可以使用 | boolean | false |
| style | 指定样式 | object | - |
| theme | 主题颜色 | light | dark |
dark |
| trigger | 自定义 trigger,设置为 null 时隐藏 trigger | string | ReactNode | - |
| width | 宽度 | number | string | 200 |
| onCollapse | 展开-收起时的回调函数,有点击 trigger 以及响应式反馈两种方式可以触发 | (collapsed, type) => {} | - |
| onBreakpoint | 触发响应式布局断点时的回调 | (broken) => {} | - |
| zeroWidthTriggerStyle | 指定当 collapsedWidth 为 0 时出现的特殊 trigger 的样式 |
object | - |
需要特别注意参数在 Blazor 版本中的落地差异:
collapsed是双向绑定的核心状态,推荐使用@bind-Collapsed="boolValue"写法,也可通过CollapsedChanged回调接收变化;OnCollapse在源码中已标注<a href="https://link.gitcode.com/i/b6ec5cd46bc1d422c3a00b70acc5f288" target="_blank">Obsolete],建议使用CollapsedChanged([Sider.razor.cs)。trigger对应源码中的RenderFragment Trigger,未设置时会自动生成默认箭头图标(展开时为左箭头、收起时为右箭头,RTL 方向自动翻转,见 Sider.razor.cs)。NoTrigger是 Blazor 版补充参数:移除手动收起的 trigger,搭配外部自定义按钮使用(demo CustomTrigger.razor 即采用该方案)。collapsedWidth设为 0 时会渲染一个特殊的零宽 trigger(ant-layout-sider-zero-width-trigger),点击后 Sider 以悬浮方式展开(见 Sider.razor)。width在源码中为int类型、默认 200;渲染时通过内联样式flex: 0 0 Wpx; max-width: Wpx; min-width: Wpx; width: Wpx固定宽度(Sider.razor.cs)。
breakpoint width:断点取值
{
xs: '480px',
sm: '576px',
md: '768px',
lg: '992px',
xl: '1200px',
xxl: '1600px',
}
在仓库中,断点被定义为 BreakpointType 枚举并直接映射为像素值(BreakpointType.cs):Xs = 480、Sm = 576、Md = 768、Lg = 992、Xl = 1200、Xxl = 1600。Sider 的响应式判断即 windowWidth < (int)Breakpoint(见下方"响应式机制"一节)。
经典布局模式(含完整可运行代码)
文档站点为每种布局模式都提供了完整 demo,以下按场景逐一给出。
基本结构
典型的页面布局,对应 demo Basic.razor:
<Layout>
<Header>Header</Header>
<Content>Content</Content>
<Footer>Footer</Footer>
</Layout>
<Layout>
<Header>Header</Header>
<Layout>
<Sider>Sider</Sider>
<Content>Content</Content>
</Layout>
<Footer>Footer</Footer>
</Layout>
<Layout>
<Header>Header</Header>
<Layout>
<Content>Content</Content>
<Sider>Sider</Sider>
</Layout>
<Footer>Footer</Footer>
</Layout>
<Layout>
<Sider>Sider</Sider>
<Layout>
<Header>Header</Header>
<Content>Content</Content>
<Footer>Footer</Footer>
</Layout>
</Layout>
通过调整 Layout 与 Sider 的相对位置,可以组合出"上中下""左中右"等全部基础形态;Layout 支持无限嵌套,任意父容器中都可以使用。
上中下布局(顶部导航)
demo Top.razor 展示了最基本的"上-中-下"布局:主导航放在页面顶端,从左至右依次为 logo、一级导航项、辅助菜单(用户、设置、通知等)。内容通常置于固定宽度(如 1200px)内,整页排版稳定、不受终端显示器影响;由于导航栏水平空间有限,不适合一级导航项很多的场景。
<Layout Class="layout">
<Header>
<div class="logo" />
<Menu Theme="MenuTheme.Dark" Mode="MenuMode.Horizontal" DefaultSelectedKeys=@(new[]{"2"})>
<MenuItem Key="1">nav 1</MenuItem>
<MenuItem Key="2">nav 2</MenuItem>
<MenuItem Key="3">nav 3</MenuItem>
</Menu>
</Header>
<Content Style="padding: 0 50px;">
<Breadcrumb Style="margin: 16px 0;">
<BreadcrumbItem>Home</BreadcrumbItem>
<BreadcrumbItem>List</BreadcrumbItem>
<BreadcrumbItem>App</BreadcrumbItem>
</Breadcrumb>
<div class="site-layout-content">Content</div>
</Content>
<Footer Style="text-align: center; ">Ant Design ©2018 Created by Ant UED</Footer>
</Layout>
侧边布局(可收起 Sider)
demo Side.razor 是侧边两列式布局,页面横向空间有限时侧边导航可收起。侧边导航模式层级扩展性强,一、二、三级导航项可以更流畅、更具关联性地展示,并可固定,便于用户在操作浏览中快速定位与切换;代价是牺牲一部分横向内容空间。
<Layout Style="min-height: 100vh; ">
<Sider Collapsible>
<div class="logo" />
<Menu Theme="MenuTheme.Dark" DefaultSelectedKeys=@(new[]{"1"}) Mode="MenuMode.Inline">
<MenuItem Key="1">
<Icon Type="@IconType.Outline.PieChart" />
<span>Option 1</span>
</MenuItem>
<MenuItem Key="2">
<Icon Type="@IconType.Outline.Desktop" />
<span>Option 2</span>
</MenuItem>
<SubMenu Key="sub1" TitleTemplate=sub1Title>
<MenuItem Key="3">Tom</MenuItem>
<MenuItem Key="4">Bill</MenuItem>
<MenuItem Key="5">Alex</MenuItem>
</SubMenu>
</Menu>
</Sider>
<Layout Class="site-layout" >
<Header Class="site-layout-background" Style="padding: 0;" ></Header>
<Content Style="margin:0 16px;" >
<Breadcrumb Style="margin:16px 0;">
<BreadcrumbItem>User</BreadcrumbItem>
<BreadcrumbItem>Bill</BreadcrumbItem>
</Breadcrumb>
<div class="site-layout-background" style="padding: 24px; min-height: 360px">
Bill is a cat.
</div>
</Content>
<Footer Style="text-align:center">Ant Design ©2018 Created by Ant UED</Footer>
</Layout>
</Layout>
要点:Sider Collapsible 开启收起能力后,底部会自动渲染 trigger(默认箭头图标);菜单在 Sider 收起时会联动进入内联收起态。
顶部-侧边布局与通栏版
- 顶部-侧边布局(TopSide.razor):拥有顶部导航及侧边栏的页面,多用于展示类网站(如文档站)。结构为顶层
Layout内先Header,Content内再嵌套一层Layout,其中左侧为Sider、右侧为内容。 - 顶部-侧边布局-通栏(TopSide2.razor):同样拥有顶部导航及侧边栏,区别是两边未留边距,多用于应用型网站。
两者的关键差异在 Content 的 Style 是否留左右 padding:TopSide 使用 padding: 0 50px,TopSide2 则将内层 Layout 直接通栏,仅用 padding: 0 24px 24px 控制内部间距。完整代码分别见两个 demo 文件。
响应式侧边栏:断点与双向绑定
demo Responsive.razor 演示了 Sider 的响应式收起能力:
<Layout>
<Sider Breakpoint="BreakpointType.Lg"
CollapsedWidth="64"
@bind-Collapsed=@collapsed>
<div class="logo" />
<Menu Theme="MenuTheme.Dark" Mode="MenuMode.Inline" DefaultSelectedKeys=@(new[]{"4"})>
<MenuItem Key="1">
<Icon Type="@IconType.Outline.User" />
<span class="nav-text">nav 1</span>
</MenuItem>
<MenuItem Key="2">
<Icon Type="@IconType.Outline.VideoCamera" />
<span class="nav-text">nav 2</span>
</MenuItem>
</Menu>
</Sider>
<Layout>
<Header Class="site-layout-sub-header-background" Style="padding: 0;" ></Header>
<Content Style=" margin: 24px 16px 0;">
<div class="site-layout-background" style="padding: 24px; min-height: 360px">
content
</div>
</Content>
<Footer Style="text-align: center;">Ant Design ©2018 Created by Ant UED</Footer>
</Layout>
</Layout>
@code {
bool collapsed;
}
响应式机制源码解析(Sider.razor.cs):
- 首次渲染后若设置了
Breakpoint,Sider 通过 JS 互操作读取窗口宽度(JSInteropConstants.GetWindow),并注册全局window.resize监听; - 窗口尺寸变化时执行
OnResize→OptimizeSize,判断逻辑为windowWidth < (int)Breakpoint(断点值即 BreakpointType.cs 中枚举的像素值); - 一旦低于断点:自动收起(
_isCollapsed = true)并显示 trigger(_showTrigger = true);高于断点则自动展开; - 状态变化会同步触发
OnBreakpoint(传入 broken 状态)、CollapsedChanged/OnCollapse回调,并通知内部 Menu 联动切换。
因此 Breakpoint="BreakpointType.Lg" 的含义是:窗口宽度小于 992px 时 Sider 自动收起,收起宽度为 CollapsedWidth="64"。
收起、自定义 trigger 与零宽 Sider
自定义 trigger:把折叠按钮移到 Header
demo CustomTrigger.razor 展示了如何隐藏 Sider 自带的底部 trigger,改由 Header 中的图标按钮控制:
<Layout>
<Sider @bind-Collapsed=@collapsed NoTrigger OnCollapse="OnCollapse">
<div class="logo" />
<Menu Theme="MenuTheme.Dark" Mode="MenuMode.Inline" DefaultSelectedKeys=@(new[]{"1"})>
<MenuItem Key="1">
<Icon Type="@IconType.Outline.User" />
<span>nav 1</span>
</MenuItem>
</Menu>
</Sider>
<Layout Class="site-layout">
<Header Class="site-layout-background" Style="padding: 0;">
@if (collapsed)
{
<Icon Type="@IconType.Outline.MenuUnfold" Class="trigger" OnClick="toggle" />
}
else
{
<Icon Type="@IconType.Outline.MenuFold" Class="trigger" OnClick="toggle" />
}
</Header>
<Content Class="site-layout-background" Style="margin: 24px 16px;padding: 24px;min-height: 280px;">
Content
</Content>
</Layout>
</Layout>
@code {
bool collapsed;
void toggle()
{
collapsed = !collapsed;
}
void OnCollapse(bool isCollapsed)
{
Console.WriteLine($"Collapsed: {isCollapsed}");
}
}
这里 NoTrigger 负责移除默认底部 trigger,@bind-Collapsed 让 Sider 与 collapsed 字段双向同步,Header 中的图标点击 toggle() 即可完成展开/收起。Sider 收起时内部 Menu 会随之切换为内联收起样式,无需额外代码。
collapsedWidth=0 的特殊 trigger
当 CollapsedWidth 设置为 0 时,Sider 收起后宽度为 0,此时 Sider 底部会自动渲染一个零宽 trigger(类名 ant-layout-sider-zero-width-trigger,含 bars 图标),点击后以悬浮方式展开侧边栏(渲染逻辑见 Sider.razor)。测试用例 LayoutTests.razor 通过 InlineData(0, ...) 覆盖了该场景,验证收起前后零宽 trigger 的出现与隐藏行为,其中 NoTrigger 会同时禁用常规 trigger 与零宽 trigger。
固定布局:固定 Header 与固定 Sider
Layout 组件本身不提供"固定"开关,而是通过 Style 配合 CSS 定位实现:
- 固定 Header(Fixed.razor):给
Header设置position: fixed; z-index: 1; width: 100%,同时给Content增加margin-top: 64px(对应一级导航高度),避免内容被遮挡。 - 固定 Sider(FixedSider.razor):给
Sider设置overflow: auto; height: 100vh; position: fixed; left: 0,同时给右侧内容区Layout设置margin-left: 200px(对应 Sider 展开宽度),实现侧边栏随页面滚动固定、内容区独立滚动的经典后台布局。
这两组 demo 完整展示了如何组合 CSS 定位与 Layout 组件,将导航从文档流中抽出并固定,适合内容超长、需要持续导航定位的后台管理页面。
测试验证与实现要点
仓库为 Layout 提供了完整的 bUnit 测试(tests/AntDesign.Tests/Layout/LayoutTests.razor),可验证本文涉及的诸多行为:
Render_basic_layout:断言Layout渲染为section.ant-layout,Header为header.ant-layout-header ant-header,Content为main.ant-layout-content,Footer为footer.ant-layout-footer;Rener_basic_layout_with_sider:断言包含 Sider 的内层Layout自动获得ant-layout-has-sider类,且 Sider 渲染为aside.ant-layout-sider ant-layout-sider-dark,宽度内联样式为flex: 0 0 200px; ...width: 200px;Render_layout_sider_collapsible:点击.ant-layout-sider-trigger后collapsed变为 true,Sider 增加ant-layout-sider-collapsed类,宽度变为 80px 且追加overflow: initial,Menu 获得ant-menu-inline-collapsed类——完整覆盖"点击 trigger 收起 + 菜单联动"链路;Render_layout_sider_no_trigger:验证NoTrigger与CollapsedWidth=0两种组合下 trigger 的渲染行为,并通过OnResize模拟窗口变窄触发断点收起。
这些测试同时印证了 Sider 宽度计算(Sider.razor.cs)与响应式判断(windowWidth < (int)Breakpoint)的实现细节,可作为你排查自定义布局问题的参考入口。
小结
Layout 组件族是 ant-design-blazor 页面级布局的基石:五个容器基于 flex 与级联机制协作,Sider 通过 Parent.HasSider() 反向通知 Layout 追加 ant-layout-has-sider 类;Breakpoint 与 @bind-Collapsed 组合即可获得开箱即用的响应式侧边栏;NoTrigger、Trigger、CollapsedWidth=0 则提供了从默认箭头到自定义按钮再到零宽悬浮触发的完整收起交互方案。掌握本文的设计规范与 API 细节后,即可像 demo 目录(site/AntDesign.Docs/Demos/Components/Layout/demo)中的 9 个示例一样,自由组合出上中下、侧边、顶部-侧边、固定导航等任意页面骨架。