PTerm 示例库完全指南:89 个自包含示例的组织结构、本地运行与 VHS 动画生成管线
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 承担单条示例的录制,关键步骤为:
- 检查交互式示例的自动化文件:如果示例路径以
interactive_*开头,却没有ci.go或keys.tape,脚本会发出警告——因为交互式组件需要按键输入才能完成演示(详见 4.6 节); - 本地构建:在示例目录执行
go build -o .pterm-vhs-example .; - 生成 VHS tape 脚本:设置
Output animation.gif、宽 1200、高 600、帧率 60、主题(默认catppuccin-macchiato),并注入options.tape/keys.tape的按键序列; - Docker 内录制:以
ghcr.io/charmbracelet/vhs:latest镜像挂载仓库录制; - 输出 golden 文件:每个示例的终端文本快照写入
testdata/raw/<printer>_<example>.txt,作为后续渲染与回归的基准; - 发布 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 设计模式,这也是把示例改造成自己应用骨架的关键:
Sprint/Srender是组合的关键:几乎所有打印机都能渲染成字符串(Sprint系方法),因此可以任意嵌套组合——Box 套 Panel、Center 套 BigText、Area 套 BarChart。接口层面由 interface_text_printer.go 统一保证。With*方法返回修改后的副本:如box/title中paddedBox作为模板反复WithTitle*复用而不被污染;AddOptions同理返回新样式。默认打印器本身永远是安全的。- 默认打印器是包级变量,可直接覆写:
coloring/override-default-printers与spinner/demo都展示了直接修改pterm.Error.Prefix、spinnerNochange.InfoPrinter这类字段来全局换肤。 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* 配置替换成自己的数据与样式。