Terminal.Gui Drawing 术语表深度解读:Attribute、Color、Scheme 与 VisualRole 核心概念全解析
Terminal.Gui Drawing 术语表深度解读:Attribute、Color、Scheme 与 VisualRole 核心概念全解析
本文基于 Terminal.Gui 仓库中 drawing-lexicon.md 这一绘制领域术语表展开,逐项拆解绘制子系统中最核心的 9 个概念——Attribute、BackgroundColor、Color、ForegroundColor、Glyph、Rune、Scheme、Style、VisualRole——并结合 Terminal.Gui/Drawing/ 下的真实源码实现,讲清每个术语的定义、数据结构、取值规则与在绘制管线中的实际作用。读完本文,你将掌握 Terminal.Gui 颜色与主题体系的最小必要知识,能够读懂 Scheme 的派生算法、理解 Attribute 的解析链路,并能在自己的控件中正确选择 VisualRole 与配色。
术语表在文档体系中的位置
该术语表(lexicon)并非孤立存在,它是 Terminal.Gui 文档"公共词汇表"的一部分,被两处正式文档以 INCLUDE 方式引用:
- drawing.md 中的 "Drawing Taxonomy & Lexicon" 小节,作为整篇绘制指南的开篇词汇基础;
- lexicon.md 中的 "Drawing" 小节,与 Arrangement、Configuration、Events、Layout、Navigation、Scrolling 等词汇表并列。
这决定了术语表的定位:它是一份领域共识定义,所有文档、API 注释(XML Doc)都围绕同一套词汇展开。读者在阅读 scheme.md、themes 相关文档 时遇到的术语,均以此为准。
核心术语逐项解读
Attribute:视觉样式的最终载体
Attribute | Defines concrete visual styling for a visual element (Foreground color, Background color, TextStyle).
Attribute 是 Terminal.Gui 中"某个元素具体长什么样"的最小封装。源码中它是一个轻量、不可变的 readonly record struct,定义于 Terminal.Gui/Drawing/Attribute.cs,内部仅由三个字段组成:
| 字段 | 类型 | 含义 |
|---|---|---|
Foreground |
Color |
前景色(文字颜色) |
Background |
Color |
背景色(文字背后的颜色) |
Style |
TextStyle |
文本样式(加粗、斜体、下划线等),默认 TextStyle.None |
实现要点:
- 默认值
Attribute.Default为new Color(Color.White), new Color(Color.Black),即白字黑底(源码第 25 行)。 - 提供了丰富的构造函数:两个
Color、两个字符串(内部走Color.Parse)、ColorName16(传统 16 色)、StandardColor(标准色板)、以及"单色同时作为前景和背景"的便捷构造。 Equals/GetHashCode同时比较 Foreground、Background、Style 三者;ToString()输出固定格式[Foreground,Background,Style](源码注释明确说明单元测试依赖该格式)。- 通过
AttributeJsonConverter支持 JSON 序列化,可直接出现在配置文件(config.json)中。
ForegroundColor 与 BackgroundColor:Attribute 的两个颜色属性
ForegroundColor | A property of
Attributedescribing the foreground text color. BackgroundColor | A property ofAttributedescribing the background text color.
这两个术语在词典中定义为 Attribute 的属性。从源码看:
Foreground描述文字本身的颜色;Background描述文字背后填充的颜色,同时也承担了"整个控件背景色"的职责——例如绘制 Viewport 时,就是用GetAttributeForRole(VisualRole.Normal).Background来清屏填充(见 BorderView.cs 中SolidFill back = new (GetAttributeForRole (VisualRole.Normal).Background)的用法)。
值得注意的命名细节:字典中写作 "ForegroundColor / BackgroundColor",而源码属性名为 Foreground / Background(无 Color 后缀),二者是同一概念的不同表述,阅读文档与代码时需自行对应。
Color:终端基础颜色(支持 TrueColor 与命名色)
Color | Base terminal color (supports TrueColor and named values like White, Black, Cyan, etc.).
Color 是一个 24 位真彩色结构体,定义于 Terminal.Gui/Drawing/Color/Color.cs,核心特征:
- ARGB32 编码:
R/G/B/A各占 1 字节,同时以uint Argb整体存储(StructLayout.Explicit字段布局)。 - TrueColor 支持:可用
new Color(r, g, b)直接构造任意 24 位颜色,例如内置 Base Scheme 的代码着色全部使用十六进制字面量(#569cd6、#ce9178等,见 Scheme.cs 的GetHardCodedSchemes)。 - 命名色支持:字典中提到的 White、Black、Cyan 等命名值来自
StandardColor枚举(通过StandardColors.GetArgb映射为 ARGB)以及传统 16 色枚举ColorName16。Color还提供"取最接近的命名色"能力(GetClosestNamedColor16,以欧氏距离度量)。 Color.None哨兵值:alpha=0 的0x00FFFFFF,表示"不指定具体颜色,使用终端默认前景/背景色"。这让终端自身的背景(包括透明、亚克力效果)得以透出,是主题系统支持"跟随终端配色"的关键机制。- Alpha 通道语义:当前渲染阶段不做 alpha 混合;alpha=0 表示不渲染,alpha=255 表示不透明渲染,其余值保留给未来的混合支持。
Glyph 与 Rune:字符与图形的边界
Glyph | A graphical representation of a character. Rune | Unicode character.
-
Rune 即 .NET 的
System.Text.Rune(Unicode 标量值),是绘制的基本"文字单元"。 -
Glyph 是字符的图形化呈现,即终端里实际画出来的符号。Terminal.Gui 将常用 UI 符号(复选框勾选态、选中指示器、进度条块、滚动条纹理、箭头、默认按钮括号等)统一定义在 Terminal.Gui/Drawing/Glyphs.cs 中,例如:
Glyphs.CheckStateChecked / CheckStateUnChecked / CheckStateNone:复选框三态;Glyphs.Selected / UnSelected:列表选中指示器;Glyphs.BlocksMeterSegment / ContinuousMeterSegment:进度条分段;Glyphs.Stipple:滚动条点阵纹理;Glyphs.RightArrow / LeftArrow等方向箭头。
这些字形可配置:实际取值来自 GlyphSettings(见 Terminal.Gui/Configuration/Settings/GlyphSettings.cs),运行时以 Resources/config.json 为数据源,并支持按主题覆盖(Themes:{name}:Glyphs)。字形值支持字符串、U+hex、\u 转义或十进制码点(RuneJsonConverter)四种写法。
Style:Attribute 的字体风格标志
Style | Property of
Attributefor font-like hints (bold, italic, underline).
Style 的类型是 TextStyle,一个 <a href="https://link.gitcode.com/i/790990c661cb643fb90dacce035f206c" target="_blank">Flags] 枚举,定义于 [Terminal.Gui/Drawing/TextStyle.cs。它只覆盖了 ANSI SGR(Select Graphic Rendition)中被认为可靠、有视觉意义、且不与其他 API 冗余的子集:
| 标志 | 二进制值 | 对应 ANSI SGR | 说明 |
|---|---|---|---|
None |
0b0000_0000 |
无 | 无样式 |
Bold |
0b0000_0001 |
1 | 加粗 |
Faint |
0b0000_0010 |
2 | 变暗(dim),终端支持度不一 |
Italic |
0b0000_0100 |
3 | 斜体 |
Underline |
0b0000_1000 |
4 | 下划线 |
Blink |
0b0001_0000 |
5 | 慢速闪烁,现代终端常被禁用 |
Reverse |
0b0010_0000 |
7 | 反显(交换前景/背景) |
Strikethrough |
0b0100_0000 |
9 | 删除线 |
使用要点:
- 多个样式用按位或组合,例如
TextStyle.Bold | TextStyle.Underline。 Bold与Faint可能互斥:如果终端用更深的颜色表示 faint、更浅的颜色表示 bold,两者无法同时呈现,最终显示哪个由终端决定。- 在 Scheme 派生算法中,Style 常被"追加":例如 Hot 系列角色(HotNormal/HotFocus/HotActive)默认在基础角色之上叠加
Underline,Active会叠加Bold,Highlight会叠加Italic。
VisualRole:元素的语义角色
VisualRole | Semantic role/purpose of a visual element (Normal, Focus, HotFocus, Active, Disabled, ReadOnly).
VisualRole 是语义层与视觉层之间的桥梁。枚举定义于 Terminal.Gui/Drawing/VisualRole.cs,词典中列举的 6 个角色只是全部角色的子集,完整枚举如下:
- 基础状态角色:
Normal(默认、未聚焦、未选中、可用)、Focus(聚焦)、Active(激活/选中,如 ListView 选中项、HexView/CharMap 的标题)、Highlight(高亮,如鼠标悬停在 Button 上)、Disabled(禁用)、Editable(可编辑,如 TextField)、ReadOnly(只读)。 - HotKey 派生角色:
HotNormal、HotFocus、HotActive——带View.HotKey指示器的对应状态。 - 代码高亮角色:
Code及CodeComment、CodeKeyword、CodeString、CodeNumber、CodeOperator、CodeType、CodePreprocessor、CodeIdentifier、CodeConstant、CodePunctuation、CodeFunctionName、CodeAttribute,用于 Markdown 代码块等预格式化内容的语法着色。
关键语义:一个 View 可能渲染为多个元素,每个元素可关联不同的 VisualRole(VisualRole.cs 的 remarks 明确说明),因此同一控件在不同区域可使用不同配色。
Scheme:语义角色到视觉样式的映射
Scheme | Maps
VisualRoletoAttribute, defining visual element appearance (color and style) based on semantic purpose.
Scheme 是 Terminal.Gui 主题系统的核心载体,一个 Scheme 即一套"角色 → 属性"的映射表。定义于 Terminal.Gui/Drawing/Scheme.cs,它是不可变的 record:
- 每个
VisualRole对应一个Attribute属性(Normal、Focus、Active、Disabled……共 23 个)。 Normal必须显式设置,其余属性均可选:未显式设置的属性会按固定的派生算法自动生成,保证任何角色都能解析出有效 Attribute。- 修改 Scheme 的正确方式是创建新实例(通过构造函数传入旧 Scheme 或 Attribute),而不是原地修改。
- 内置 5 套硬编码 Scheme 由
Scheme.GetHardCodedSchemes()提供:Base(默认,Normal 为Color.None跟随终端配色,并预设全部代码高亮色)、Dialog、Error、Menu、Accent。 - 主题的运行时管理由
SchemeManager(Terminal.Gui/Configuration/SchemeManager.cs)负责,可通过 config.json 配置。
深化:Scheme 的 Attribute 派生算法
词典没有展开、但对理解 Scheme 至关重要的一点是:未显式设置的 VisualRole 如何被派生。源码 Scheme.cs 的 GetAttributeForRoleCore 方法实现了完整的派生规则:
- Normal:必须显式设置,是其他派生的基准。
- Focus:交换 Normal 的前景与背景色(
Color.None先解析为终端真实默认色,通过 OSC 10/11 查询;查不到时前景回退白、背景回退黑)。 - Active:基于 Focus,前景变亮(
GetBrighterColor(0.2))、背景变暗(GetDimmerColor(0.2)),并追加Bold样式。 - Highlight:基于 Normal,前景取 Normal 背景变亮后的颜色,背景不变,样式追加
Italic。 - Editable:基于 Normal,背景改为前景色按 50% 调暗后的颜色。
- ReadOnly:基于 Editable,前景按 5% 调暗。
- Disabled:基于 Normal,前景按 5% 调暗。
- HotNormal / HotFocus / HotActive:分别在 Normal / Focus / Active 基础上追加
Underline。 - Code 系列:
Code基于 Editable(背景再调暗 20% + 追加Bold),其余CodeXxx角色默认直接继承Code。
两个重要的算法细节:
- 明暗背景感知:做颜色数学(变亮/变暗)前,算法通过
Color.IsDarkColor()判断相关背景是深色还是浅色。浅色背景下"调暗"是向白色靠拢(wash out),从而保证浅色与深色终端都能得到正确视觉结果。 - 递归防护:
GetAttributeForRoleCore使用HashSet<VisualRole>栈防止循环派生导致的无限递归(如角色 A 派生自 B、B 又派生自 A 的异常配置),遇到环时回退到Normal。
实战:Attribute 在 View 上的解析链路
理解了五个核心类型后,还需知道它们在真实绘制流程中如何被消费。入口是 View.GetAttributeForRole(VisualRole),实现在 Terminal.Gui/ViewBase/View.Drawing.Attribute.cs,解析顺序如下:
- Scheme 继承:若当前 View 没有显式 Scheme 且没有 SchemeName,则委托给
SuperView.GetAttributeForRole,让父视图可以统一定制子元素的配色。 - Scheme 解析:否则取自身 Scheme,调用
Scheme.GetAttributeForRole(role, defaultTerminalColors)(此时触发上述派生算法)。 - 可取消事件:触发
GettingAttributeForRole/OnGettingAttributeForRole(属于 Cancellable Work Pattern 的一部分),处理器可通过 VisualRoleEventArgs.cs 的Role判断目标角色、用Result+Handled覆盖返回值。 - 状态修正:
Enabled == false时强制改用Disabled角色;MouseHighlightStates包含MouseState.In/Pressed且未聚焦时改用Highlight角色。
典型用法示例(来自 VisualRoleEventArgs.cs 的文档注释):
View view = new();
view.GettingAttributeForRole += (sender, args) =>
{
if (args.Role == VisualRole.Focus)
{
args.Result = new Attribute(Color.BrightCyan, Color.Black);
args.Handled = true;
}
};
Attribute attribute = view.GetAttributeForRole(VisualRole.Focus);
绘制侧,控件拿到 Attribute 后通过 SetAttribute() 设置到 driver,再经 AddRune()/AddStr() 输出字形——这正是 drawing.md 描述的 Move() → SetAttribute() → AddRune() 绘制三步曲。由于采用延迟渲染,实际写屏发生在 MainLoop 迭代的 Write 阶段。
术语关系速览与自查表
| 术语 | 本质 | 所在源码文件 |
|---|---|---|
| Attribute | 前景 + 背景 + 样式的不可变组合 | Attribute.cs |
| ForegroundColor / BackgroundColor | Attribute 的两个 Color 属性 |
同上 |
| Color | ARGB32 真彩色,支持命名色与 None |
Color.cs |
| Glyph / Rune | 字形(可配置符号) / Unicode 字符 | Glyphs.cs |
| Scheme | VisualRole → Attribute 的映射表(含派生算法) | Scheme.cs |
| Style | 字体风格标志(TextStyle 枚举) | TextStyle.cs |
| VisualRole | 元素语义角色(状态 + 代码高亮) | VisualRole.cs |
一句话串联整条链路:一个 View 的某个元素按语义选择 VisualRole,VisualRole 经 Scheme 映射(必要时触发派生算法)解析为 Attribute,Attribute 携带 ForegroundColor、BackgroundColor 与 Style,最终配合 Glyph/Rune 字形通过 SetAttribute + AddRune 绘制到终端。
理解这 9 个术语,就掌握了阅读 Terminal.Gui 所有绘制与主题相关源码、文档(drawing.md、scheme.md、config.md)与配置文件(config.json)的词汇基础;在此基础上为控件选择正确的 VisualRole、定制 Scheme 或拦截 GettingAttributeForRole 事件,就能实现完全自定义的终端 UI 视觉体系。