UI组件跨平台桌面应用【免费下载链接】Terminal.GuiCross Platform Terminal UI toolkit for .NET项目地址https://gitcode.com/gh_mirrors/te/Terminal.Gui点击查看免费下载导读Shortcut是 Terminal.Gui 中承载命令文本 帮助文本 快捷键的单行复合控件是Menu、MenuBar、StatusBar、Bar等菜单体系的共同基石。本文基于 docfx/docs/shortcut.md 展开并结合 Terminal.Gui/Views/Shortcut.cs、Terminal.Gui/ViewBase/View.Command.cs 等源码与 单元测试 深入剖析其命令系统参与方式、BubbleDown 转发模式、七条典型命令流以及如何用CheckBox、Button、ColorPicker16等替换CommandView实现一处点击、一处状态变更的用户体验。读完本文你将能独立实现自定义CommandView、精确控制 Activate/Accept/HotKey 三条命令路径并理解其与FlagSelector、OptionSelector在设计取舍上的差异。一、认识 Shortcut从用户视角出发一个 Shortcut 是菜单、工具栏或状态栏中可点击的一行它同时展示三样东西┌─────────────────────────────────────────────────┐ │ [CommandView] [HelpView] [KeyView] │ │ _Open File Opens a file CtrlO │ └─────────────────────────────────────────────────┘CommandView默认位于左侧命令文本与热键下划线字母例如_Open File中的OHelpView默认位于中间命令的辅助说明文本KeyView默认位于右侧绑定的键盘快捷键例如CtrlO。在 Shortcut.cs 的构造器 中可以看到Shortcut默认将MouseHighlightStates设为MouseState.In鼠标悬停时高亮、CanFocus设为true并隐藏边框标题其宽度为Dim.Auto (DimAutoStyle.Content)高度为Dim.Auto (DimAutoStyle.Content, 1)即天然随内容自适应。从用户角度一个 Shortcut 应当满足以下期望点击 Shortcut 上任意位置都能激活它切换复选框、调用动作等按键盘快捷键KeyView 中显示的CtrlO产生同样效果无论焦点在哪按热键CommandView 中带下划线的字母产生同样效果Shortcut 获得焦点时按Space激活它Shortcut 获得焦点时按Enter接受它确认/执行每次交互恰好产生一次状态变更——点击带 CheckBox 的 Shortcut 只切换一次绝不切换两次。这一单控件体验正是整个设计围绕的核心命题。CommandView 变体CommandView可以是任意 ViewShortcut会自动适配不同 CommandView 的激活行为CommandView 类型Activate 行为Accept 行为View默认调用Action调用ActionCheckBox切换选中状态并调用Action调用Action不切换状态Button调用Action调用 Button 自身的 AcceptColorPicker16打开取色对话框或循环切换调用Action单一职责原则从用户视角看Shortcut 是一个控件。它内部包含 CommandView、HelpView、KeyView 三个子视图只是实现细节。无论用户点击命令文本、帮助文本、快捷键文本还是三者之间的空隙结果必须一致。后续的所有命令路由设计BubbleDown、事件冒泡、Action 调用都是为了维护这个单一控件的错觉。二、设计命令及其语义Shortcut通过标准的 Command 系统 参与交互只涉及三个命令命令触发方式作用Command.ActivateSpace、鼠标点击、Shortcut.Key按键变更状态例如切换 CheckBox并调用ActionCommand.AcceptEnter、双击确认/执行不改变状态调用ActionCommand.HotKeyCommandView 中的热键字母、Shortcut.Key先设置焦点再触发Command.Activate从 Command.cs 的枚举定义 可以看出Accept 1、HotKey 2、Activate 3是基础 View 命令且每个成员带有冻结的整数 ABI 契约——因此任何新增命令都必须追加编号绝不能插入或重排。CommandsToBubbleUpShortcut在构造器中设置 CommandsToBubbleUp [Command.Activate, Command.Accept]。这使 CommandView 等子视图发出的Activate、Accept命令能够冒泡到 Shortcut由 Shortcut 统一处理。关于冒泡的底层实现可参阅 View.Command.cs 中的 TryBubbleUp 与GetBubbleAncestor框架会沿 SuperView 链向上查找CommandsToBubbleUp包含该命令的祖先并转发。三、BubbleDown 模式复合视图的命令下派因为 Shortcut 是复合视图它必须在自身与 CommandView 之间协调命令流。核心模式如下用户与 Shortcut 交互点击、按键等命令到达Shortcut.OnActivating或Shortcut.OnAcceptingShortcut通过 BubbleDown 把命令向下转发给 CommandViewCommandView 处理命令例如 CheckBox 切换状态BubbleDown 抑制再次冒泡防止无限循环Shortcut 触发自身事件并调用Action。源码中的 Relay Dispatch 实现在源码层面这一BubbleDown由**中继分发Relay Dispatch**机制实现。Shortcut重写了两个钩子// Terminal.Gui/Views/Shortcut.cs protected override View? GetDispatchTarget (ICommandContext? ctx) CommandView; // ConsumeDispatch 默认为 false —— CommandView 自行完成自己的激活 // 例如 CheckBox.OnActivated 调用 AdvanceCheckState 切换状态在 View.Command.cs 的 TryDispatchToTarget 中中继分发的核心逻辑为重入保护ctx?.Routing CommandRouting.DispatchingDown时不再次分发防止无限递归对应文档中IsBubblingDown true抑制再冒泡的语义桥接保护来自非包含边界如 SubMenu → 父 MenuItem的桥接命令不向下分发程序化调用保护ConsumeDispatch false且ctx?.Binding is null即无用户交互的程序化InvokeCommand不向下分发来源保护IsSourceWithinView (target, ctx)为真命令已来自 CommandView 自身或其子视图时不分发直接返回。也就是说何时 BubbleDown在源码中收敛为两条守护命令必须来自用户交互绑定且绑定来源不能已经在 CommandView 内部。何时 BubbleDown何时不Shortcut是否把命令转发给 CommandView规则如下仅当满足以下两个条件时才 BubbleDown 到 CommandView - 命令带有 Binding即来自用户交互而非程序化 InvokeCommand - 且 Binding.Source 不是 CommandView即命令并非已经来自 CommandView由此产生三条路径来源有 BindingBinding.SourceBubbleDown原因CommandView 点击/按键是CommandView否CommandView 已处理命令经CommandsToBubbleUp冒泡上来Shortcut/HelpView/KeyView 点击或 Shortcut.Key 按键是Shortcut或 HelpView/KeyView是CommandView 尚未看到该命令程序化 InvokeCommand()否null不适用否没有可转发的用户交互四、核心实现解析OnActivatingprotected override bool OnActivating (CommandEventArgs args) { if (base.OnActivating (args)) { return true; } // 仅当存在 Binding 且来源不是 CommandView 时才 BubbleDown if (args.Context?.Binding is { Source: { } source } source ! CommandView) { return BubbleDown (CommandView, args.Context) is null; } return false; }OnAccepting 行为文档中描述的OnAccepting与OnActivating采用相同的 BubbleDown 判定逻辑转发Accept到 CommandView 后再经OnAccepted调用Actionprotected override bool OnAccepting (CommandEventArgs args) { if (base.OnAccepting (args)) { return true; } // 与 OnActivating 相同的 BubbleDown 逻辑 if (args.Context?.Binding is { Source: { } source } source ! CommandView) { return BubbleDown (CommandView, args.Context) is null; } return false; } protected override void OnAccepted (ICommandContext? ctx) Action?.Invoke ();重要演进说明当前 Shortcut.cs 中的 OnAccepting 在文档描述的基础上增加了一个关键细节——当Accept来自键盘绑定如 Enter时会先转换为Command.Activate再向下分发。源码注释解释了原因Enter 表示激活该项而非提交。转换后命令会经由 MenuItem → Menu → CommandBridge → PopoverMenu 的桥接架构流动从而正确收起菜单否则 Accept 会冒泡越过菜单层级直达宿主视图触发非预期的退出行为。而无绑定的程序化InvokeCommand(Accept)仍按正常路径流动这与文档结论一致。OnActivated 行为激活成功完成未被取消后OnActivated调用Actionprotected override void OnActivated (ICommandContext? ctx) { base.OnActivated (ctx); Action?.Invoke (); }当前源码版本在此基础上还会把传入命令通过ctx.WithCommand (Command)翻译为Shortcut.Command所指定的命令并调用InvokeOnTargetOrApp若设置了 TargetView则在该目标视图上调用InvokeCommand (Command, ctx)否则若Key有效则通过App?.Keyboard.InvokeCommandsBoundToKey (Key)调用应用级绑定命令。BubbleActivatedUp完成后通知当命令完成激活无论走常规路径还是 ConsumeDispatch 之后框架沿 SuperView 链向上遍历对通过CommandsToBubbleUp订阅的祖先触发RaiseActivated。这保证了两点中继分发路径如带 CheckBox 的 ShortcutCheckBox 完成状态变更如切换后BubbleActivatedUp在复合祖先Shortcut上触发RaiseActivated确保Action看到的是更新后的状态消费分发路径如带 OptionSelector/FlagSelector 的 MenuItemOptionSelector 消费命令并更新值后BubbleActivatedUp沿整条链MenuItem → Menu → SuperView触发RaiseActivated实现全链路通知。五、七条典型命令流流程 1点击 CommandView用户点击 CommandView 区域用户点击 CommandView → CommandView.InvokeCommand(Activate) [来自鼠标绑定] → CommandView.RaiseActivating() → CommandView.Activating 事件触发 → TryBubbleUpToSuperView (Shortcut 在 CommandsToBubbleUp 中包含 Activate) → Shortcut.InvokeCommand(Activate) [IsBubblingUptrue] → Shortcut.OnActivating(args) → args.Context.Binding.Source CommandView → 跳过 BubbleDown → return false → Shortcut.Activating 事件触发 → CommandView.RaiseActivated() → CommandView 在此处变更状态例如 CheckBox 切换 → Shortcut.RaiseActivated() → Action?.Invoke()结果CommandView 激活一次Shortcut 事件触发Action 被调用。流程 2点击 HelpView / KeyView / Shortcut 背景由于 Shortcut 默认MouseHighlightStates MouseState.In它会拦截整个区域的鼠标事件点击被归属到 Shortcut 自身用户点击 Shortcut而非 CommandView → Shortcut.InvokeCommand(Activate) [来自鼠标绑定, SourceShortcut] → Shortcut.RaiseActivating() → Shortcut.OnActivating(args) → args.Context.Binding.Source Shortcut不是 CommandView→ BubbleDown! → BubbleDown(CommandView, ctx) → CommandView.InvokeCommand(Activate) [IsBubblingDowntrue] → CommandView.RaiseActivating() → TryBubbleUpToSuperView: IsBubblingDowntrue → 跳过 → CommandView.RaiseActivated() → 状态在此处变更例如 CheckBox 切换 → Shortcut.Activating 事件触发 → Shortcut.RaiseActivated() → Action?.Invoke()结果CommandView 经 BubbleDown 激活一次Shortcut 事件触发Action 被调用。流程 3按 Shortcut.Key例如 CtrlO用户按下 Shortcut.Key → Shortcut.InvokeCommand(HotKey) [来自 HotKeyBinding, Binding.SourceShortcut] → Shortcut.DefaultHotKeyHandler(ctx) → RaiseHandlingHotKey(ctx) → HandlingHotKey 事件 → SetFocus()若 CanFocus → RaiseHotKeyCommand(ctx) → HotKeyCommand 事件 → InvokeCommand(Activate, ctx.Binding) [透传原始 binding] → Shortcut.RaiseActivating() → Shortcut.OnActivating(args) → args.Context.Binding.Source Shortcut → BubbleDown! → BubbleDown(CommandView, ctx) → CommandView 激活状态变更 → Shortcut.Activating 事件触发 → Shortcut.RaiseActivated() → Action?.Invoke()关键细节DefaultHotKeyHandler调用InvokeCommand(Activate)时透传ctx.Binding保留绑定来源使OnActivating能识别这是用户发起的交互并 BubbleDown 到 CommandView。流程 4按 CommandView 的热键字母例如_Open的 AltO用户按下 CommandView 的热键字母 → CommandView.InvokeCommand(HotKey) [来自 HotKeyBinding] → CommandView.DefaultHotKeyHandler(ctx) → RaiseHandlingHotKey → CommandView 上的 HandlingHotKey 事件 → SetFocus()若 CanFocus → RaiseHotKeyCommand → InvokeCommand(Activate, ctx.Binding) [SourceCommandView] → CommandView.RaiseActivating() → 冒泡到 ShortcutActivate 在 CommandsToBubbleUp 中 → Shortcut.OnActivating: Binding.Source CommandView → 跳过 BubbleDown → CommandView.RaiseActivated() → 状态变更 → Shortcut.RaiseActivated() → Action?.Invoke()流程 5按 SpaceShortcut 获得焦点用户按下 SpaceShortcut 拥有焦点 → Shortcut.InvokeCommand(Activate) [来自 KeyBinding, SourceShortcut] → 与流程 2 相同BubbleDown 到 CommandView流程 6按 EnterShortcut 获得焦点用户按下 EnterShortcut 拥有焦点 → Shortcut.InvokeCommand(Accept) [来自 KeyBinding, SourceShortcut] → Shortcut.RaiseAccepting() → Shortcut.OnAccepting(args) → Binding.Source Shortcut → BubbleDown(CommandView, Accept) → CommandView 处理 Accept → Shortcut.Accepting 事件触发 → Shortcut.RaiseAccepted() → Action?.Invoke()结合上文重要演进说明Enter 场景在现网源码中实际是Accept 由键盘绑定触发 → 转换为 Activate → 下派从而保证 CheckBox 也能正确切换、菜单能正确收起。流程 7程序化 InvokeCommand代码调用 shortcut.InvokeCommand(Command.Activate) → Shortcut.RaiseActivating() → Shortcut.OnActivating(args) → args.Context.Binding null → 跳过 BubbleDown → return false → Shortcut.Activating 事件触发 → Shortcut.RaiseActivated() → Action?.Invoke()结果Action 被调用但 CommandView不会变更状态。这是有意设计程序化调用若想改变 CommandView 状态应直接调用commandView.InvokeCommand(Command.Activate)。这一点被测试 CheckBox_CanFocus_False_Direct_InvokeCommand_Does_Not_Change_State 与CheckBox_CanFocus_True_Direct_InvokeCommand_Does_Not_Change_State明确验证直接shortcut.InvokeCommand (Command.Activate)不会转发到 CheckBox复选框保持UnChecked而直接对 CheckBox 调用checkBox.InvokeCommand (Command.Activate)则会切换状态——测试注释还澄清了CanFocus只控制键盘焦点不控制状态变更能力。六、MouseHighlightStates 与事件路由Shortcut 默认MouseHighlightStates MouseState.In鼠标悬停时高亮并拦截整个区域的鼠标事件。使用默认值 MouseState.In点击Shortcut 任意位置都归属到Shortcut 自身Binding.Source是 Shortcut路径BubbleDown 到 CommandView流程 2。改为 MouseState.None点击 CommandView 归属到CommandViewBinding.Source是 CommandView路径从 CommandView 冒泡上来跳过 BubbleDown流程 1点击 HelpView/KeyView 归属到对应视图再冒泡到 Shortcut。两条路径殊途同归CommandView 恰好激活一次Shortcut 事件触发Action 被调用。这正是单一控件体验在鼠标路由层面的保障。七、事件汇总Shortcut 上的事件供 SuperView 订阅者使用事件触发时机可否取消HandlingHotKey按下Shortcut.Key时可以Activating激活流程中可以Activated激活成功后随后调用Action否Accepting触发Command.Accept时可以Accepted接受成功后随后调用Action否CommandView 上的事件直接订阅时事件触发时机说明ActivatingCommandView 激活时每次交互触发一次ActivatedCommandView 激活后CheckBox 在此处变更状态CheckBox 特有事件事件触发时机CheckedStateChanging状态切换前可取消CheckedStateChanged状态切换后八、Action 属性Action在两处被调用OnActivatedCommand.Activate成功完成后OnAcceptedCommand.Accept成功完成后。这意味着无论 Shortcut 是被激活Space/点击还是被接受EnterAction都会触发。九、实战How To根据来源区分激活处理在Activating事件处理器中使用args.Context.TryGetSource()判断用户是直接与 CommandView 交互还是与 Shortcut 其他区域交互Shortcut shortcut new () { Key Key.F9, HelpText Cycles BG Color, CommandView bgColor }; shortcut.Activating (_, args) { if (args.Context.TryGetSource (out View? source) source shortcut.CommandView) { // 用户直接点击了 CommandView —— 不设置 Handled // 让 CommandView 的 OnActivated 运行例如按鼠标位置取色。 return; } // 用户按了 F9 或点击了 Shortcut 的其他区域 —— 循环切换颜色。 args.Handled true; bgColor.SelectedColor; };用 CheckBox 作为 CommandViewShortcut shortcut new () { Key Key.F6, CommandView new CheckBox { Text Force 16 Colors } }; // 订阅 CheckBox 的状态变更 ((CheckBox)shortcut.CommandView).CheckedStateChanged (_, args) { bool isChecked args.CurrentValue CheckState.Checked; // 对状态变更做出反应 }; // 或者订阅 Shortcut 的 Action 做简单回调 shortcut.Action () DoSomething ();实战参考UICatalog 的 Shortcuts 场景Examples/UICatalog/Scenarios/Shortcuts.cs 提供了大量可直接运行的组合用法其中包括带 CheckBox 与组合键的 ShortcutKey.F5.WithCtrl.WithAlt.WithShift并在ValueChanging事件中响应状态变更对齐按键开关BindKeyToApplication true的应用级快捷键Key.F1无论焦点在哪都能触发Activated事件弹出MessageBox通过AlignmentModes动态切换布局在 CheckBox 的ValueChanged中批量修改窗口内所有 Shortcut 的AlignmentModes.EndToStart标志实现命令文本在左/在右的实时切换Keyless / 无命令的 Shortcut验证 HelpView、KeyView 为空时ShowHide ()自动隐藏子视图的布局行为见 Shortcut.ShowHide。十、设计原理为什么需要 BubbleDown如果没有 BubbleDown点击 HelpView 或 KeyView 区域就不会切换 CheckBox 型 CommandView 的状态。BubbleDown 确保所有用户对 Shortcut 的交互都能到达 CommandView从而维持单一控件的错觉。为什么要检查 Binding.Source三路检查是否有绑定来源是否是 CommandView是否程序化调用防止两类问题双重处理CommandView 触发 Activate 冒泡到 Shortcut 后Shortcut 不能再 BubbleDown 回 CommandView否则会无限循环/双重切换非预期副作用对 Shortcut 的程序化InvokeCommand()不应隐式改变 CommandView 状态——调用方应当显式操作。为什么 Accept 不调用 ActivateAccept与Activate是两种语义截然不同的动作Activate 与控件交互切换、选择、变更状态Accept 确认/执行提交、关闭菜单、运行命令。在 Menu 这类复合视图中混淆二者会引发混乱MenuItem 上的Accept应执行命令并关闭菜单而Activate只负责高亮/聚焦该项。与 SelectorBase / FlagSelector 的对比FlagSelector是另一个使用 BubbleDown 的复合视图但语义刻意不同维度ShortcutFlagSelector检查依据Binding.SourceContext.Source经TryGetSource程序化调用跳过 BubbleDownBubbleDown 到获得焦点的 checkbox来自子视图跳过已处理跳过已处理来自自身BubbleDown 到 CommandViewBubbleDown 到获得焦点的 checkbox为何存在差异FlagSelector是 N 个等价 checkbox 的容器程序化InvokeCommand(Activate)天然意味着切换焦点项而Shortcut是只含一个 CommandView 的复合体程序化调用应只触发 Shortcut 自身的事件与 Action而不隐式改变 CommandView 状态——想改变状态应直接调用commandView.InvokeCommand(Activate)。在源码层面两者的差异体现在 FlagSelector.cs 与 OptionSelector.cs 均重写了GetDispatchTarget并设置ConsumeDispatch true消费分发而 Shortcut 走的是ConsumeDispatch false的中继分发。正如 View.Command.cs 的注释 所述中继分发对无绑定的程序化调用不向下派发消费分发则会把程序化命令转发给焦点子视图。OptionSelector则走了完全不同的路线它订阅 checkbox 的Activating事件手动调用InvokeCommand(Command.Activate, args.Context)作用于自身绕开了 BubbleDown 模式。源码中留有 TODO注明这种手动方案本不该需要。十一、测试与验证本仓库的 ShortcutTests.Command.cs共 1054 行系统验证了上述行为可以作为行为契约的权威参考CheckBox_CanFocus_False/True_Changes_State_On_Direct_Activate直接对 CheckBox 调用 Activate 必然切换状态与 CanFocus 无关CheckBox_CanFocus_False/True_Direct_InvokeCommand_Does_Not_Change_State对 Shortcut 直接调用InvokeCommand(Activate)不转发给 CommandView鼠标点击 CheckBox CommandView 时状态变更的用例验证了 CheckBox 用LeftButtonClicked → Command.Activate覆盖基类LeftButtonReleased绑定、避免双击双重激活的细节。此外ShortcutDrawingTests.cs、ShortcutTests.KeyDown.cs、ShortcutTests.Mouse.cs 分别覆盖绘制、按键与鼠标路由是理解 Shortcut 完整行为的补充材料。相关文档Command Deep Dive —— 命令系统的完整介绍Cancellable Work Pattern —— 可取消工作模式Events —— 事件模型Mouse Deep Dive —— 鼠标事件深入Menus Deep Dive —— Shortcut 在菜单体系类层级中的位置赞分享UI组件跨平台桌面应用【免费下载链接】Terminal.GuiCross Platform Terminal UI toolkit for .NET项目地址https://gitcode.com/gh_mirrors/te/Terminal.Gui点击查看免费下载相关推荐Halo Console 动态路由与侧边栏菜单生成机制详解Halo Console 动态路由与侧边栏菜单生成机制详解 本文以 Halo 建站工具的控制台Console为背景系统讲解其路由与侧边栏菜单的 动态生成机后端前端CMSUI 控件深度定制ScottPlot 工具栏与上下文菜单扩展UI 控件深度定制ScottPlot 工具栏与上下文菜单扩展 在数据可视化应用开发中用户交互体验往往决定了工具的实用性。ScottPlot作为.NET生态中数据可视化图表库告别单调状态栏SketchyBar命令行定制指南告别单调状态栏SketchyBar命令行定制指南 macOS状态栏总是让你觉得不够个性还在为无法调整的系统图标位置烦恼本文将带你掌握SketchyBar命桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考