企业官网建设流程全解析

V 语言 term 模块实战指南：用 ANSI 转义码实现终端着色、光标定位与基础 TUI

【免费下载链接】vSimple, fast, safe, compiled language for developing maintainable software. Compiles itself in <1s with zero library dependencies. Supports automatic C => V translation. https://vlang.io项目地址: https://gitcode.com/GitHub_Trending/v/v

term是 V 语言标准库中面向终端的基础模块，它为构建"极简 TUI（文本用户界面）"提供积木式能力：给输出文本着色/加样式、查询终端尺寸、精确控制光标位置、读取按键输入。本文以 vlib/term/README.md 为骨架，结合 colors.v、control.v、term.v 等源码与 term_test.v 测试用例，讲透 term 模块的每个 API 及其底层 ANSI 原理，并给出可直接复制运行的完整示例。读完你将能够：用十几行 V 代码写出"清屏 + 居中着色输出 + 光标定位 + 按键退出"的终端程序，并理解何时该从term升级到term.ui。

term 模块的定位：极简 TUI 的积木，而非完整框架

文档开篇即明确了 term 的边界：它专为构建非常简单的 TUI 应用而设计，提供的是"构建积木"（building blocks）。如果你需要更复杂的应用——涉及终端事件（键盘/鼠标）、更高的绘制性能、复杂的布局——应当转向term.ui模块（源码位于 vlib/term/ui/，含完整 Quickstart 与配置说明），它内建了事件循环、逐帧回调（frame_fn）、矩形/文本绘制原语，以及frame_rate、hide_cursor、capture_events、mouse_enabled等完整配置项。

从源码结构上看，term模块的核心能力恰好分为两大块（对应 colors.v 与 control.v 两个文件）：

1. 着色输出：把任意字符串包裹上 ANSI 颜色/样式转义码；
2. 位置控制：查询与移动光标、查询与清除屏幕区域。

快速上手：在终端正中央打印一行彩色文字

README 提供了一个覆盖模块主要特性的完整示例：清屏 → 获取终端尺寸 → 把光标移到屏幕正中央 → 打印"绿色 + 删除线"样式的文本 → 把光标移到屏幕底部 → 等待用户按q退出。

import term import os fn main() { term.clear() // clears the content in the terminal width, height := term.get_terminal_size() // get the size of the terminal term.set_cursor_position(x: width / 2, y: height / 2) // now we point the cursor to the middle of the terminal println(term.strikethrough(term.bright_green('hello world'))) // Print green text term.set_cursor_position(x: 0, y: height) // Sets the position of the cursor to the bottom of the terminal // Keep prompting until the user presses the q key for { if var := os.input_opt('press q to quit: ') { if var != 'q' { continue } break } println('') break } println('Goodbye.') }

这个程序虽小，却演示了 term 模块的四个关键特性，也揭示了两个容易被忽视的要点：

• 坐标从 1 开始：set_cursor_position的x、y是 1-based 坐标，因此把光标定位到width / 2, height / 2就是"正中"，x: 0, y: height则是"最左侧 + 最后一行"。
• 样式可以嵌套叠加：strikethrough(bright_green('hello world'))把"亮绿色前景"和"删除线"两个 SGR 属性组合到同一段文本上，这是由 colors.v 中format(msg, open, close)的"前开后关"配对机制天然支持的。

关键方法在底层做了什么

注意：clear()、get_terminal_size()等在非 TTY 环境（如管道重定向、TERM=dumb）下会返回 false 或回退到默认值80×25（见 term.v），这是编码时需要自行处理的边界情况。

颜色与消息 API 详解

README 的 API 章节强调了一个极易踩坑的重要事实：ok_message、yellow、bold这类着色/样式函数本身并不会打印任何东西——它们只是返回一段嵌入了 ANSI 转义码的新字符串，你必须把它交给println（或写入 stdout 的类似函数）才能真正显示。

完整的 API 演示程序

import term import os // returns the height and the width of the terminal width, height := term.get_terminal_size() println('terminal dimensions: width: ${width} height: ${height}') mut output := '' // returns the string as green text output = 'ok_message() text ' + term.ok_message('is green') println(output) // returns the string as red text output = 'fail_message() text ' + term.fail_message('is red') println(output) // returns the string as yellow text output = 'warn_message() text ' + term.warn_message('is yellow') println(output) os.input('hit Enter to clear the console and continue') // clears the entire terminal term.clear() // Set the color output of the text. // The available colors are: // black, white, blue, yellow, // green, red, cyan, magenta, // bright_black, bright_white, bright_blue, bright_yellow, // bright_green, bright_red, bright_cyan, bright_magenta, output = 'yellow() - ' + term.yellow('text') println(output) // transforms the given string into bold text output = 'bold() - ' + term.bold('text') println(output) // puts a strikethrough into the given string output = 'strikethrough() - ' + term.strikethrough('text') println(output) // underlines the given string output = 'underline() - ' + term.underline('text') println(output) // colors the background of the output following the given color // the available colors are: black, blue, yellow, green, cyan, gray output = 'bg_green() - ' + term.bg_green('text') println(output) // sets the position of the cursor term.set_cursor_position(x: 5, y: 10) println('Cursor at (5,10)') // flashes (blinks) the text output = term.slow_blink('done') println(output)

三种语义化消息函数：ok / fail / warn

• term.ok_message(s)—— 绿色文本（green），表示成功；
• term.fail_message(s)—— 红色文本，实为failed()，即"亮白字 + 红底 + 加粗"（bg_red(bold(white(s)))），比普通红字更醒目，见 term.v；
• term.warn_message(s)—— 亮黄色文本（bright_yellow），表示警告。

三者都带颜色可用性保护：当终端不支持转义序列时（例如输出被重定向到文件），它们会原样返回传入字符串，而不是输出一堆\x1b[...m乱码。判断逻辑集中在supports_escape_sequences()（term.v）：

1. 环境变量VCOLORS=always→ 强制启用颜色；
2. VCOLORS=never→ 强制禁用；
3. TERM=dumb→ 禁用；
4. 否则检查 stdout/stderr 是否为 TTY（Windows 上还会额外判断ConEmuANSI=ON或是否启用了虚拟终端处理标志）。

判定结果会被缓存到__global can_show_color_on_stdout_cache/can_show_color_on_stderr_cache，避免每次调用都做系统调用。colorize(cfn, s)与ecolorize(cfn, s)则把这种"条件着色"封装成了函数式风格：term.colorize(term.yellow, 'the message')。

全部前景色/背景色/样式速查

结合 colors.v 源码，term模块实际上提供了远超 README 列表的完整 SGR 调色板：

标准前景色：black(30)、red(31)、green(32)、yellow(33)、blue(34)、magenta(35)、cyan(36)、white(37)；亮色前景：bright_black(90)、bright_red(91)、bright_green(92)、bright_yellow(93)、bright_blue(94)、bright_magenta(95)、bright_cyan(96)、bright_white(97)；其中gray等价于bright_black；背景色：bg_black(40) 至bg_white(47) 的八种标准色，加上bright_bg_black(100) 至bright_bg_white(107) 八种亮色；文本样式：bold(1/22)、dim(2/22)、italic(3/23)、underline(4/24)、slow_blink(5/25)、rapid_blink(6/26)、inverse(7/27)、hidden(8/28)、strikethrough(9/29)、reset(0)。

括号中的两个数字即format(msg, open, close)的"开启码/关闭码"配对，例如yellow('text')实际返回'\x1b[33mtext\x1b[39m'。测试 term_test.v 验证了这些嵌套样式可以被term.strip_ansi()干净地剥离回纯文本。

24 位真彩色支持：rgb(r, g, b, msg)与bg_rgb(r, g, b, msg)使用\x1b[38;2;r;g;bm/\x1b[48;2;r;g;bm扩展序列；hex(hex, msg)与bg_hex(hex, msg)则接受 0xRRGGBB 形式的整数并自动拆分为 RGB 分量（见 colors.v）。注意旧式 16 色终端可能不支持这些扩展序列。

为日志/进度条场景设计的辅助函数

• strip_ansi(text)：移除文本中的所有 ANSI 序列（处理 CSI、OSC、%三种转义形式），常用于日志清洗或计算"纯文本宽度"；
• h_divider(divider)：返回一条铺满当前终端宽度的水平分隔线（若传空字符串则用空格撑满一行），见 term.v；
• header(text, divider)/header_left(text, divider)：生成"居中标题"或"左对齐标题"的装饰线，如==== TITLE ====...，标题超长时会按终端宽度自动截断。

低级光标控制与屏幕擦除

README 还列出了一些直接写 stdout的低级光标辅助函数，它们不再返回字符串，而是立即输出控制序列：

import term // moves the cursor up term.cursor_up(1) // moves the cursor down term.cursor_down(1) // moves the cursor to the right term.cursor_forward(2) // moves the cursor to the left term.cursor_back(2) // hides the cursor term.hide_cursor() // shows the cursor term.show_cursor()

这些函数只是move(n, direction)的封装，最终输出\x1b[nA（上）、\x1b[nB（下）、\x1b[nC（右）、\x1b[nD（左）四种 CSI 光标移动序列，方向由A/B/C/D字母决定（control.v）。hide_cursor()/show_cursor()则分别输出\x1b[?25l/\x1b[?25h，是"进度条刷新"和"全屏 TUI"场景的常用组合。

term模块还提供了一整套屏幕擦除原语，适合实现进度条与局部刷新（control.v）：

最后一个clear_previous_line()是官方注释钦点的"进度条利器"——它保证下一次println直接覆盖上一行的内容，不会产生滚动。

交互输入：读按键、读光标、改终端标题

虽然 README 的主示例用os.input_opt实现"按 q 退出"，但term模块本身（尤其非 Windows 平台）还内置了更底层的输入能力，可直接支撑简单的交互逻辑：

• key_pressed(blocking: true, echo: false)：临时关闭 ICANON（行缓冲）与 ECHO，逐字符读取标准输入；非阻塞模式下无按键时返回-1。底层通过termios修改终端属性并在结束时恢复原状（term_nix.c.v）。Windows 实现则基于kbhit()/_getch()，函数键（方向键等）会返回0xE0与真实键码的合成值（term_windows.c.v）；
• utf8_getchar()：从标准输入读取一个完整的 UTF-8 字符（rune），内部按首字节推断后续字节数并逐字节拼装（utf8.v）；
• get_cursor_position() !Coord：发送 DSR 请求序列\e[6n，解析终端回传的ESC [ y ; x R应答（term_nix.c.v）。测试 term_test.v 验证了 set 后再 get 能取回相同坐标；需要注意哑终端（dumb）上该调用返回Coord{0, 0}；
• set_terminal_title(title)/set_tab_title(title)：分别输出\033]0;...\007与\033]30;...\007修改窗口/标签页标题（term_nix.c.v）；Windows 上通过SetConsoleTitle实现，且set_tab_title目前等价于设置窗口标题（term_windows.c.v）；
• enable_echo(enable)：开启/关闭输入回显（ECHO标志），Windows 上为空操作（由key_pressed的 echo 参数承担）；
• supports_sixel()与graphics_num_colors()：探测终端对 Sixel 图形协议的支持情况与色彩寄存器数量，用于判断能否直接向终端输出 Sixel 位图。Linux 平台通过关闭回显后发送设备查询序列\e[c并解析应答实现（term_nix.c.v）；Windows Console 目前不支持，两个函数固定返回false/0（term_windows.c.v）。

平台差异与回退行为

term 模块采用平台分文件编译，同名公开函数在不同平台有不同实现：

• 类 Unix（Linux/macOS/BSD 等）：get_terminal_size()走ioctl + TIOCGWINSZ；clear()、get_cursor_position()等基于 ANSI 序列与 termios；
• Windows：get_terminal_size()走 Win32 控制台 API（GetConsoleScreenBufferInfo读取窗口矩形），clear()通过ScrollConsoleScreenBuffer实现，语义与 ANSI 清屏一致；
• JavaScript 后端：还存在独立的 term.js.v 实现；
• 公共回退：stdout 非 TTY 或TERM=dumb时，get_terminal_size()返回默认值80×25（常量default_columns_size/default_rows_size，term.v）。

何时升级到 term.ui

README 的定位非常清晰：term 只适合"非常简单"的 TUI。当你的应用出现以下任一诉求时，就应转向 vlib/term/ui/README.md 中的term.ui：

1. 需要键盘/鼠标事件（如.key_down、.mouse_*），而不是裸读按键；
2. 需要按frame_rate（默认 30fps）驱动逐帧重绘，且对大屏绘制有性能要求；
3. 需要矩形、文本等绘制原语和完整的初始化/清理生命周期（init_fn、frame_fn、cleanup_fn、fail_fn回调）；
4. 需要 raw 模式拦截ctrl+c、ctrl+z（capture_events）或终端鼠标追踪（mouse_enabled）。

term.ui的 Quickstart 只用了约 30 行代码就完成了一个"按键退出 + 绘制矩形与文本"的可交互程序，而同样的能力若用纯term实现将需要自行维护事件循环与差分绘制——这正是文档建议"复杂应用用 term.ui"的根本原因。真实范例可参考 examples/term.ui/ 下的pong.v、text_editor.v、vyper.v等程序。

小结与验证

term模块的完整能力可归纳为三条主线：条件化 ANSI 着色（含 16/24 位色与全部样式）、光标与屏幕区域控制、终端状态查询与底层输入。所有函数要么"返回带转义码的字符串"（着色/样式类），要么"直接写 stdout"（控制类），理解这一二分法就不会再用错。

仓库自带的测试 term_test.v 为上述行为提供了可执行佐证：test_get_terminal_size断言终端宽度大于 0；test_header系列断言各种标题/分隔线长度与终端宽度一致；test_get_cursor_position验证光标坐标可被 set/get 往返一致；test_strip_ansi验证多层嵌套样式可被完整剥离；test_write_color则检查ColorConfig（styles/fg/bg/custom字段）拼装出的 SGR 序列格式（如\x1b[1;3;4;31;46m）。运行v test vlib/term/即可在本地复现这些验证，动手改一改示例里的颜色与坐标，是理解 ANSI 终端编程最快的路径。

【免费下载链接】vSimple, fast, safe, compiled language for developing maintainable software. Compiles itself in <1s with zero library dependencies. Supports automatic C => V translation. https://vlang.io项目地址: https://gitcode.com/GitHub_Trending/v/v