顶栏自定义功能

顶栏右上角除了内置的搜索、刷新、全屏、通知与头像下拉，还留了一个可扩展槽位： 宿主通过 Config.AddTopAction 集中声明一次，凡使用 AdminLayout 或 TopBar 的页面都会自动出现这个功能按钮， 不必在每个页面重复挂载。这与 Config.AddMenuGroup 是同一套「声明 + 引用」理念——只声明一次，按 id 引用。

三种形态

AddTopAction 支持三种点击行为，按优先级择一生效：

三者可只给其一；同时给出时优先级为 component > handler > url。

最小声明

在应用启动配置里（AddKnown 之后）登记即可：

// 命令式处理器须先注册进 DI
services.AddScoped<FeedbackAction>();

// 三种形态各举一例
Config.AddTopAction("quick",    "快捷面板", icon: "layout",        component: typeof(FeedbackPanel),  order: 5);
Config.AddTopAction("feedback", "意见反馈", icon: "star",          handler:   typeof(FeedbackAction), order: 10);
Config.AddTopAction("docs",     "帮助文档", icon: "external-link", url:       "https://known.org.cn",  order: 20);

公共参数含义：

• id：功能唯一标识。相同 id 再次调用会覆盖前一次（幂等），便于模块 / 插件重复登记。
• name：按钮 tooltip 与面板标题，可作为国际化 key。
• icon：对应 Icon 组件的 Type；留空回退为 more。
• order：同级排序，越小越靠前；所有自定义功能整体排在内置工具按钮（刷新 / 全屏 / 通知 / 头像）之前。

命令式 handler

实现 ITopAction，从构造函数注入所需服务。TopBar 会从 DI 解析该类型，因此它必须已注册：

public sealed class FeedbackAction(UIService UI) : ITopAction
{
    public Task ExecuteAsync()
    {
        UI.Success("感谢反馈！顶栏自定义功能已触发。");
        return Task.CompletedTask;
    }
}

下拉面板 component

component 指向一个可渲染的 Razor 组件。点击图标会展开一个锚定浮层，内部用 DynamicComponent 渲染它。 面板组件由渲染器实例化，[Inject] 服务照常解析，无需把组件类型注册进 DI：

@namespace KnownApp

<div class="demo-panel">
    <p>这是一块由宿主注册的顶栏下拉面板，内容完全自定义。</p>
    <button class="btn btn-primary" @onclick="Ping">点我试试</button>
</div>

@code {
    [Inject] private UIService UI { get; set; }
    private void Ping() => UI.Success("面板里的按钮生效了。");
}

面板的展开 / 收起、点击外部自动关闭都由底层 Dropdown 组件内置处理（见 Dropdown），宿主无需再接任何 JS。

按角色显隐

roles 是逗号分隔的可见角色，语义与 [Menu].Roles 一致：留空则所有已登录用户可见， 否则要求当前登录用户的角色命中其一。当前用户由 AdminLayout 透传给 TopBar 的 User 参数参与判定。

// 仅 admin 与 manager 可见
Config.AddTopAction("audit", "审计日志", icon: "shield", url: "/audit", roles: "admin,manager");

常见坑

• handler 忘了注册进 DI → 点击时解析不到实例，功能无反应。handler 类型必须 AddScoped / AddSingleton。
• 以为要逐页给 TopBar 传参 → 不用。AddTopAction 写进启动配置一次，全站 AdminLayout / TopBar 自动出现。
• 面板里点了导航项浮层不关 → 落在浮层"内部"的点击不会触发外部关闭；若你在面板里放了导航项，用 Dropdown 的 Close() 主动收起（见组件文档）。
• 想调整与内置按钮的相对顺序 → 内置按钮固定在自定义项之后，自定义项之间靠彼此 order 排序。

相关

• 顶栏与整体骨架的组合，见布局组合。
• 下拉浮层的点击外部关闭与样式复用，见 Dropdown 组件文档。