Known · 元数据驱动的 .NET 全栈框架

说明

面向 AI 助手“斜杠命令 / @ 提及”的建议弹出菜单组件，纯展示、不依赖任何浏览器 API，由宿主决定何时展开并驱动键盘导航。Items 为 SuggestionItem 列表（Key / Label / Icon / Description / Hint / Group / Disabled，另有只读的 Id = Key 优先、留空回退 Label），标题、说明、快捷键提示、分组名一律视为业务内容、直接展示不本地化。Open（默认 false）为总开关，宿主在输入命中触发符（如 /）时置真、失焦或 Esc 时置假；Keyword 非空时对 Label / Description / Hint 做不区分大小写的“包含”过滤、留空显示全部（组件内部与宿主共用公开静态方法 Suggestion.Match(items, keyword)，保证可见集合一致，便于宿主按同一集合做上下键导航）。相邻同 Group 的项只在该组首行上方渲染一次组标题。ActiveKey 支持 @bind-ActiveKey 双向绑定：宿主用 ↑ / ↓ 改它驱动高亮，鼠标悬停 / 选中也会经 ActiveKeyChanged 反馈；禁用项置灰、不可选、导航应跳过。选中经 OnSelect 回传命中的 SuggestionItem（组件本身不改输入，回填由宿主完成）。Title（作为翻译键）给出顶部标题，Loading 显示骨架行，无匹配显示 EmptyText（默认“无匹配结果”、作为翻译键）。面板为普通文档流卡片（带描边阴影、内部滚动），定位交由宿主包裹层，便于做成向上弹出的命令面板；外观走 CSS 令牌接入框架明暗主题，常与 Sender / Attachments 组合。

常见能力：

Open 由宿主控制展开，Keyword 对 Label/Description/Hint 做不区分大小写包含过滤、留空显示全部
公开静态 Match(items, keyword) 供宿主与组件共用，键盘导航可见集合与面板完全一致
@bind-ActiveKey 双向高亮：宿主 ↑/↓ 驱动，鼠标悬停/选中经 ActiveKeyChanged 反馈
Group 分组标题（相邻同组只渲染一次）、Disabled 置灰不可选且导航跳过
每行 Icon + Label + Description + 右侧 Hint 快捷键徽标，选中经 OnSelect 回传
Loading 骨架行、EmptyText 空态（默认“无匹配结果”），Title 作为翻译键
纯展示、无 JS 互操作，定位交宿主包裹层；命令文本视为业务数据不本地化，明暗主题随 CSS 令牌适配

用法

<Suggestion Items="@_items" Open="@_open" Keyword="@_kw"
            Title="快捷指令" @bind-ActiveKey="_active" OnSelect="Pick" />

@code {
    List<SuggestionItem> _items = new()
    {
        new("新建数据模型", "database") { Key = "model", Group = "常用", Description = "生成实体与字段", Hint = "/model" },
        new("生成管理页面", "layout") { Key = "page", Group = "常用", Description = "列表 + 表单 + 详情", Hint = "/page" },
    };
    bool _open; string _kw = ""; string _active;
    void OnInput(string v) { _open = v.StartsWith("/"); _kw = _open ? v[1..] : ""; }
    void Pick(SuggestionItem it) { _cmd = "/" + it.Label + " "; _open = false; }
}

API 参数

参数	类型	默认值	说明
`ActiveKey`	`string`	`null`	外部驱动的高亮项 Key（配合 @bind-ActiveKey 双向绑定）。宿主用键盘上下键改变它。
`ActiveKeyChanged`	`EventCallback<string>`	—	事件
`EmptyText`	`string`	`"无匹配结果"`	空态文本（作为翻译键）。默认“无匹配结果”（复用既有键）。
`Items`	`List<SuggestionItem>`	`null`	建议项数据。标题 / 说明 / 提示 / 分组视为业务内容、直接展示不本地化。
`Keyword`	`string`	`null`	过滤关键字。非空时按标题 / 说明 / 提示做不区分大小写的“包含”匹配；留空显示全部。
`Loading`	`bool`	`false`	加载态：显示骨架行。默认 false。
`OnSelect`	`EventCallback<SuggestionItem>`	—	事件选中某一项的回调（鼠标点击或悬停经 ActiveKeyChanged 反馈高亮）。
`Open`	`bool`	`false`	是否展开显示。默认 false；一般由宿主在输入命中触发符（如 “/”）时置为 true。为 false 时不渲染。
`Title`	`string`	`null`	顶部标题（作为翻译键）。留空则不显示。
`Visible`	`bool`	`true`	取得或设置组件是否可见，默认为false。
`VisibleChanged`	`EventCallback<bool>`	—	事件取得或设置组件可见性变化时的回调事件。
`Class`	`string`	`null`	取得或设置组件的CSS类名，用于自定义样式。
`Disabled`	`bool`	`false`	取得或设置组件是否禁用，默认为false。
`Style`	`string`	`null`	取得或设置组件的内联样式，用于自定义样式。

所有组件均继承 BaseComponent，除上表参数外还支持 Class、Style、Disabled、Visible。