菜单:发现、显示、执行与配置
帮助菜单的键盘入口
按 Alt+H 展开帮助菜单,再按下表中的访问键。也可使用方向键选择、Enter 打开、Esc 返回;这些访问键属于菜单本身,不新增全局热键,也不覆盖用户保存的组合键配置。
| 入口 | 访问键 |
|---|---|
| 检查更新 | U |
| 关于 | A |
| 日志 | L |
| 商店 | P |
| 反馈 | F |
| Servicee Host | S |
| 通信 | C |
“通信”打开“Socket 连接管理器”。独立日志窗口的 Esc 先退出搜索,再关闭窗口。插件市场的 Esc 先收起详情,再关闭窗口。Socket 连接管理器的 Esc 先清除筛选,再关闭窗口。进入反馈窗口后可直接输入正文,多行输入保留 Enter 换行。关于窗口支持 Enter 确认关闭。检查更新的默认操作与忙碌门禁见更新窗口。
菜单接口在 ColorVision.Common,UI/ColorVision.UI/Menus/MenuManager.cs 为调用方提供的 WPF Menu 装配菜单树;UI/ColorVision.UI.Desktop/MenuItemManager/ 管理显示覆盖。三者分别负责扩展声明、运行时呈现和配置编辑,不接管菜单背后的设备、文件或业务事务。
主程序分别调用 LoadMenuForWindow(MainWindow, Menu1) 和 LoadHotKeyFromAssembly()。菜单显示、命令可执行、快捷键注册、搜索结果和业务完成是不同证据;不能通过隐藏一个入口来承诺操作已禁用。
发现来源和实例生命周期
EnsureTypeCaches 从 AssemblyHandler.GetAssemblies() 的缓存/过滤视图取得类型,并通过 GetTypes 读取可用类型。候选必须为非抽象、非开放泛型的 class,未直接标注 [Obsolete],且具有公共无参构造函数。仅仅“插件 DLL 已加载”不能证明类型满足这些条件或已进入该视图。
同一类型按以下优先级进入一条发现路径,不会因同时带特性而得到第二个菜单:
| 优先级 | 来源 | 何时构造、什么会被收录 |
|---|---|---|
| 1 | IMenuItem,包括 MenuItemBase | 每次创建目录时构造,Command != null 才收录;这一层不要求 Header 非空 |
| 2 | IMenuItemProvider | 每次构造 provider 并枚举结果;仅收录非 null、Command 和 Header 均非 null 的元数据 |
| 3 | 只标注 [MenuItem] 的类型 | Header 非 null 时建立懒 adapter;目标类到每次执行时才实例化 |
直接条目和 provider 的构造/枚举异常按类型记录日志后继续;provider 已产出的条目不会因后续枚举失败而统一撤回。调用方的 typeFilter 在构造前按声明类型筛选,provider 整体受筛选;TargetName 的窗口筛选则在条目创建之后。因此为某个窗口加载菜单仍可能先构造其它窗口的条目,构造函数不应被当作只在用户点击时执行。
类型缓存是一份不可变快照,AssemblyHandler.AssembliesChanged(登记新程序集、程序集集合变化的 RefreshAssemblies 或 ClearCaches)会丢弃它;与变化并发的扫描结果只用于本次调用,不写回缓存。RebuildAllMenus、RefreshMenuItemsByGuid 和 LoadMenuForWindow 在快照已丢弃时重新扫描,否则只用既有类型列表重新构造条目/provider。程序集刷新本身不会重建已显示的菜单,新插件菜单仍需宿主调用重建后才出现。
普通条目实例也不是 manager 为类型维护的永久单例;重复枚举、加载或刷新会产生新实例。菜单控件持有其 Tag/Command,但 manager 没有统一调用这些条目或 provider 的 Dispose。业务资源和订阅不应依赖“菜单重建会自动清理旧实例”。
窗口目标、标识与父子树
MenuItemBase 默认 TargetName=MainWindow、OwnerGuid=Menu、GuidId=类型简单名;GlobalMenuBase 改为 TargetName=Global。特性路径默认 Global,未指定 GuidId 时 adapter 实际使用类型 FullName,不是特性注释所说的简单类名。MenuItemMetadata 默认 GuidId 来自 new Guid(),即全零 GUID 字符串,不会自动生成随机唯一标识;provider 应提供稳定且不冲突的 ID。
LoadMenuForWindow(targetName, menu, typeFilter) 只选 TargetName 精确匹配或 Global 的条目。Global 表示参与这些已接入 manager 的菜单,不会自动给任意窗口添加菜单栏。
OwnerGuid=Menu才作为根项;其它项按有效 OwnerGuid 匹配父项 GuidId。没有对应父项的孤儿不会自动提升到顶层。- 同级按有效 Order 排序;子项与前一项的 Order 差大于 4 且当前项可见时插入分隔符,不代表业务分组语义。
- 树构建不按 GuidId 去重或合并。同一窗口中重复 ID 可能显示多个条目、重复挂载子树;沿当前路径遇到循环 ID 时只剪掉该分支,不能把剪枝当成冲突修复。
MenuItemScopeKey(TargetName, GuidId)用于覆盖与过滤身份,不是树节点的全局唯一性强制机制。作用域覆盖优先于旧 GuidId-only 覆盖,未覆盖时使用条目的原始值。
隐藏、刷新与控件状态
manager 的 FilteredGuids 是旧式跨目标过滤,ScopedFilteredItems 是按目标过滤。被过滤父项的后代按有效 OwnerGuid 递归过滤,父项匹配考虑同目标和 Global;排序/父级覆盖分别来自有效覆盖表。
这些过滤与 IMenuItem.Visibility 不同。CreateMenuItem 将 Header、Icon、Command、Visibility 和 IsChecked 复制到控件,没有为这些字段建立通用更新绑定,也不会把控件勾选回写给源条目。InputGestureText 通常也是复制值,只有 IHotKey 菜单通过专用适配跟随运行时组合,见下文。GetAllMenuItemsFiltered() 只应用上述 ID 过滤,不等于“当前窗口可见且可执行的菜单”:它可以包含其它目标、Collapsed 条目或没有父项的孤儿,且不检查 CanExecute。
| 刷新入口 | 实际影响范围 |
|---|---|
LoadMenuForWindow / RebuildAllMenus | 清空已注册 Menu 并重新建树;自身不清类型缓存,只在程序集变化后重扫。首次接管时备份已有顶层 MenuItem,重建后按 Header 去重追加这些原对象 |
RefreshMenuItemsByGuid(ownerGuid) | 每个已注册 Menu 只找第一个匹配 ID 的节点,清空并重建它的子项;不更新该节点自身的标题、可见性、Command,也不创建缺失的根节点 |
| Menu Unloaded 或所属 Window Closed | 注销该 Menu 的注册、事件和备份;再次装载控件不等于自动重新注册,需要调用方重新接入 |
注册保留原 TargetName 和 typeFilter。RebuildAllMenus 只处理仍注册的菜单,并不是刷新搜索索引、快捷键或所有自定义按钮的通用广播。IMenuService 只暴露按父 ID 刷新入口,宿主需先创建/注入 MenuManager。
执行、搜索与快捷键的边界
默认 MenuItemBase.Command 返回的 RelayCommand 在 CanExecute predicate 和实际调用 Execute 前都执行 AccessControl.Check(Execute)。因此直接调用这条默认命令也会重新决策,拒绝时不进入菜单 action;通用 RelayCommand.Execute 仍只直接执行自己的委托,其它条目也可返回完全不同的 ICommand。方法/声明类的权限特性及其稳定 ActionId 交给当前共享策略,精确范围见Common 命令契约与安全边界,不能从菜单是否变灰推导全部直接调用都被保护。
懒 adapter 保持目标类按执行时构造:注册时只读取无参 Execute() 及方法/类的权限元数据,不为 CanExecute 创建实例。其 predicate 和执行前检查同一动作、角色要求及 ResourceId;允许后才构造,实际调用前再执行 Demand。实例若实现 IMenuItem,还需其自身 Command 的 CanExecute 允许;否则反射调用公共或非公共的无参 Execute()。构造失败、缺少方法或同步调用异常会记录警告。反射返回值被忽略,返回 Task 时既不等待,也不观察其后续异步失败,因此菜单点击或返回不能作为异步业务完成信号。实现 IMenuItem 的类型在普通发现路径仍优先走直接适配,不会因再加 [MenuItem] 自动变成懒加载。
MenuSearchProvider 从 GetAllMenuItemsFiltered 再选取 TargetName=MainWindow/Global、自身 Visibility=Visible、Header/Command 非空的条目,排除 OwnerGuid=Menu 的顶层分组;它不是任意窗口菜单的统一入口,也没有重建菜单树来证明每个候选的父项实际可见。单项元数据读取失败记录警告并继续。结果通常保留原 ICommand,新增说明、别名和 CategoryKey=Commands;MenuClose 例外使用已有 CloseDocumentCommand,不再经依赖活动窗口的菜单适配器。菜单身份包含 TargetName/GuidId,已有 IHotKey 动作则按稳定 ActionId 关联当前键位,不通过显示名称猜测。
搜索界面对不可执行结果给出不可用状态,并在真正派发前检查 CanExecute;RoutedCommand 使用原业务宿主中的明确内容目标,不因独立搜索窗口变为活动窗口而改为保存搜索框或关闭搜索宿主。原内容隐藏或活动文档已切换时拒绝旧路由结果,关闭搜索后仍复核目标。候选刷新、焦点恢复、目标失效和同步异常边界归产品搜索契约。搜索通道的检查与默认 MenuItemBase 命令的执行检查分别负责各自边界,均不改变任意 RelayCommand 或直接方法调用的行为。菜单重建也不主动更新一个已经显示的搜索结果快照。
InputGestureText 仅为显示文字,不注册 Ctrl+X 等快捷键。HotkeyService 独立发现 IHotkeyProvider / IHotKey,还接收显式注册;它不读取菜单隐藏覆盖。已注册快捷键可能仍调用原操作,是否能执行继续取决于该回调自己的检查和热键注册状态。键位在独立的快捷键设置页编辑。
MenuManager 为实现 IHotKey 的现有菜单条目附加 HotkeyMenuGestureBinding:
- 只读取该条目的
HotKeys声明一次取得明确 ID;未提供 ID 的旧单动作 provider 按与热键发现相同的类型 FullName 规则匹配。不按 Header、Name 或菜单 GuidId 猜测,名称翻译、重名和菜单移动不改变关联。 - 弱订阅
HotkeyService.HotKeys的集合变化和匹配条目的Hotkey/AdditionalHotkeys属性,按顺序以/连接显示全部运行时组合。菜单先创建、随后加载热键、编辑附加组、删除首组、定义替换、清除与恢复默认都会更新提示;没有匹配运行时项或组合已全部清除时留空,不回退为可能失效的默认键位。 - 提示反映组合值,不以临时
IsRegistered变化闪烁;它不是操作系统注册成功的指示灯。适配本身不重新发现 provider、不注册热键、不执行业务回调。声明读取失败只记录警告并留空,不阻止菜单创建。 - 同时实现多动作
IHotkeyProvider的条目必须在其IHotKey声明中给出明确动作 ID,适配不会枚举所有动作选一个。非IHotKey菜单保留原始 InputGestureText。
订阅不把丢弃的 MenuItem 强引用留在运行时集合上,也不把子菜单弹出层的临时 Unloaded 当作永久解绑。此适配只属于 MenuManager 创建的控件,不改变 Common 层的 ToMenuItem() 扩展。
IRightMenuItemProvider 则由 MainWindow.InitRightMenuItemPanel 单独装配右侧按钮,不经 MenuManager 树和隐藏覆盖;其它地方直接使用 ToMenuItem() 也不能自动获得 manager 的配置规则。
菜单覆盖配置
MenuItemManagerInitialized 在启动时调用 MenuItemManagerService.ApplySettings(),加载 MenuItemManagerConfig.Overrides 中的 IsVisible、OrderOverride 和 OwnerGuidOverride。运行时覆盖有变化时重建菜单。
旧 Settings 会迁移到 Overrides。缺少 TargetName 的覆盖按匹配 GuidId 的窗口目标展开。非法父级或循环会跳过覆盖并记录日志。
菜单未按预期显示时
| 现象 | 检查顺序 |
|---|---|
| 加载插件后没有菜单 | 检查插件是否进入程序集发现视图、类型是否满足构造条件,再查发现日志和宿主重建入口 |
| 条目已被发现但菜单不可见 | 核对 TargetName、自身 Visibility、MenuItemManagerConfig.Overrides 和父级是否可达 |
| 隐藏菜单后快捷键仍有效 | 到独立快捷键设置查看该动作的绑定。菜单隐藏控制显示,不能用作禁用业务操作的权限措施 |
| 重启后显示与预期不符 | 核对配置文件中的 MenuItemManagerConfig、目标和父级覆盖,再查启动日志 |
