Terminal.Gui Drawing 术语表深度解读:Attribute、Color、Scheme 与 VisualRole 核心概念全解析

原创2026-09-23 09:16:401,873 阅读
文章标签:UI组件跨平台桌面应用

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 Attribute describing the foreground text color. BackgroundColor | A property of Attribute describing 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 Attribute for 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 VisualRole to Attribute, 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 方法实现了完整的派生规则:

  1. Normal:必须显式设置,是其他派生的基准。
  2. Focus:交换 Normal 的前景与背景色(Color.None 先解析为终端真实默认色,通过 OSC 10/11 查询;查不到时前景回退白、背景回退黑)。
  3. Active:基于 Focus,前景变亮(GetBrighterColor(0.2))、背景变暗(GetDimmerColor(0.2)),并追加 Bold 样式。
  4. Highlight:基于 Normal,前景取 Normal 背景变亮后的颜色,背景不变,样式追加 Italic。
  5. Editable:基于 Normal,背景改为前景色按 50% 调暗后的颜色。
  6. ReadOnly:基于 Editable,前景按 5% 调暗。
  7. Disabled:基于 Normal,前景按 5% 调暗。
  8. HotNormal / HotFocus / HotActive:分别在 Normal / Focus / Active 基础上追加 Underline。
  9. 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,解析顺序如下:

  1. Scheme 继承:若当前 View 没有显式 Scheme 且没有 SchemeName,则委托给 SuperView.GetAttributeForRole,让父视图可以统一定制子元素的配色。
  2. Scheme 解析:否则取自身 Scheme,调用 Scheme.GetAttributeForRole(role, defaultTerminalColors)(此时触发上述派生算法)。
  3. 可取消事件:触发 GettingAttributeForRole / OnGettingAttributeForRole(属于 Cancellable Work Pattern 的一部分),处理器可通过 VisualRoleEventArgs.cs 的 Role 判断目标角色、用 Result + Handled 覆盖返回值。
  4. 状态修正: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 视觉体系。

登录后查看全文
Terminal.Gui