PTerm 示例库完全指南:89 个自包含示例的组织结构、本地运行与 VHS 动画生成管线

原创2026-10-14 18:31:011,870 阅读
文章标签:开发工具

PTerm 示例库完全指南:89 个自包含示例的组织结构、本地运行与 VHS 动画生成管线

本指南以 _examples/README.md 为骨架,系统讲解 PTerm 开源仓库中示例库的组织方式、本地运行方法、由 main.go 驱动的自动文档生成管线,并逐一梳理 27 个打印机家族共 89 个示例的用法要点与底层实现依据。读完本文,你将能快速定位任意功能对应的示例、在自己的终端里运行它们,并理解"源码即唯一事实来源"这一文档维护模式的完整链路。

一、示例库是什么:以 main.go 为核心的自包含示例集合

PTerm 的 _examples 目录是一个"活文档":它不只是展示效果的素材,更是每个功能的最小可运行示例。其组织原则有三条:

  • 每个示例都是小型的、自包含的程序:一个示例只演示一个打印机(printer)或一个特性,不依赖示例之间的共享代码;
  • 目录布局固定为 <printer>/<example>:外层目录是打印机家族名,内层是具体场景名;
  • 每个示例目录包含自己的 main.go,外加一份由脚本生成的 README.md 和动画。

以 area 家族为例,_examples/area 下有 6 个示例目录:demo、center、default、dynamic-chart、fullscreen、fullscreen-center,每个目录都是一个可直接 go run 的程序,例如 _examples/area/demo/main.go 演示了"用 BigText 渲染当前时间并实时刷新到 Area 中"的经典时钟场景。

二、快速开始:在本地运行任意示例

官方给出的运行方式极其简单——直接进入示例目录执行:

cd table/demo
go run main.go

由于每个示例都是自包含的 main.go,无需额外配置即可运行。例如 table/demo 会依次渲染两张表格:第一张用 WithHasHeader() 把首行作为表头并正确按显示宽度对齐中文字符("张"、"小宝"、"这是一个测试, haha!"),第二张演示单元格内含换行符时行高自动扩展:

tableData1 := pterm.TableData{
    {"Firstname", "Lastname", "Email", "Note"},
    {"Paul", "Dean", "augue@velitAliquam.co.uk", ""},
    {"Callie", "Mckay", "nunc.sed@est.com", "这是一个测试, haha!"},
    {"张", "小宝", "zhang@example.com", ""},
}

pterm.DefaultTable.WithHasHeader().WithData(tableData1).Render()

如果希望批量跑完所有示例做一次人工回归,仓库还提供了 _examples/test.sh:它遍历除 demo 外的所有示例目录逐个 go run main.go,并在每个示例运行后提示 Was the example successful? (y/n),输入非 y 会立即以红色路径输出失败示例并退出。

三、文档是生成的:main.go 是唯一事实来源

_examples/README.md 开篇就强调了一个重要事实:该 README 以及每个示例子目录中的 README 和动画,全部由动画管线从 main.go 自动生成。因此:

  • main.go 是唯一事实来源(single source of truth);
  • 不要手工编辑生成的部分(README 中的示例区块),否则会在下次管线运行时被覆盖。

3.1 管线入口:task animations

仓库根目录的 Taskfile.yml 定义了与示例相关的三个任务:

任务 命令 作用
animations scripts/animate.sh 渲染并发布全部示例动画,更新 README 与文档
animations:dry scripts/animate.sh --dry-run 本地录制示例、写入 golden 文件,跳过发布与文档更新
animate scripts/animate.sh --example "{{.CLI_ARGS}}" 只录制一个示例,例如 task animate -- logger/default

此外 test 任务使用 go test -race ./... 跑全仓测试。

3.2 录制脚本:record-example.sh

scripts/record-example.sh 承担单条示例的录制,关键步骤为:

  1. 检查交互式示例的自动化文件:如果示例路径以 interactive_* 开头,却没有 ci.go 或 keys.tape,脚本会发出警告——因为交互式组件需要按键输入才能完成演示(详见 4.6 节);
  2. 本地构建:在示例目录执行 go build -o .pterm-vhs-example .;
  3. 生成 VHS tape 脚本:设置 Output animation.gif、宽 1200、高 600、帧率 60、主题(默认 catppuccin-macchiato),并注入 options.tape / keys.tape 的按键序列;
  4. Docker 内录制:以 ghcr.io/charmbracelet/vhs:latest 镜像挂载仓库录制;
  5. 输出 golden 文件:每个示例的终端文本快照写入 testdata/raw/<printer>_<example>.txt,作为后续渲染与回归的基准;
  6. 发布 GIF:将动画发布到 vhs.charm.sh 并记录 URL 到 manifest TSV,供渲染阶段嵌入 README。

3.3 渲染脚本:render-animation-docs.sh

scripts/render-animation-docs.sh 读取 manifest 后完成整套文档更新:

  • 对每个示例重新生成 _examples/<printer>/<example>/README.md(内容为标题 + 动画 + 源码块);
  • 重新生成各打印机的 _examples/<printer>/README.md;
  • 通过 replace_between(定义于 scripts/animation-common.sh)把 <!-- examples:start --> 与 <!-- examples:end --> 之间的内容整体替换——这正是 _examples/README.md 中那个巨大示例区块和根 README.md 中示例区块的来源;
  • 重建根 README 的打印机列表表格,以及 docs/index.html 中网站侧栏的打印机清单;
  • 更新根 README 与 docs/index.html 中的 demo 动画图片链接。

给维护者的启示:想新增一个示例,只需在 _examples/<printer>/<example>/main.go 写好代码,运行 task animations:dry 本地验证,再运行 task animations 发布即可,文档、动画、golden 文件全部自动同步,无需手写任何 Markdown。

四、示例全图谱:27 个打印机家族的 89 个示例

以下按打印机家族分组,完整覆盖 _examples/README.md 中的全部示例,并给出关键 API 与源码依据。

4.1 实时输出:Area 与 MultiPrinter

area(6 个示例) 演示的是"原地重绘"能力——内容更新时不会追加新行,而是覆盖已绘制的区域。

示例 演示要点
area/demo 时钟效果:先打印固定文本,再在 Area 内每秒钟 Update 一次 BigText 渲染的时间,此前的内容保持不动
area/center WithCenter() 让区域内容在终端中水平居中
area/default 最基本的 DefaultArea.Start() / Update / Stop 循环
area/dynamic-chart 每 500ms 把柱状图 Srender 成字符串后 Update 进全屏 Area,形成动态图表
area/fullscreen WithFullscreen() 清屏并让 Area 占据整个终端
area/fullscreen-center WithFullscreen() + WithCenter() 组合,内容在整屏内居中

其核心实现见 area_printer.go:Update 方法(area_printer.go)会把传入内容存为 content,若设置了 Center 则先经 DefaultCenter.Sprint 居中;若设置了 Fullscreen 则按 GetTerminalHeight() 计算上下留白(居中时上下对半分),实现全屏占位。Stop(area_printer.go)在 RemoveWhenDone 为 true 时会调用 Clear 清掉内容。所有 With* 方法都遵循"返回修改后的副本"模式,原始 DefaultArea 不受影响。

multiple-live-printers(1 个示例) 展示了 DefaultMultiPrinter:通过 multi.NewWriter() 为每个 spinner / progressbar 分配独立写入器,全部 Start 后再 multi.Start() 统一渲染,各进度条以不同速率独立推进。

4.2 图表:BarChart(9 个示例)

示例 演示要点
barchart/default 默认垂直柱状图,每个标签位于对应柱子下方
barchart/demo 同一份数据分别渲染垂直与 WithHorizontal() 水平两种形态;超长标签展示水平图如何按最宽标签对齐
barchart/custom-height WithHeight(5) 把图表高度限制为 5 行,柱高按比例缩放
barchart/custom-width 水平模式下 WithWidth(5) 限制柱子向右延伸的最大宽度
barchart/horizontal WithHorizontal():每行一根柱,标签在柱前方
barchart/show-value WithShowValue():在垂直柱上方打印数值
barchart/horizontal-show-value 水平柱末尾打印数值
barchart/mixed-values 正负混合数据:图表区域在正负两侧之间分割
barchart/negative-values 全负值数据:柱子仍占满整个图表区域

底层默认值见 barchart.go:DefaultBarChart 的 Height 与 Width 分别取终端高宽的 2/3(GetTerminalHeight() * 2 / 3),竖柱字符默认 "██"、横柱字符默认 "█";终端尺寸变化后需要调用 pterm.go 中的 RecalculateTerminalSize() 重新同步(该函数同时刷新 DefaultParagraph.MaxWidth)。

4.3 大数据可视化:Heatmap(6 个示例)

示例 演示要点
heatmap/demo 基本用法:[][]float32 数据矩阵 + HeatmapAxis{XAxis, YAxis} 坐标轴标签,WithEnableRGB() 启用 TrueColor 平滑渐变
heatmap/custom_colors WithColors(pterm.BgBlue, ...) 用自定义 ANSI 背景色替代默认调色板,无需 RGB 支持、兼容所有终端
heatmap/custom_legend WithLegendLabel("custom") 改图例标题,WithLegendOnlyColoredCells() 隐藏图例中的数值只留色块
heatmap/custom_rgb WithRGBRange(...) 定义渐变关键点:最小值取第一个颜色、最大值取最后一个,中间平滑过渡
heatmap/no_grid WithGrid(false) 去掉单元格间分隔线,颜色连成连续平面
heatmap/separated WithBoxed(false).WithLegend(false) 去掉外框与图例,仅保留网格分隔

注意示例注释中的要点:坐标轴标签数量必须与矩阵严格对应——X 轴每列一个、Y 轴每行一个。

4.4 文本与样式:12 个家族的文本能力

basictext(1 个):DefaultBasicText 打印无样式纯文本,其价值在于实现了 TextPrinter 接口,可在任何期望样式打印器的地方无缝替换(接口定义见 interface_text_printer.go,含 Sprint / Println / Printf 等 10 个方法)。

bigtext(3 个):用 ASCII 大字母渲染标题屏。

示例 演示要点
bigtext/default putils.LettersFromString("PTerm") 把字符串转成 Letters 后交给 WithLetters 渲染
bigtext/colored 每个字母组独立着色:LettersFromStringWithStyle("P", pterm.FgCyan.ToStyle())
bigtext/demo 综合展示默认主题、分组着色、以及 LettersFromStringWithRGB("PTerm", pterm.NewRGB(255, 215, 0)) TrueColor 渲染(终端不支持时自动降采样)

coloring(8 个):颜色能力最丰富的家族。

示例 演示要点
coloring/demo 用表格展示全部 Fg* / Bg* 内置前景、背景色(含 Light 亮色变体);pterm.Red("...") 等简写函数可直接拼接、嵌套;NewStyle 组合多属性(如 BgRed + FgLightGreen + Bold)复用
coloring/disable-output DisableOutput() 全局静默所有 PTerm 打印器,EnableOutput() 恢复;实现见 pterm.go,两者均通过全局互斥锁保证并发安全
coloring/fade-colors startColor.Fade(0, 1, factor, endColor) 在终端高度范围内逐行渐变
coloring/fade-colors-rgb-style NewRGBStyle(fg, bg) 让前景与背景独立渐变,AddOptions(pterm.Bold) 在渐变之上叠加字重
coloring/fade-multiple-colors Fade 接受多个目标颜色,让渐变中途经过多个色点(横向逐字符 + 纵向逐行两种演示)
coloring/override-default-printers 默认打印器是包级变量,可直接改字段:pterm.Error.Prefix = pterm.Prefix{Text: "OVERRIDE", ...}
coloring/print-color-rgb NewRGB(r,g,b) 本身就是打印器;最后一个布尔参数为 true 时作用于背景色
coloring/print-color-rgb-style 手写 pterm.RGB{R,G,B} 结构体 + NewRGBStyle,AddOptions 返回新样式实现 Bold / Italic

center(1 个):默认整块居中(多行作为一个整体,保持内部左对齐,因此可以安全地居中其他打印器渲染的多行输出,如 BigText 的 Srender 结果);WithCenterEachLineSeparately() 则逐行独立居中。

style(1 个):NewStyle(FgLightCyan, BgGray, Bold) 组合任意颜色与文本选项;Style 本身也是 TextPrinter,可直接 Println。

theme(1 个):ThemeDefault 的每个字段都是普通 pterm.Style,示例用 reflect 反射遍历 pterm.Theme{} 的所有字段并各自打印字段名,直观展示每个主题样式的效果;覆盖主题只需给字段赋新的 Style。

header(2 个):header/demo 对比默认宽度(内容 + 边距)与 WithFullWidth() 全宽两种头部;header/custom 演示 WithMargin(15) + WithBackgroundStyle/WithTextStyle 即时换肤,以及从零构造 HeaderPrinter{TextStyle, BackgroundStyle, Margin}。

section(1 个):DefaultSection 把长输出组织成带标题的章节块;WithLevel(2) 渲染更小的子章节。

prefix(2 个):prefix/demo 演示 Debug(需先 EnableDebugMessages())、Info、Success、Warning、Error(默认附带文件名和行号)五种内置前缀打印器,WithShowLineNumber() 让其他 PrefixPrinter 也能显示行号,WithFatal(false) 关闭 Fatal 的退出行为;prefix/custom 从零构造自定义 PrefixPrinter,并通过 Scope{Text: "database"} 在前缀后附加带括号的子系统标签。

paragraph(2 个):按单词边界智能折行(不拆分单词);WithMaxWidth(60) 限制行宽;对比 Println 的"哪里溢出就在哪里断行"。

4.5 布局组件:Box、Panel、BulletList、Tree、Table

box(4 个):

示例 演示要点
box/default 盒子自动适应内容尺寸:DefaultBox.Println("Hello, World!")
box/custom-padding 四个方向独立设置内边距:WithRightPadding(10).WithLeftPadding(10).WithTopPadding(2).WithBottomPadding(2)
box/title 标题可放在边框任意一侧:WithTitleTopCenter / WithTitleTopRight / WithTitleBottomLeft 等 7 个位置;标题可以携带样式(如 pterm.LightRed(...));With* 返回副本使 paddedBox 可作模板复用
box/demo 组合拳:Box 通过 Sprint 渲染成字符串从而可以嵌套,DefaultPanel 把多个盒子排成网格,外层再套一个带标题的盒子

panel(2 个):panel/demo 演示 2D 网格结构(外层切片是行、内层切片是该行的面板),面板内容支持多行且可来自其他打印器(如 pterm.DefaultHeader.Sprint(...)),WithPadding(5) 控制行内面板间距;panel/boxed 用 WithBoxPrinter(pterm.DefaultBox) 给每个面板加框,WithSameColumnWidth() 把同一列的面板补齐到最宽者,使盒子整齐对齐。

bulletlist(2 个):bulletlist/demo 用 Level 控制缩进深度,或用 putils.BulletListFromString(text, " ") 从带缩进的字符串生成列表(第二个参数是缩进单位,一个空格对应一级);bulletlist/customized 让每个条目独立覆盖 Bullet 符号、BulletStyle 与 TextStyle。

tree(3 个):

示例 演示要点
tree/demo 手工嵌套 TreeNode{Text, Children} 构造树
tree/from-leveled-list putils.TreeFromLeveledList 把扁平 LeveledList{Level, Text} 转成 TreeNode(实现见 putils/tree_from_leveled_list.go,并自动修正非法层级跳变),再给根节点命名
tree/styled WithTreeStyle 着色分支线、WithTextStyle 着色节点文本

table(7 个):

示例 演示要点
table/demo WithHasHeader() 首行作表头;单元格按显示宽度对齐,中文/日文等 CJK 字符不会破坏列对齐;单元格可含换行、行高自适应
table/boxed WithBoxed() 给整表加外框
table/alternate-row-style WithAlternateRowStyle(NewStyle(BgDarkGray)) 给偶数数据行套样式,宽表更易扫描
table/multiple-lines WithRowSeparator("-") + WithHeaderRowSeparator("-") 用分隔线区分多行单元格
table/right-alignment WithRightAlignment() 全表右对齐
table/from-csv putils.TableDataFromCSV(csv) 把 CSV 转成 TableData(见 putils/tabledata_from_csv.go),CSV 首行经 WithHasHeader 成为表头
table/from-structs 普通 Go 结构体切片无需任何 tag:putils.DefaultTableFromStructSlice(users) 通过反射把字段名变成首行(见 putils/tabledata-from-struct-slice.go)

4.6 交互式组件:5 个家族 14 个示例

交互式示例在动画录制时需要按键驱动,因此 record-example.sh 要求它们携带 ci.go(交互注入)或 keys.tape(按键脚本),例如 _examples/interactive_select/demo/ci.go。

interactive_confirm(2 个):demo 用 y / n 快捷键作答,直接回车返回默认值(默认 false,可用 WithDefaultValue 改变);custom-answers 用 WithDefaultText("Do you want to apply the update?")、WithConfirmText("Apply")、WithRejectText("Cancel") 自定义文案,快捷键自动跟随首字母(a / c)。

interactive_continue(1 个):默认提供 yes / no / all / cancel 四个选项,输入首字母选择,回车取默认(默认第一个选项)。

interactive_select(2 个):demo 演示长列表滚动与模糊搜索过滤——直接输入即可收窄候选,回车选中高亮项;custom-filter-placeholder 用 WithFilterInputPlaceholder("🔍 Start typing") 替换过滤框为空时的提示文本。

interactive_multiselect(5 个):

示例 演示要点
demo 100+ 项长列表,默认 Enter 切换选中、Tab 确认提交
custom-checkmarks WithCheckmark(&pterm.Checkmark{Checked: pterm.Green("+"), Unchecked: pterm.Red("-")}) 自定义选中/未选中符号;WithFilter(false) 关闭过滤
custom-filter-placeholder 自定义过滤框占位文本
custom-keys WithKeyConfirm(keys.Enter) + WithKeySelect(keys.Space) 重绑定确认与切换按键(类型来自 atomicgo.dev/keyboard/keys,见 go.mod)
show-selected-options WithShowSelectedOptions(true) 在提示上方列出当前已选项,选项滚出视野时也能确认

interactive_textinput(4 个):demo 默认单行、回车提交;default-value 用 WithDefaultValue("Some default value") 预填建议值,直接回车返回它,输入任意字符则替换;multi-line 用 WithMultiLine() 切换为多行模式(回车换行、Tab 提交);password 用 WithMask("*") 以掩码回显实现密码输入。

4.7 进度反馈:Progressbar 与 Spinner

progressbar(3 个):demo 模拟下载列表,UpdateTitle 动态改标题,进度条运行期间通过 pterm 打印的内容会出现在条上方而非破坏条;custom-style 全面定制视觉——WithBarCharacter("#")、WithLastCharacter("#")、WithBarFiller("-")、WithBarPartialCharacters(nil)(清掉平滑块状边缘字符,避免与纯 # 冲突)、WithTitleStyle、WithBarStyle、WithShowElapsedTime(false);multiple 通过 MultiPrinter 同时运行 5 根进度条并以不同速率推进。

spinner(3 个):demo 演示 spinner 的四种终结方式 Info() / Success() / Warning() / Fail()(终结行会被对应前缀打印器替换)、自定义 InfoPrinter(如换成 NOCHG 前缀)、以及运行中 UpdateText 实时改文案;custom 用 WithSequence("▁","▃","▅","▇","▅","▃") 自定义帧序列 + WithStyle 着色;multiple 让多个 spinner 各自独立终结。

progressbar/multiple、spinner/multiple 与 multiple-live-printers 的共同点:它们都基于 pterm.DefaultMultiPrinter 的 NewWriter() 模式,先给每个 live printer 绑定独立 writer 并 Start,再启动 multi.Start() 统一渲染,最后 multi.Stop()。

4.8 结构化日志:Logger 与 slog

logger(5 个):

示例 演示要点
logger/demo WithLevel(pterm.LogLevelTrace) 把默认 Info 级别降到 Trace 以显示全部级别;logger.Args("k","v") 配对结构化字段,ArgsFromMap(map[string]any) 从已有 map 生成字段;超长消息自动折行;Fatal 记录后退出进程
logger/default 同上但不含演示性的睡眠与重复
logger/json WithFormatter(pterm.LogFormatterJSON) 每行输出一个 JSON 对象,便于生产环境机器解析
logger/with-caller WithCaller() 为每条消息附加调用处的文件与行号
logger/custom-key-styles WithKeyStyles(map[string]pterm.Style) 整体替换键样式表,AppendKeyStyle("foo", ...) 在既有样式之上追加单键样式

源码依据见 logger.go:DefaultLogger 默认 Formatter: LogFormatterColorful、Level: LogLevelInfo、TimeFormat: "2006-01-02 15:04:05"、MaxWidth: 80,且内置了 error、err、caller 三个键的特殊样式;日志级别枚举(logger.go)从 LogLevelDisabled 到 LogLevelPrint 共 8 级,每级样式定义在 ThemeDefault 中(见 LogLevel.Style())。

slog(1 个):pterm.NewSlogHandler(&pterm.DefaultLogger) 把 PTerm 日志器包装成标准库 log/slog 的 Handler,既有 slog 代码立刻获得 PTerm 的彩色输出;显示哪些级别由 PTerm 日志器决定(默认 Info 会吞掉 Debug),修改 pterm.DefaultLogger.Level = pterm.LogLevelDebug 即时生效。

4.9 综合演示:demo/demo

_examples/demo/demo/main.go 是全部能力的串场节目,依次展示结构化日志、进度条、spinner、Area 实时输出、表格、TrueColor 渐变、全自定义(通过 Area 反复换肤一个 Box)、主题、以及"更多";支持 -speedup(把 1 秒压缩到 200ms)与 -skip-intro 两个命令行 flag。它同时也是根 README 与 docs/index.html 中那张"PTerm demo animation"的来源(render-animation-docs.sh 会专门回填它的 GIF 链接)。

五、从示例中提炼的通用使用模式

通读 89 个示例,可以总结出四条贯穿始终的 API 设计模式,这也是把示例改造成自己应用骨架的关键:

  1. Sprint / Srender 是组合的关键:几乎所有打印机都能渲染成字符串(Sprint 系方法),因此可以任意嵌套组合——Box 套 Panel、Center 套 BigText、Area 套 BarChart。接口层面由 interface_text_printer.go 统一保证。
  2. With* 方法返回修改后的副本:如 box/title 中 paddedBox 作为模板反复 WithTitle* 复用而不被污染;AddOptions 同理返回新样式。默认打印器本身永远是安全的。
  3. 默认打印器是包级变量,可直接覆写:coloring/override-default-printers 与 spinner/demo 都展示了直接修改 pterm.Error.Prefix、spinnerNochange.InfoPrinter 这类字段来全局换肤。
  4. putils 负责"数据转换":字符串→Letters(putils/letters_from_string.go)、CSV/结构体→TableData、缩进字符串→BulletList(putils/bullet_list.go)、LeveledList→TreeNode,完整清单见 putils/README.md。把业务数据先用 putils 转成 PTerm 类型,再交给打印器,是最顺滑的接入方式。

六、输出验证与回归

示例与测试并非割裂的:record-example.sh 每次录制都会把终端文本快照写入 testdata/raw(如 area_default.txt、logger_json.txt),这些 golden 文件既是文档生成的输入,也构成渲染结果的回归基准;仓库另有一套基于快照的测试(见根目录 snapshot_test.go 与 testdata/snapshots),确保打印器输出不发生意外变化。因此,修改示例代码后请务必运行 task test(即 go test -race ./...)与 task animations:dry 双重验证。

七、小结

_examples 目录是 PTerm 的"可运行文档":main.go 是唯一事实来源,task animations 管线(Taskfile.yml → scripts/animate.sh → scripts/record-example.sh + scripts/render-animation-docs.sh)自动产出 README、动画与 golden 文件。89 个示例覆盖实时输出、图表、热力图、颜色、布局、交互组件、进度条、日志与综合演示九大类能力。对使用者而言,最快的上手路径是:cd _examples/<printer>/<example> && go run main.go,然后照着 main.go 把 With* 配置替换成自己的数据与样式。

登录后查看全文
pterm