Ant Design Blazor Drawer 抽屉组件完全指南:声明式 API 与 DrawerService 命令式调用实战
Ant Design Blazor Drawer 抽屉组件完全指南:声明式 API 与 DrawerService 命令式调用实战
导读
本文围绕 Ant Design Blazor 组件库中的 Drawer(抽屉)组件展开,它是一块从屏幕边缘滑出的浮层面板,常用于承载表单、编辑信息或处理子任务,让用户无需离开当前页面即可完成操作。你将学会两种完整的用法:通过 Visible 双向绑定的声明式用法,以及通过 DrawerService.CreateAsync / CreateDialogAsync 创建的命令式用法;同时深入理解 DrawerOptions、DrawerRef 的每个参数,以及抽屉从打开到关闭背后的组件状态机与渲染管线。
什么时候使用 Drawer
从官方文档(index.en-US.md)的定义来看,Drawer 是一块典型的叠加在页面上方、从屏幕一侧滑入的面板,里面可以容纳一组信息或操作。由于用户不需要离开当前页面就能与 Drawer 交互,在相同上下文内完成任务的效率更高。官方推荐的典型场景包括:
- 使用表单创建或编辑一组信息:Drawer 内嵌 Form,避免整页跳转打断编辑流程;
- 处理子任务:当子任务对 Popover 来说太重、又希望子任务保持在主任务的上下文中时,Drawer 非常合适;
- 同一份表单在多个地方复用:通过命令式服务,可以在任意位置以同一套配置弹出相同的抽屉。
声明式用法:基础示例
最简单的使用方式是在页面中直接放置 <Drawer> 组件,并通过 @bind-Visible 双向绑定控制开关。以下是文档站示例(Basic.razor)的完整代码:
<div>
<Button Type="ButtonType.Primary" @onclick="_=>open()">Open</Button>
<Drawer Closable="true" @bind-Visible="visible" Placement="DrawerPlacement.Right" Title='("Basic Drawer")' OnClose="OnClose" OnOpen="OnOpen">
<p>Some contents...</p>
<p>Some contents...</p>
<p>Some contents...</p>
</Drawer>
</div>
@code{
bool visible = false;
void open()
{
this.visible = true;
}
void OnClose()
{
Console.WriteLine("closed");
}
void OnOpen()
{
Console.WriteLine("opened");
}
}
要点说明:
@bind-Visible是声明式用法的核心:外部将visible置为true时抽屉打开;用户点击关闭按钮或遮罩时,组件内部通过VisibleChanged事件把false回写给绑定变量;Placement使用枚举DrawerPlacement(DrawerPlacement.cs),可选Left、Top、Right、Bottom,默认Right;OnOpen/OnClose是打开完成与关闭时的回调,可用于日志埋点或触发后续逻辑。
Drawer 组件 API 详解
以下表格完整继承自官方文档,并结合 Drawer.razor.cs 的源码补充了类型与默认值的说明。
| Property | 说明 | Type | 默认值 |
|---|---|---|---|
| Title | 抽屉标题,支持字符串或模板 | OneOf<RenderFragment, string> |
- |
| BodyStyle | 抽屉内容区的样式(如 padding) | string |
- |
| HeaderStyle | 抽屉头部区域的样式(如高度、padding) | string |
- |
| Closable | 是否显示右上角关闭(x)按钮 | boolean |
true |
| ChildContent | 子内容 RenderFragment | RenderFragment |
- |
| Content | 抽屉内容;与 ChildContent 同时给出时显示在 ChildContent 上方 | OneOf<RenderFragment, string> |
- |
| MaskClosable | 点击遮罩(抽屉外区域)是否关闭抽屉 | boolean |
true |
| Mask | 是否显示遮罩;为 true 时 Visible 期间抽屉周围区域变暗 | boolean |
true |
| Placement | 抽屉出现位置:left、top、right、bottom |
string(源码中为 DrawerPlacement 枚举) |
right |
| Width | 抽屉宽度,仅 left / right 方向生效 |
string(文档标 int,源码为 string 像素值) |
256 |
| Height | 抽屉高度,仅 top / bottom 方向生效 |
string |
256 |
| ZIndex | 抽屉的 z-index | int |
1000 |
| OffsetX | X 坐标偏移(px),仅 left / right 生效 |
int |
0 |
| OffsetY | Y 坐标偏移(px),仅 top / bottom 生效 |
int |
0 |
| Visible | 抽屉是否可见 | boolean |
- |
| Keyboard | 是否支持 ESC 关闭(当前未实现) | boolean |
true |
| Handler | 作为抽屉内容兄弟元素渲染的内容 | RenderFragment |
- |
| OnClose | 用户点击遮罩、关闭按钮或取消按钮时触发的回调 | EventCallback |
- |
| OnOpen | 抽屉渲染完成后触发的回调 | EventCallback |
- |
| MaskStyle | 遮罩元素的样式 | string |
- |
| WrapClassName | 抽屉容器(content-wrapper)的类名 | string |
- |
源码实现中值得注意的几个细节:
- Width / Height 实际为字符串类型,通过
StyleHelper.ToCssPixel转换为 CSS 像素值(见 Drawer.razor.cs),因此可以直接传入"256"或"60%"这类带单位的值; - Title 与 Content 支持
OneOf<RenderFragment, string>,setter 内部通过value.Switch(...)分别路由到模板字段与字符串字段(Drawer.razor.cs);字符串内容在 Drawer.razor 中以MarkupString渲染为 HTML; - ZIndex 有特殊处理:当值等于默认的
1000时输出空样式,否则生成z-index: {n};;并且在抽屉处于关闭/动画结束后状态时强制输出z-index:-9999;,避免隐藏抽屉遮挡页面(Drawer.razor.cs)。
抽屉的滑入滑出动画原理
抽屉的“滑入滑出”效果不是依赖外部 JS,而是由组件自身根据 ComponentStatus 状态机计算 transform 实现的(Drawer.razor.cs):
- 打开状态:transform 为
null,抽屉停留在屏幕内; - 关闭状态:按方向分别输出
translateX(-100%)、translateX(100%)、translateY(-100%)、translateY(100%),把抽屉移出屏幕; - 动画时长
0.3s、缓动函数cubic-bezier(0.78, 0.14, 0.15, 0.86)在代码中定义为常量(Drawer.razor.cs)。
而 OffsetX / OffsetY 通过 OffsetTransform 属性生成对应方向的 translate 偏移,可以让抽屉在打开时停留在距离屏幕边缘指定像素的位置(Drawer.razor.cs)。文档站的 Offset.razor 演示了该用法。
命令式用法:DrawerService
当抽屉需要在多个页面、多个组件中被复用时,更适合用命令式方式创建。DrawerService 已在 AddAntDesign() 扩展方法中自动注册,无需手动配置 DI(ServiceCollectionExtensions.cs);在 Blazor Server 中注册为 Scoped、在 WebAssembly 中注册为 Singleton(取决于 RuntimeInformation.IsOSPlatform(OSPlatform.Create("BROWSER")) 的判断,见同一文件的 L43-L51)。
在组件中通过 @inject DrawerService DrawerService 注入后即可使用。文档站演示(Drawer_service.razor)提供了四种典型场景。
方式一:Fast Dialog Mode(快速对话框模式)
直接传参,一步完成创建、打开与结果等待:
private async Task OpenFastDialogMode()
{
var result = await DrawerService.CreateDialogAsync<DrawerTemplateDemo, string, string>(value, title: "Component", width: "350");
if (result != null)
value = result;
}
这个重载(DrawerService.cs)内部帮你组装了 DrawerOptions,支持 closable、maskClosable、title、width、mask、placement 等常用参数,适合快速弹出不需要精细定制的抽屉。
方式二:Dialog Mode(完整对话框模式)
使用 DrawerOptions 显式配置,再把参数传给组件:
private async Task OpenDialogMode()
{
var options = new DrawerOptions()
{
Title = "Component",
Width = "350",
};
var result = await DrawerService.CreateDialogAsync<DrawerTemplateDemo, string, string>(options, value);
if (result != null)
value = result;
}
方式三:组件模式(Component Mode)
CreateAsync<TComponent, TComponentOptions, TResult> 返回 DrawerRef<TResult>,通过它订阅关闭事件并接收返回值:
private async Task OpenComponent()
{
var options = new DrawerOptions()
{
Title = "Component",
Width = "350",
};
var drawerRef = await DrawerService.CreateAsync<DrawerTemplateDemo, string, string>(options, value);
drawerRef.OnClosed = async result =>
{
Console.WriteLine("OnAfterClosed:" + result);
if (result != null)
value = result;
await InvokeAsync(StateHasChanged);
};
}
方式四:纯模板内容模式(Content Mode)
不创建自定义组件,而是直接把 RenderFragment 作为 DrawerOptions.Content 传入:
private DrawerRef _drawerRef;
private async Task OpenContent()
{
RenderFragment content =@<div>
<Input @bind-Value="@value" /><br />
<Button OnClick="CloseDrawer">close</Button>
</div>;
var options = new DrawerOptions()
{
Title = "Drawer",
Width = "350",
Content = content,
};
_drawerRef = await DrawerService.CreateAsync(options);
_drawerRef.OnClosing = (handle) =>
{
Console.WriteLine("Closing Drawer");
return Task.CompletedTask;
};
}
private async Task CloseDrawer()
{
if (_drawerRef != null)
{
await _drawerRef.CloseAsync();
}
}
自定义抽屉模板组件
CreateAsync / CreateDialogAsync 的泛型组件参数要求继承 FeedbackComponent<TComponentOptions, TResult>,这样组件才能通过基类拿到传入的 Options 参数和 FeedbackRef 引用。文档站提供了完整的模板示例(DrawerTemplateDemo.razor):
@namespace AntDesign
@inherits FeedbackComponent<string, string>
<div>
value: <Input @bind-Value="value" />
<br/>
<br/>
<Button Type="ButtonType.Primary" OnClick="OnClose">Confirm</Button>
</div>
@code{
string value;
protected override void OnInitialized()
{
value = base.Options;
base.OnInitialized();
}
async Task OnClose()
{
DrawerRef<string> drawerRef = base.FeedbackRef as DrawerRef<string>;
await drawerRef!.CloseAsync(value);
}
}
关键点:
base.Options就是创建时传入的TComponentOptions(示例中的value),可在OnInitialized中取出初始化界面;base.FeedbackRef as DrawerRef<string>强转后调用CloseAsync(value),关闭抽屉的同时把value作为结果返回给调用方。
DrawerOptions 完整参数表
DrawerOptions 是命令式用法的配置载体,字段与 Drawer 组件参数一一对应(DrawerOptions.cs):
| Property | 说明 | Type | 默认值 |
|---|---|---|---|
| Content | 抽屉主体内容 | OneOf<RenderFragment, string> |
- |
| ContentParams | 组件的输入参数 / 模板上下文 | D |
- |
| Closable | 是否显示右上角关闭按钮 | boolean |
true |
| MaskClosable | 点击遮罩是否关闭 | boolean |
true |
| Mask | 是否显示遮罩 | boolean |
true |
| CloseOnNavigation | 导航历史变化时是否关闭抽屉 | boolean |
true |
| Keyboard | 是否支持 ESC 关闭 | boolean |
true |
| MaskStyle | 遮罩元素样式 | string |
{} |
| BodyStyle | 抽屉主体样式(高度、padding 等) | string |
{} |
| HeaderStyle | 抽屉头部样式 | string |
{} |
| Title | 抽屉标题 | OneOf<RenderFragment, string> |
- |
| Width | 抽屉宽度 | string(文档标 int) |
256 |
| Height | 抽屉高度,仅 top / bottom 生效 |
string |
256 |
| WrapClassName | 抽屉容器的类名 | string |
- |
| ZIndex | 抽屉的 z-index | int |
1000 |
| Placement | 出现方向:'top' | 'right' | 'bottom' | 'left' |
枚举 | 'right' |
| OffsetX | X 坐标偏移,仅 left / right 生效 |
int |
0 |
| OffsetY | Y 坐标偏移,仅 top / bottom 生效 |
int |
0 |
说明:
CloseOnNavigation与Keyboard已在 Options 中预留,其中 Keyboard 对应组件参数Keyboard,官方文档标注为“当前未实现”;CloseOnNavigation的行为可以从 DrawerContainer.razor.cs 得到佐证——容器监听了NavigationManager.LocationChanged,路由变化时会清空全部抽屉引用。
DrawerRef:抽屉的编程句柄
CreateAsync 系列方法返回 DrawerRef(或泛型 DrawerRef<TResult>),它是后续控制抽屉的句柄(DrawerRef.cs):
| Property / Method | 说明 |
|---|---|
| CloseAsync() | 关闭抽屉(触发 OnClosing,可通过 ModalClosingEventArgs.Cancel 取消) |
| OpenAsync() | 重新打开抽屉 |
| UpdateConfigAsync() | 更新当前配置并刷新已打开的抽屉 |
| UpdateConfigAsync(DrawerOptions config) | 以新配置覆盖后刷新 |
| Config | 当前抽屉的 DrawerOptions 配置(旧属性 Options 已标记 [Obsolete]) |
| OnClosing | 关闭前的回调,返回 Func<ModalClosingEventArgs, Task>,可取消关闭 |
| OnClosed(仅泛型) | 关闭后的回调,携带 TResult 结果 |
| CloseAsync(TResult result)(仅泛型) | 带结果关闭,并完成内部 TaskCompletionSource,让 CreateDialogAsync 的等待方拿到返回值 |
带结果关闭的实现逻辑位于 DrawerRef.cs:先触发 OnClosing 检查 Cancel 标志,未取消则调用服务的 CloseAsync、触发 OnClosed,最后 TaskCompletionSource.SetResult(result)——这正是 CreateDialogAsync 能 await 到结果的原因。
源码视角:DrawerService 的完整调用链
理解命令式用法的底层原理,可以帮你排查多抽屉场景下的异常。完整链路如下:
- 创建:
DrawerService.CreateAsync校验options非空,构造DrawerRef,泛型重载会用RenderFragment构建器把自定义组件挂载为ChildContent,并触发OnOpenEvent(DrawerService.cs); - 渲染:
DrawerContainer在初始化时订阅了OnOpenEvent/OnCloseEvent/OnUpdateEvent(DrawerContainer.razor.cs),收到事件后把DrawerRef加入内部列表,然后渲染出<Drawer>组件并逐项绑定DrawerOptions的属性(DrawerContainer.razor); - 关闭:用户点击关闭或调用
drawerRef.CloseAsync()时,DrawerContainer把Visible置为false,等待 300ms 动画完成后才把该DrawerRef从列表移除并再次刷新(DrawerContainer.razor.cs); - 导航清理:路由变化时
OnLocationChanged清空_drawerRefs,抽屉随页面切换自动回收。
组件自身的打开/关闭同样遵循状态机:Visible setter 在开关切换时把 _status 置为 Opening / Closing(Drawer.razor.cs),OnAfterRenderAsync 中再流转为 Opened / Closed,并依次调用 OnOpen / OnClose 回调和 VisibleChanged 双向绑定回写(Drawer.razor.cs)。这也是声明式用法中 @bind-Visible 能自动复位的原因。
延伸阅读
- 更多官方示例位于 site/AntDesign.Docs/Demos/Components/Drawer/demo:Placement.razor(四个方向)、Offset.razor(坐标偏移)、Formindrawer.razor(抽屉内嵌表单)、Multiple.razor(多抽屉叠加)、DropdownInDrawer.razor(抽屉内下拉菜单);
- 中文版组件文档:index.zh-CN.md;
- 抽屉样式定义位于 components/drawer/style,如需自定义主题可在此基础上覆盖 Less 变量;
- 抽屉的反馈组件基类(
FeedbackComponent)与消息、模态框共用同一套机制,学习 components/core/Feedback 目录可掌握FeedbackRefBase的通用设计。