Ant Design Blazor Drawer 抽屉组件完全指南:声明式 API 与 DrawerService 命令式调用实战

原创2026-10-09 14:46:052,189 阅读
文章标签:前端UI组件设计系统WebAssembly

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 的完整调用链

理解命令式用法的底层原理,可以帮你排查多抽屉场景下的异常。完整链路如下:

  1. 创建:DrawerService.CreateAsync 校验 options 非空,构造 DrawerRef,泛型重载会用 RenderFragment 构建器把自定义组件挂载为 ChildContent,并触发 OnOpenEvent(DrawerService.cs);
  2. 渲染:DrawerContainer 在初始化时订阅了 OnOpenEvent / OnCloseEvent / OnUpdateEvent(DrawerContainer.razor.cs),收到事件后把 DrawerRef 加入内部列表,然后渲染出 <Drawer> 组件并逐项绑定 DrawerOptions 的属性(DrawerContainer.razor);
  3. 关闭:用户点击关闭或调用 drawerRef.CloseAsync() 时,DrawerContainer 把 Visible 置为 false,等待 300ms 动画完成后才把该 DrawerRef 从列表移除并再次刷新(DrawerContainer.razor.cs);
  4. 导航清理:路由变化时 OnLocationChanged 清空 _drawerRefs,抽屉随页面切换自动回收。

组件自身的打开/关闭同样遵循状态机:Visible setter 在开关切换时把 _status 置为 Opening / Closing(Drawer.razor.cs),OnAfterRenderAsync 中再流转为 Opened / Closed,并依次调用 OnOpen / OnClose 回调和 VisibleChanged 双向绑定回写(Drawer.razor.cs)。这也是声明式用法中 @bind-Visible 能自动复位的原因。

延伸阅读

登录后查看全文
ant-design-blazor