Terminal.Gui 导航系统深入解析:焦点管理、Tab 遍历与键盘/鼠标导航实战指南
Terminal.Gui 导航系统深入解析:焦点管理、Tab 遍历与键盘/鼠标导航实战指南
导读
本文全面剖析 Terminal.Gui(跨平台 .NET 终端 UI 工具包)的导航(Navigation)系统:它决定了应用中哪一个元素接收键盘与鼠标输入(即"谁拥有焦点")、用户如何切换焦点、键盘遍历 UI 元素的顺序,以及 Tab、F6、方向键、HotKey、鼠标点击等标准输入在默认情况下的行为。读完本文,你将掌握焦点链(Focus Chain)的完整模型、TabBehavior 四种取值的使用场景、Application.Navigation 的全局焦点 API,并能通过 SetFocus()、AdvanceFocus() 与 HasFocusChanging/HasFocusChanged 事件构建可键盘直达、无障碍友好的终端界面。文中所有结论均以当前仓库源码(navigation.md、ApplicationNavigation.cs、TabBehavior.cs 等)为依据。
阅读前置:建议先通读 Keyboard Deep Dive 与 Lexicon & Taxonomy,它们与本文共享大量概念;有关光标显示的内容请参见 Cursor Management。
导航系统回答的核心问题
Terminal.Gui 的导航系统本质上要回答六类问题,理解它们有助于把握整个导航架构的边界:
- 视觉线索:哪些视觉元素帮助用户判断"哪个控件正在接收键盘/鼠标输入"(即谁有焦点)?
- 焦点切换:用户如何改变应用中拥有焦点的控件?
- 导航线索:哪些视觉元素提示用户"什么按键会改变焦点"?
- 动作线索:哪些视觉元素提示用户"什么按键会在未聚焦的控件上触发动作"(如 HotKey)?
- 遍历顺序:使用键盘导航时,UI 元素按什么顺序被遍历?
- 默认动作:标准按键/鼠标输入(
HotKey、Space、Enter、鼠标单击)的默认行为是什么?
术语表(Lexicon & Taxonomy)
先统一术语,后续章节会反复使用(完整术语表见 navigation-lexicon.md):
| 术语 | 含义 |
|---|---|
| Cursor | 指示键盘输入将作用于何处的视觉标记。每个终端会话只有一个 Cursor,详见 Cursor。 |
| Focus | 某个 UI 元素(View)被选中并准备接收用户输入的状态。 |
| Focus Chain(焦点链) | 从当前聚焦元素向上延伸到根视图(Application.Top)的有序序列。一个应用中同一时刻只有一条焦点链处于激活状态(top.HasFocus == true),且链中恰好只有一个 View 是"最聚焦"(most-focused)的——即实际接收键盘输入的那个。 |
| Tab | 既可指键盘上的 Tab 键,也可指键盘导航中的一个"停靠点"(stop-point)。 |
| TabStop | 一个"终极停靠点":自身没有可聚焦子视图的 View。Command.NextTabStop/PreviousTabStop 的默认键是 Key.Tab/Key.Tab.WithShift(见 Application.DefaultKeyBindings),且只在同级兄弟视图(peer-views)之间导航。 |
| TabGroup | 一个"可聚焦子视图的容器" View。Command.NextTabGroup/PreviousTabGroup 的默认键为 Key.F6/Key.F6.WithShift,用于在视图层级中上下导航。 |
| Enter / Gain | View 从"未聚焦"变为"获得焦点"(v1 遗留术语,等价于"gaining focus")。 |
| Leave / Lose | View 从"已聚焦"变为"失去焦点"(v1 遗留术语,等价于"losing focus")。 |
导航设计原则(Tenets)
Terminal.Gui v2 的导航设计遵循四条原则,优先级自上而下递减(键盘相关的原则同时参考 Keyboard Deep Dive):
- 每应用仅一个焦点(One Focus Per App):不可能存在两个视图同时是"最聚焦"视图。应用中始终有且仅有一个视图作为键盘输入的目标。
- 键盘永远可达(There's Always a Way With The Keyboard):框架确保只用键盘也能访问应用的任何元素。例如仓库中的单元测试
AllViews_AtLeastOneNavKey_Advances(见 AllViewsNavigationTests.cs)遍历所有内置 View,断言每个可聚焦的内置 View 都至少有一个能推进焦点的导航键。另一个保证是:只要定义了 HotKey 的 View 可见且启用,无论视图层级如何,按下该热键就会触发其动作(默认同时聚焦该 View)。 - 灵活覆写(Flexible Overrides):焦点行为可以在代码中灵活改变。例如将
View.CanFocus设为false可阻止视图获得焦点,或覆写OnHasFocusChanging返回true取消焦点变更。 - 概念解耦(Decouple Concepts):v1 中
CanFocus与HasFocus、TabIndex、TabIndexes、TabStop强耦合,存在大量自动同步的"魔法"逻辑,导致 API 脆弱难测。v2 将这些概念解耦:例如CanFocus == true的视图可以设置TabStop == NoStop,仍可通过鼠标获得焦点。
回答导航关键问题:视觉线索与焦点切换
焦点视觉线索
当前焦点指示:
- 拥有焦点的视图使用其
ColorScheme.Focus属性渲染; - 焦点链中最深的视图(最聚焦)可通过
View.Cursor显示终端光标; - 焦点链上的祖先视图(聚焦视图的 SuperView 们)同样使用聚焦样式;
- 整个终端同一时刻只显示一个光标,由
Application.Navigation(ApplicationNavigation.cs)统一管理。
导航线索:
- HotKey 通过在
Label、Button、MenuItem等控件中以下划线标注字符来提示(如E_xit中的x); - Tab 顺序在容器内一般为从左到右、从上到下;
- 焦点指示器(如高亮矩形)显示哪个视图将接收输入。
提示:关于视图如何控制光标位置与样式,参见 Cursor Management。
改变焦点的方式
键盘方式:
| 按键 | 行为 |
|---|---|
Tab / Shift+Tab |
在 TabStop 视图之间导航 |
F6 / Shift+F6 |
在 TabGroup 容器之间导航 |
| 方向键 | 在容器内导航或移动到相邻视图 |
HotKey(Alt+字母) |
直接导航到特定视图 |
Enter / Space |
激活当前聚焦的视图 |
鼠标方式:
- 单击任何可聚焦视图即可让其获得焦点;
- 焦点行为取决于该视图之前是否被聚焦过(见下文"RestoreFocus 与 AdvanceFocus"小节)。
导航遍历顺序
视图按其 TabStop 行为与在视图层级中的位置被遍历:
- TabStop 视图:用
Tab/Shift+Tab按布局顺序导航; - TabGroup 视图:容器用
F6/Shift+F6导航; - NoStop 视图:键盘导航时跳过,但可被鼠标聚焦。
键盘导航详解
Terminal.Gui 导航系统的绝大部分工作都围绕"让用户能用键盘导航视图"展开。系统定义的导航键如下(均以 KeyBindingScope.Application 作用域注册,见 Application.cs 中的 DefaultKeyBindings):
| Command | 默认键 | 行为 |
|---|---|---|
Command.NextTabStop |
Key.Tab |
导航到下一个 TabStop 子视图;若无,则聚焦第一个 TabStop 子视图 |
Command.PreviousTabStop |
Key.Tab.WithShift |
与 NextTabStop 相反 |
| — | Key.CursorRight / Key.CursorDown |
行为与 NextTabStop 完全相同 |
| — | Key.CursorLeft / Key.CursorUp |
行为与 PreviousTabStop 完全相同 |
Command.NextTabGroup |
Key.F6 |
导航到视图层级中下一个 TabGroup;若无,则聚焦第一个 TabGroup |
Command.PreviousTabGroup |
Key.F6.WithShift |
与 NextTabGroup 相反 |
F6 的选择沿用了 Windows 通用键盘加速键约定。
这些键由 Application 注册为**应用作用域(KeyBindingScope.Application)**的键绑定。由于应用作用域的键绑定优先级最低,视图可以覆写这些键的默认行为——典型例子是 Editor 视图默认覆写了 Key.Tab,让用户能在文本中直接输入 \t(见 TextView.Commands.cs 中 KeyBindings.Add (Key.Tab, Command.NextTabStop) 的注册方式)。仓库中的 AllViews_AtLeastOneNavKey_Advances 单元测试保证所有内置视图至少有一个能推进焦点的导航键。
补充:在仓库当前的
DefaultKeyBindings定义中(Application.cs),NextTabStop/PreviousTabStop确实绑定到Key.Tab/Key.Tab.WithShift,NextTabGroup/PreviousTabGroup绑定到Key.F6/Key.F6.WithShift,与文档描述一致;而术语表 navigation-lexicon.md 中提示的Ctrl+PageDown/Ctrl+PageUp属于该术语定义的历史说明,实际按键以DefaultKeyBindings为准,且这些默认值可通过Application.SetDefaultKeyBinding自定义。
导航示例代码
// 基础焦点管理
var button = new Button() { Text = "Click Me", CanFocus = true, TabStop = TabBehavior.TabStop };
var textField = new TextField() { Text = "", CanFocus = true, TabStop = TabBehavior.TabStop };
// 带分组导航的容器
var frameView = new FrameView()
{
Title = "Options",
CanFocus = true,
TabStop = TabBehavior.TabGroup
};
// 程序化焦点控制
button.SetFocus(); // 给特定视图焦点
Application.Navigation.AdvanceFocus(NavigationDirection.Forward, TabBehavior.TabStop);
HotKey:跨层级直达
HotKey 是键盘导航的"快捷键"机制,详见 Keyboard Deep Dive。View.HotKey 可以在整个应用的视图层级间导航,且独立于焦点工作——即使某个视图当前未聚焦,按下其热键也能直接触发动作并(默认)聚焦它。这在复杂的嵌套子视图(包括重叠窗口场景)中非常有用,AllViewsTester 场景(AllViewsTester.cs)就是一个典型例子。
HotKey 通过 View.HotKey 属性定义,用 Alt+指定键 激活:
var saveButton = new Button() { Text = Strings.cmdSave, HotKey = Key.S };
var exitButton = new Button() { Text = "E_xit", HotKey = Key.X };
// Alt+S 激活保存,Alt+X 激活退出,与当前焦点无关
此外,应用中多个视图(甚至同一 SuperView 内)可以拥有相同的 HotKey。
鼠标导航详解
鼠标导航比键盘简单得多:如果视图可聚焦,用户点击它即可获得焦点。但有两个值得注意的细节:
- 一个可聚焦的 View 带有可聚焦子视图时,用户点击其 Border,哪个子视图(如果有)会获得焦点?
- 同样情况下,用户点击其 ContentArea,哪个子视图(如果有)会获得焦点?
两个问题的答案一致,取决于该 View 之前是否被聚焦过:
- 若 View 之前曾被聚焦,系统会记录之前"最聚焦"的子视图,并通过
RestoreFocus()恢复到该子视图; - 若 View 之前未被聚焦,则调用
AdvanceFocus()查找下一个合适的焦点目标。
为保证上述机制正确,框架必须包含相应逻辑:一旦此前可聚焦的视图变得不可聚焦(例如 Visible 发生变化),就要清除 RestoreFocus() 使用的焦点缓存。
鼠标焦点示例
// 鼠标点击行为
view.MouseEvent += (sender, e) =>
{
if (e.Flags.HasFlag(MouseFlags.LeftButtonClicked) && view.CanFocus)
{
view.SetFocus();
e.Handled = true;
}
};
// 鼠标悬停聚焦(可选行为)
view.MouseEnter += (sender, e) =>
{
if (view.CanFocus && focusOnHover)
{
view.SetFocus();
}
};
应用级导航:Application.Navigation
应用层的导航被封装在 ApplicationNavigation 辅助类中(ApplicationNavigation.cs),通过 Application.Navigation 属性公开访问。该类的核心 API 与内部职责如下:
获取最聚焦视图
ApplicationNavigation.GetFocused() 返回应用中"最聚焦"(焦点链最深)的视图;若没有视图拥有焦点(极其罕见的情况)则返回 null。它替代了 v1 的 View.MostFocused。
var focused = Application.Navigation.GetFocused();
全局焦点事件
FocusedChanged:应用中"最聚焦"视图已改变时触发。适合想对最聚焦视图做处理的应用(例如AdornmentsEditor场景,见 Adornments.cs)。FocusedChanging:应用中"最聚焦"视图正在改变时触发。适合想在整个应用范围内限制"哪些视图可以被聚焦"的应用。
从源码看(ApplicationNavigation.cs),SetFocused() 内部在焦点变更时还会处理鼠标抓取(若旧焦点视图被 App.Mouse 抓取则调用 UngrabMouse()),并通知驱动 SetCursorNeedsUpdate(true) 以刷新光标。
程序化推进焦点
ApplicationNavigation.AdvanceFocus() 使焦点向前/向后推进到应用视图层级中的下一个视图,并以 behavior 作为过滤条件。其实现极为简洁:
return App?.TopRunnableView is { } && App.TopRunnableView.AdvanceFocus (direction, behavior);
(仓库当前实现还会先检查活动 Popover——若存在可见的 GetActivePopover(),则将焦点推进委托给该 Popover,见 ApplicationNavigation.cs。)
该方法由 app.Init() 期间创建的应用作用域键绑定所绑定的 Command 处理器调用;作为便利,它是 public 的。注意: 在视图内部访问时,应使用 App?.Current 而非已过时的 Application.TopRunnable。
在 v1 中,这一方法的功能分散在 Application 与 Runnable 中的十余个函数里;v2 将其收敛为单一 API。
终端光标管理
ApplicationNavigation 还负责管理终端光标。每个主循环迭代都会调用 UpdateCursor()(源码见 ApplicationNavigation.cs),其流程为:
- 通过
GetCursorNeedsUpdate()检查是否需要更新光标(性能优化,避免每帧重绘); - 获取最聚焦视图的
Cursor属性; - 验证光标位置位于所有祖先 viewport 边界内(从最聚焦视图逐级向
SuperView上溯检查); - 通过
SetCursor()委托给驱动。
光标只为最聚焦的视图(焦点链最深者)显示;焦点变化时光标自动更新为新视图的光标状态。视图通过 View.Cursor 属性控制光标,而非直接操作 ApplicationNavigation。
说明:视图如何设置光标位置与样式的完整细节,参见 Cursor Management。
应用级导航示例
var app = Application.Create();
app.Init();
// 监听全局焦点变化
app.Navigation.FocusedChanged += (sender, e) =>
{
var focused = app.Navigation.GetFocused();
StatusBar.Text = $"Focused: {focused?.GetType().Name ?? "None"}";
};
// 阻止特定视图获得焦点
app.Navigation.FocusedChanging += (sender, e) =>
{
if (e.NewView is SomeRestrictedView)
{
e.Cancel = true; // 取消焦点变更
}
};
// 程序化导航
Application.Navigation.AdvanceFocus(NavigationDirection.Forward, TabBehavior.TabStop);
Application.Navigation.AdvanceFocus(NavigationDirection.Backward, TabBehavior.TabGroup);
NavigationDirection 枚举只有两个取值:Forward 与 Backward(见 NavigationDirection.cs)。
视图级导航:View 上的焦点 API
AdvanceFocus() 是开发者让一个 View 获得或失去焦点的核心方法(View.Navigation.cs)。其递归算法从源码可以概括为:
- 先检查自身
CanBeVisible; - 触发
AdvancingFocus事件(RaiseAdvancingFocus),若被处理则返回; - 若当前
Focused子视图存在,先尝试让子视图推进焦点(递归下探); - 若子视图无法推进,则基于方向与行为构建焦点链
GetFocusChain(direction, behavior)并在链中寻找下一个候选;TabGroup行为在到达链顶时还有特殊的回绕逻辑。
视图的焦点变化会触发一系列事件,例如 HasFocusChanging 与 HasFocusChanged(事件签名与触发顺序见 View.Navigation.cs)。
视图焦点管理示例
// 基础焦点控制
public class CustomView : View
{
protected override void OnHasFocusChanging(CancelEventArgs<bool> e)
{
if (SomeCondition)
{
e.Cancel = true; // 阻止焦点变更
return;
}
base.OnHasFocusChanging(e);
}
protected override void OnHasFocusChanged(EventArgs<bool> e)
{
if (e.CurrentValue)
{
// 视图获得了焦点
UpdateAppearance();
}
base.OnHasFocusChanged(e);
}
}
什么让一个 View 可聚焦?
首先,只有 Visible 与 Enabled 都为 true 的视图才能获得焦点。在此基础上,CanFocus 决定视图是否可聚焦——CanFocus 必须为 true。但即便 CanFocus == true,其他因素仍可能阻止视图获得焦点。
一个"可见 + 启用 + CanFocus == true"的视图,可以通过鼠标点击或代码显式调用 SetFocus() 获得焦点(当然,视图自身或其他代码可通过覆写 OnHasFocusChanging 取消)。
对于键盘导航,TabStop 属性是"从当前最聚焦视图出发"的过滤器;TabStop 对鼠标导航没有影响。TabStop 的类型为 TabBehavior 枚举(源码见 TabBehavior.cs)。
TabBehavior 取值详解
| 值 | 含义 |
|---|---|
null |
视图仍在初始化中;作为信号让 set_CanFocus 自动将 TabStop 设为 TabStop(为最常见用例提供便利)。在判断"视图是否可被键盘聚焦"时等价于 NoStop。 |
NoStop |
阻止用户通过键盘导航让该视图(及其子视图)获得焦点。注意:视图仍可通过代码或鼠标获得焦点。 |
TabStop |
表示该视图是可聚焦视图且没有可聚焦子视图。NextTabStop/PreviousTabStop 键只在兄弟视图(SuperView.SubViews)之间推进。 |
TabGroup |
表示该视图是"其他可聚焦视图的容器",支持跨容器键盘导航,适用于平铺(tiled)与重叠(overlapped)两种场景。例如 FrameView 是平铺场景的可见容器,其 TabStop 设为 TabGroup(Arrangement 为 ViewArrangement.Fixed);Window 是重叠场景的可见容器,其 TabStop 设为 TabGroup(Arrangement 为 `ViewArrangement.Movable |
需要说明:
TabBehavior枚举的 XML 文档中,TabGroup项仍写着"NextTabGroup 键为Ctrl+PageDown"的示例文本(见 TabBehavior.cs),但仓库当前Application.DefaultKeyBindings实际绑定的是Key.F6(Application.cs),实际按键请以后者为准,且可通过Application.SetDefaultKeyBinding覆盖。
可聚焦条件总结
一个视图可聚焦,需要满足:
- Visible =
true - Enabled =
true - CanFocus =
true - TabStop !=
NoStop(仅键盘导航需要)
// 示例:让一个视图可聚焦
var view = new Label()
{
Text = "Focusable Label",
Visible = true, // 必须可见
Enabled = true, // 必须启用
CanFocus = true, // 必须可聚焦
TabStop = TabBehavior.TabStop // 可键盘导航
};
如何判断视图是否有焦点?哪个是最聚焦视图?
View.HasFocus 指示该视图是否聚焦,是权威信号。若视图没有可聚焦子视图,则该属性同时表明它是应用中"最聚焦"的视图。
将 HasFocus 设为 true 与调用 SetFocus() 效果相同——也意味着焦点可能不会真的改变。
如果 v.HasFocus == true,则:
v的 SuperView 层级上所有视图都必须是可聚焦的;v的 SuperView 层级上所有视图的HasFocus也均为true;v中最深的可聚焦子视图HasFocus也为true。
换言之,v.HasFocus == true 并不一定意味着 v 是最聚焦、正在接收输入的视图。若它有可聚焦子视图,那么其中一个(或更深层的子视图)才是最聚焦的(即 Application.Navigation.GetFocused() 的返回值)。
从源码看,private bool _hasFocus 字段是 View.HasFocus 的后备存储,是视图是否有焦点的终极事实来源(相关事件与字段实现见 View.Navigation.cs)。
焦点链示例
// 层级:Window -> Dialog -> Button
// 如果 Button 有焦点,则:
window.HasFocus == true // 焦点链的一部分
dialog.HasFocus == true // 焦点链的一部分
button.HasFocus == true // 真正被聚焦
// Application.Navigation.GetFocused() 返回 button
var mostFocused = Application.Navigation.GetFocused(); // 返回 button
用户如何感知焦点?
简言之:ColorScheme.Focus。焦点链上的视图使用聚焦颜色渲染,提供"应用的哪部分处于活动状态"的视觉反馈。
// 自定义焦点样式
protected override void OnDrawContent(Rectangle viewport)
{
var attribute = HasFocus ? GetFocusColor() : GetNormalColor();
Driver.SetAttribute(attribute);
// ... 绘制内容
}
如何让一个视图获得焦点?
开发者让视图获得焦点的核心 public 方法是 SetFocus()(签名见 View.Navigation.cs)。
与 v1 不同,v2 中该方法在焦点变更未发生时(例如视图不可聚焦、或焦点变更被取消)返回 false:
// 程序化焦点控制
if (myButton.SetFocus())
{
Console.WriteLine("Button now has focus");
}
else
{
Console.WriteLine("Could not focus button");
}
// 备选:设置 HasFocus 属性(效果相同)
myButton.HasFocus = true;
如何让一个视图失去焦点?
让视图失去焦点的典型方式是让另一个视图获得焦点:
// 聚焦其他视图,从而移除当前视图的焦点
otherView.SetFocus();
// 或程序化推进焦点
Application.Navigation.AdvanceFocus(NavigationDirection.Forward, TabBehavior.TabStop);
// 视图变为不可聚焦时也会失去焦点
myView.CanFocus = false; // 若有焦点则会失去
myView.Visible = false; // 若有焦点则会失去
myView.Enabled = false; // 若有焦点则会失去
确定最聚焦的子视图
v1 中 View.MostFocused 会沿视图层级向上遍历,返回最后一个 HasFocus == true 的视图。v2 中 Application.Navigation.GetFocused() 提供相同功能且开销更小:
// v2 获取最聚焦视图的方式
var focused = Application.Navigation.GetFocused();
// 替代 v1 的写法:
// var focused = Application.TopRunnable.MostFocused;
View.Add/Remove 对焦点的影响
v1 中,调用 super.Add(view) 时若 view.CanFocus == true,会导致层级中所有 SuperView 的 CanFocus 也被自动设为 true;同时 v1 会在 view.CanFocus == true 时自动设置 TabStop。
v2 的规则明显简化:
- 开发者必须显式设置视图层级中任何希望获得焦点的视图的
CanFocus; - v2 保留了
Add自动设置TabStop的行为(因为它不复杂,且免去开发者同时设置TabStop与CanFocus的麻烦); - 注意: 如果
TabStop被改变,v2 不会自动改变CanFocus。
// v2 显式焦点设置
var container = new FrameView()
{
Title = "Container",
CanFocus = true, // 必须显式设置
TabStop = TabBehavior.TabGroup
};
var button = new Button()
{
Text = "Click Me",
CanFocus = true, // 必须显式设置
TabStop = TabBehavior.TabStop // Add() 会自动设置,但可以覆盖
};
container.Add(button); // 不会自动给 container 设置 CanFocus
监听视图焦点变化
HasFocusChanging 与 HasFocusChanged 在视图焦点变化时触发:
// 监听焦点变化
view.HasFocusChanging += (sender, e) =>
{
if (e.NewValue && !ValidateCanFocus())
{
e.Cancel = true; // 阻止获得焦点
}
};
view.HasFocusChanged += (sender, e) =>
{
if (e.CurrentValue)
{
OnViewGainedFocus();
}
else
{
OnViewLostFocus();
}
};
内置视图的交互性速查表
下表总结了内置视图对各种输入方式的响应(表格图例见后文):
| View | States | Static | Default | HotKeys | Activate Cmd | Accept Cmd | HotKey Cmd | Click Focus | DblClick | RightClick | GrabMouse |
|---|---|---|---|---|---|---|---|---|---|---|---|
| View(基类) | 1 | Yes | No | 1 | OnSelect | OnAccept | Focus | Focus | - | - | No |
| Label | 1 | Yes | No | 1 | OnSelect | OnAccept | FocusNext | Focus | - | FocusNext | No |
| Button | 1 | No | Yes | 1 | OnSelect | Focus+OnAccept | Focus+OnAccept | HotKey | - | Select | No |
| CheckBox | 3 | No | No | 1 | OnSelect+Advance | OnAccept | OnAccept | Select | - | Select | No |
| OptionSelector | >1 | No | No | 2+ | Advance | SetValue+OnAccept | Focus+SetValue | SetFocus+SetCursor | - | SetFocus+SetCursor | No |
| LinearRange | >1 | No | No | 1 | SetFocusedOption | SetFocusedOption+OnAccept | Focus | SetFocus+SetOption | - | SetFocus+SetOption | Yes |
| ListView | >1 | No | No | 1 | MarkUnMarkRow | OpenSelected+OnAccept | OnAccept | SetMark+OnSelectedChanged | OpenSelected+OnAccept | - | No |
| TextField | 1 | No | No | 1 | - | OnAccept | Focus | Focus | SelectAll | ContextMenu | No |
| Editor | 1 | No | No | 1 | - | OnAccept | Focus | Focus | - | ContextMenu | Yes |
表格图例
- States:视图可拥有的视觉/功能状态数量;
- Static:视图是否主要用于展示(不可交互);
- Default:视图能否成为默认按钮(通过 Enter 激活);
- HotKeys:视图通常支持的 HotKey 数量;
- Activate Cmd:调用
Command.Activate时的行为; - Accept Cmd:调用
Command.Accept时的行为; - HotKey Cmd:按下视图 HotKey 时的行为;
- Click Focus:点击时的行为(若
CanFocus == true); - DblClick:双击时的行为;
- RightClick:右键点击时的行为;
- GrabMouse:视图是否捕获鼠标以进行拖拽操作。
常见导航模式
对话框导航
var dialog = new Dialog()
{
Title = "Settings",
CanFocus = true,
TabStop = TabBehavior.TabGroup
};
var okButton = new Button() { Text = "OK", IsDefault = true };
var cancelButton = new Button() { Text = "Cancel" };
// Tab 在按钮间导航,Enter 激活默认按钮
dialog.Add(okButton, cancelButton);
容器导航
var leftPanel = new FrameView()
{
Title = "Options",
TabStop = TabBehavior.TabGroup,
X = 0,
Width = Dim.Percent(50)
};
var rightPanel = new FrameView()
{
Title = "Preview",
TabStop = TabBehavior.TabGroup,
X = Pos.Right(leftPanel),
Width = Dim.Fill()
};
// F6 在面板之间导航,Tab 在面板内部导航
列表导航
var listView = new ListView()
{
CanFocus = true,
TabStop = TabBehavior.TabStop
};
// 方向键在条目间移动,Enter 选择,Space 切换
listView.KeyBindings.Add(Key.CursorUp, Command.Up);
listView.KeyBindings.Add(Key.CursorDown, Command.Down);
listView.KeyBindings.Add(Key.Enter, Command.Accept);
无障碍(Accessibility)考量
Terminal.Gui 的导航系统从设计之初就考虑无障碍:
键盘无障碍
- 所有功能必须可通过键盘访问;
- Tab 顺序应逻辑清晰、可预测;
- HotKey 提供到达重要功能的直接途径;
- 方向键在控件内提供细粒度导航。
视觉无障碍
- 焦点指示器必须清晰可见;
- 颜色不是焦点状态的唯一指示(即不能仅靠颜色区分焦点);
- 文本与背景对比度符合无障碍标准;
- HotKey 以视觉方式标注(下划线字符)。
屏幕阅读器支持
- 焦点变化通过系统事件播报;
- 视图标题与标签提供上下文;
- 状态信息可以程序化获取。
无障碍导航最佳实践
// 提供有意义的标签
var button = new Button() { Text = "_Save Document", HotKey = Key.S };
// 设置逻辑 Tab 顺序
container.TabStop = TabBehavior.TabGroup;
foreach (var view in container.Subviews)
{
view.TabStop = TabBehavior.TabStop;
}
// 为鼠标动作提供键盘替代方案
view.KeyBindings.Add(Key.F10, Command.Context); // 右键的键盘等价物
view.KeyBindings.Add(Key.Space, Command.Activate); // 点击的键盘等价物
延伸阅读
- Keyboard Deep Dive — HotKey、按键绑定与键盘事件深入;
- Mouse Deep Dive — 鼠标事件、点击与拖拽语义;
- Cursor Management — 视图如何控制光标位置与样式;
- Lexicon & Taxonomy — 术语与分类体系;
- 相关源码:ApplicationNavigation.cs、View.Navigation.cs、TabBehavior.cs、Application.cs;
- 相关测试:AllViewsNavigationTests.cs;
- 交互示例:AllViewsTester.cs、Adornments.cs。
无障碍标准的行业参考(外部链接,仅供背景了解):WCAG 快速参考、Microsoft 无障碍指南、.NET 无障碍文档。