• 指标监控
• 开发工具

termui v3 是 gotop 的核心 UI 渲染引擎——一个基于 termbox-go 构建、纯 Go 编写的跨平台终端仪表盘与 Widget 库。本文以仓库中 vendored 的 termui v3 README 为主体骨架，结合 gotop 主程序与src/termui的实战代码，完整讲解 termui 的初始化、渲染管线、事件循环、Grid 布局、主题样式，以及如何像 gotop 一样利用它快速搭建可交互的 TUI 监控面板。读完本文，你将掌握 termui v3 从"Hello World"到复杂仪表盘的完整开发链路，并能理解 gotop 每个终端像素背后的渲染机制。

termui v3 是什么

根据 vendor/github.com/gizak/termui/v3/README.md 中的官方定位，termui 是一个跨平台、完全可定制的终端仪表盘（dashboard）与 Widget 库，构建于 termbox-go 之上，灵感来自 blessed-contrib 与 tui-rs，并以纯 Go 编写。它把"在终端里画界面"这件底层工作抽象为两个层次：

• 底层：由 termbox-go 直接管理终端屏幕的 cell（字符单元）、输入输出模式与颜色属性；
• 上层：termui 提供 Widget（部件）、Buffer（画布）、Grid（网格布局）、事件循环与主题系统，开发者只需声明式地组装组件即可。

在 gotop 中，这一关系体现得十分清晰：项目根目录的 go.mod 声明了对github.com/gizak/termui/v3 v3.0.0的直接依赖；而 src/termui 目录则是在 termui v3 之上扩展的自定义 widget 层（LineGraph、SparklineGroup、Table），主程序 main.go 通过ui "github.com/gizak/termui/v3"的别名导入使用。可以说，gotop 就是 termui v3 最典型的大型实战案例（README 的 Uses 一节也明确列出了 gotop）。

核心特性一览

原文档 Features 一节总结了 termui v3 的五大能力，结合源码可以逐条印证其实现：

安装与引入

原文档给出的安装方式为：

go get github.com/gizak/termui/v3

在 gotop 仓库中，termui v3 以 vendor 形式固化在vendor/github.com/gizak/termui/v3目录，并通过 go.mod 锁定版本v3.0.0，保证构建可复现。开发者在使用时只需：

import ( ui "github.com/gizak/termui/v3" "github.com/gizak/termui/v3/widgets" )

其中widgets子包提供了官方预置 Widget；gotop 则选择在src/termui中基于 termui v3 的Block、Buffer、Color等基础类型自行扩展更贴合监控场景的 Widget。

Hello World：最小的 termui 程序

原 README 给出了一个 25 行的完整示例，这里逐行拆解其运行机制：

package main import ( "log" ui "github.com/gizak/termui/v3" "github.com/gizak/termui/v3/widgets" ) func main() { if err := ui.Init(); err != nil { log.Fatalf("failed to initialize termui: %v", err) } defer ui.Close() p := widgets.NewParagraph() p.Text = "Hello World!" p.SetRect(0, 0, 25, 5) ui.Render(p) for e := range ui.PollEvents() { if e.Type == ui.KeyboardEvent { break } } }

这段程序演示了 termui 应用的四个固定步骤：

1. 初始化与收尾：ui.Init()必须在任何渲染前调用，程序结束前必须ui.Close()。查看 backend.go 可以看到Init()实际做了三件事：调用tb.Init()初始化 termbox-go；tb.SetInputMode(tb.InputEsc | tb.InputMouse)开启 ESC 序列与鼠标输入；tb.SetOutputMode(tb.Output256)启用 256 色输出。
2. 创建 Widget：widgets.NewParagraph()创建一个段落部件，设置文本后通过SetRect(x1, y1, x2, y2)以绝对坐标指定其在终端中的矩形区域（起点与终点，右开区间）。
3. 渲染：ui.Render(p)将 widget 绘制到终端。渲染管线见下文"渲染原理"一节。
4. 事件循环：ui.PollEvents()返回一个只读 channel，range遍历即阻塞等待用户输入；示例中收到任意键盘事件即退出。

gotop 的初始化顺序对照

gotop 的 main.go 在主流程中同样严格遵循"先ui.Init()→ 配置主题 → 创建 Widget → 组 Grid → 渲染 → 事件循环"的顺序：

if err := ui.Init(); err != nil { stderrLogger.Fatalf("failed to initialize termui: %v", err) } defer ui.Close() setDefaultTermuiColors() // 先设置全局主题，Widget 创建时才能继承颜色 initWidgets() setWidgetColors() setupGrid() termWidth, termHeight := ui.TerminalDimensions() grid.SetRect(0, 0, termWidth, termHeight) ui.Render(grid) eventLoop()

这里还用到了 backend.go 中提供的ui.TerminalDimensions()（内部先tb.Sync()再取tb.Size()），以全屏尺寸初始化 Grid。

Widget 体系：预置部件与自定义部件

官方预置 Widget 列表

原 README 完整列出了 termui v3 官方 widgets 包提供的 12 类部件，每一类都配有可运行的示例：

• BarChart：柱状图
• Canvas：基于 braille（盲文点阵）绘制的自由画布
• Gauge：进度条/仪表
• Image：终端图片显示
• List：列表
• Paragraph：段落文本（Hello World 示例即用它）
• PieChart：饼图
• Plot：散点图与折线图
• Sparkline：迷你走势线
• StackedBarChart：堆叠柱状图
• Table：可滚动、可交互的表格
• Tabs：标签页

原文档说明可用go run _examples/{example}.go运行单个示例，或用make run-examples依次运行全部示例。

gotop 的自定义 Widget 实战

gotop 并没有直接使用上述预置部件，而是在 src/termui 中基于 termui v3 的基础类型（Block、Buffer、Color、NewStyle、TrimString等）实现了三个自定义 Widget，这是"如何创建自定义 Widget"的最佳教材：

• LineGraph：折线图。它内嵌*Block并重写Draw(buf *Buffer)方法；渲染时先把数据点画到 drawille 画布（每个 braille 字符含 2x4 个点），再统一拷贝到 Buffer，最后叠加图例与标签。CPU 与内存曲线即由此绘制（见 src/widgets/cpu.go 与 src/widgets/mem.go）。
• SparklineGroup：迷你走势线组。通过BARS字符集（如▁▂▃▄▅▆▇█）按数据相对最大值映射字符高度，网络流量监控使用它（见 src/widgets/net.go）。
• Table：进程表格。内置ScrollUp/ScrollDown/ScrollTop/ScrollBottom/ScrollPageUp/ScrollPageDown/HandleClick等完整的滚动与鼠标点击支持，进程列表（见 src/widgets/proc.go）基于它实现k/j、<C-d>/<C-u>、鼠标滚轮等交互。

布局系统：Grid 相对布局与绝对坐标

Grid 相对布局

grid.go 实现了类似前端 CSS Grid 的相对比例布局：NewRow(ratio, ...)按宽度比例横向切分，NewCol(ratio, ...)按高度比例纵向切分，Set(...)将叶子 Widget 加入网格并递归计算其相对位置与尺寸。gotop 的 main.gosetupGrid()是教科书式的用法——三行三等分，第二行再纵向切分为左右两列，左侧继续横向二分放磁盘与温度：

grid.Set( cpuRow, // 1/3：CPU（或带电池的 CPU+电池） ui.NewRow(1.0/3, ui.NewCol(1.0/3, ui.NewRow(1.0/2, disk), ui.NewRow(1.0/2, temp), ), ui.NewCol(2.0/3, mem), ), ui.NewRow(1.0/3, ui.NewCol(1.0/2, net), ui.NewCol(1.0/2, proc), ), )

从Grid.Draw的实现可以看到，每个叶子部件按XRatio/WidthRatio换算成实际像素矩形后调用entry.SetRect(...)再entry.Draw(buf)，这正是"相对定位"的底层落地方式。

绝对坐标定位

除 Grid 外，termui 也支持SetRect(x1, y1, x2, y2)式的绝对坐标。gotop 的状态栏（StatusBar）即采用绝对定位：当启用-s/--statusbar时，主程序把 Grid 压到(0, 0, termWidth, termHeight-1)，而状态栏固定在(0, termHeight-1, termWidth, termHeight)一行内，实现"底部状态栏 + 上方仪表盘"的经典布局。

终端缩放响应

<Resize>事件配合 Grid 即可实现自适应布局。gotop 事件循环中收到<Resize>后重新计算终端尺寸并grid.SetRect(...)，随后ui.Clear()并重新ui.Render(grid)，保证窗口变化后面板即时重排。

事件系统：键盘、鼠标与缩放

events.go 定义了三种事件类型：

type EventType uint const ( KeyboardEvent EventType = iota MouseEvent ResizeEvent )

每个Event包含Type、ID（字符串标识）与Payload。PollEvents()内部启动 goroutine 持续调用 termbox 的PollEvent()并转换后送入 channel。

键盘事件被转换为易读的字符串形式，例如j、<C-d>（Ctrl+d）、<M-d>（Alt+d）、<Up>、<F1>、<Enter>、<Space>等；功能键、方向键与组合键的完整映射表见 events.go 中的keyboardMap（注意文档同时指出<C-h>、<C-i>、<C-m>等因终端转义冲突不可用）。

鼠标事件的ID为<MouseLeft>/<MouseRight>/<MouseMiddle>/<MouseWheelUp>/<MouseWheelDown>/<MouseRelease>，Payload为Mouse{X, Y, Drag}结构。

缩放事件的ID为<Resize>，Payload为Resize{Width, Height}。

gotop 的 main.goeventLoop()完整演绎了这套系统的用法：select同时监听ui.PollEvents()与系统信号；q、<C-c>退出；h/l调节折线图水平缩放；k/j/<Up>/<Down>/滚轮滚动进程表；<MouseLeft>点击定位进程行；<Tab>切换分组视图；m/c/p切换进程排序方式。整个 gotop 的交互体验全部建立在这三类事件之上。

颜色与样式系统

Style 与 Color

style.go 定义了样式基础：

• Color是取值 -1 到 255 的整数：-1 为ColorClear（清除颜色），0-255 对应 Xterm 256 色；同时提供ColorBlack/Red/Green/Yellow/Blue/Magenta/Cyan/White八种基本色常量。
• Modifier支持ModifierBold、ModifierUnderline、ModifierReverse（反显）三种修饰，位运算组合使用。
• Style{Fg, Bg, Modifier}描述一个终端 cell 的完整外观；NewStyle(fg, bg?, modifier?)按 1 到 3 个参数构造样式。

全局主题 Theme

theme.go 导出一个全局Theme变量（RootTheme结构），为所有 Widget 提供默认颜色：包括Block.Title/Border、BarChart、Gauge、Plot、List、Paragraph、PieChart、Sparkline、StackedBarChart、Tab、Table各自的主题结构。在创建 Widget 之前修改Theme，即可让新部件自动继承全局配色。

gotop 正是利用这一机制实现配色方案切换的。main.go 的setDefaultTermuiColors()根据所选 colorscheme 覆盖全局主题：

ui.Theme.Default = ui.NewStyle(ui.Color(colorscheme.Fg), ui.Color(colorscheme.Bg)) ui.Theme.Block.Title = ui.NewStyle(ui.Color(colorscheme.BorderLabel), ui.Color(colorscheme.Bg)) ui.Theme.Block.Border = ui.NewStyle(ui.Color(colorscheme.BorderLine), ui.Color(colorscheme.Bg))

随后setWidgetColors()再对每个 Widget 的线条颜色、进程光标色、温度色等做精细化赋值。仓库 colorschemes 目录下的 default、default-dark、solarized、monokai、vice 配色均可通过gotop -c/--color切换（还支持加载用户自定义 JSON 配色文件）。

渲染原理：从 Widget 到终端像素

渲染的核心在 render.go 与 buffer.go：

1. Drawable 接口：所有可渲染部件必须实现GetRect()/SetRect(...)/Draw(*Buffer)与sync.Locker（block.go 中的Block已实现全部接口，因此它是大多数 Widget 的基类）。
2. Buffer 中间层：Buffer本质是map[image.Point]Cell的矩形区域，Cell{Rune, Style}是终端的单个字符单元。Buffer.Fill/SetCell/SetString支持批量写入，且SetString通过 go-runewidth 正确处理 CJK 等宽字符。
3. Render 汇聚：Render(items ...Drawable)为每个部件新建 Buffer，加锁调用Draw(buf)，再把 Buffer 中的每个 cell 经tb.SetCell写入 termbox，最后tb.Flush()一次性刷新到屏幕。注意Draw与Render之间通过互斥锁保护，保证多 goroutine 更新数据（如 gotop 各 widget 后台定时采样）时渲染线程安全。

Braille 高分辨率技巧：普通终端 cell 只能显示一个字符，termui 的 Canvas（canvas.go）与 gotop 的 LineGraph 都借助 braille 字符（每个字符 2x4 点阵）实现"亚字符"级图形。gotop 的折线图在 src/termui/linegraph.go 中把每个数据点映射到 2x4 网格坐标，再通过drawille.Line连线并写入 braille cell，这就是 CPU 曲线在终端中看起来平滑细腻的原因。

Block 基类：边框、标题与内边距

自定义 Widget 通常直接内嵌*Block。从 block.go 可以看到 Block 管理的位置与外观要素：

• Border开关与BorderLeft/Right/Top/Bottom四边独立控制（默认全部开启，NewGrid()会关闭边框）；
• PaddingLeft/Right/Top/Bottom内边距，在SetRect时自动计算Inner内矩形（外边线各占 1 格，内边距再收缩），子类只在Inner区域内绘制内容；
• Title与TitleStyle标题，绘制在左上角Min.X+2处。

gotop 各 widget 均以self.Title = " CPU Usage "这样的形式设置标题，边框与标题外观统一由全局Theme.Block控制。

探索与运行

• 查看源码：termui v3 的完整实现位于 vendor/github.com/gizak/termui/v3（含 CHANGELOG.md 与 LICENSE）；gotop 的实战扩展见 src/termui，使用方式见 main.go。
• 体验 gotop：仓库 README.md 提供了从源码（go get github.com/cjbassi/gotop）、预编译二进制（scripts/download.sh）、AUR、FreeBSD pkg、Homebrew、Snap 等多种安装途径。

许可证

termui v3 以 MIT 许可证开源，见 LICENSE；gotop 项目本体同样采用 MIT 许可证（根目录 LICENSE）。

总结：termui v3 用一套简洁的抽象——Drawable接口、Buffer中间层、Grid 相对布局、三类输入事件与全局主题——把终端 UI 开发从"逐个 cell 操作"提升到"组装部件"的层面。gotop 正是这套 API 的深度实践：12 个官方预置 Widget 覆盖通用场景，src/termui的自定义 Widget 证明其扩展边界几乎没有限制。无论你是想为 gotop 二次开发新监控面板，还是从零构建自己的 TUI 工具，本文所述的内容都构成了完整的地基。

• 指标监控
• 开发工具