Go go-runewidth 怎样按终端列宽截断中文文本

在终端表格里把中文列和英文列放在一起时，len(s) 得到的是字节数，utf8.RuneCountInString 得到的是码点数量，它们都不能直接代表光标要占的列数。Go 使用 github.com/mattn/go-runewidth 时，可以让 Truncate 按显示单元格宽度截断，并把省略号一起算进总宽度。

官方地址：https://pkg.go.dev/github.com/mattn/go-runewidth

需要把字符串限制在终端列宽内时，先用 StringWidth 理解显示宽度，再调用 Truncate(s, w, tail)。第三个参数不是装饰，它也会占用 w 的单元格预算；中文、组合字形和东亚宽度配置则决定真正能保留多少内容。

把字节长度问题换成显示列宽

终端排版关注的是 cell（显示单元格）。ASCII 字母通常占一列，中文通常占两列；同一个字符串的字节数、码点数和显示列数可能完全不同。比如中文 UTF-8 往往每个字占多个字节，但这不意味着终端要为每个字节留一个位置。

runewidth.StringWidth 返回字符串的显示宽度，RuneWidth 则用于观察单个 rune 的宽度。它们适合给表格列、状态栏和命令行提示做预算。本文的判断对象是终端列宽，不是浏览器 CSS 像素，也不是字体排版引擎的精确像素。

用 Truncate 预留尾标记

最常见的运行手册场景是：日志表格的“对象名称”最多显示 20 列，超出后追加 ...。不要先切字符串再拼省略号，因为切分位置可能落在中文显示宽度或组合字形的错误边界上。把完整文本、总列宽和尾标记一次交给 Truncate 即可。

package main

import (
	"fmt"

	"github.com/mattn/go-runewidth"
)

func main() {
	name := "订单：华东仓库-蓝色纸箱-待发货"
	const columnWidth = 20
	const tail = "..."

	// 先观察显示列宽，不用 len 判断终端占位。
	fmt.Printf("原文列宽=%d，尾标记列宽=%d\n",
		runewidth.StringWidth(name),
		runewidth.StringWidth(tail))

	// Truncate 会把 tail 的宽度从总预算中扣除，再在完整字形边界截断。
	short := runewidth.Truncate(name, columnWidth, tail)
	fmt.Printf("截断结果=%q，结果列宽=%d\n",
		short, runewidth.StringWidth(short))
}

这个示例的关键是把“20 列”作为显示预算传入，而不是传入 20 个字节。输入超宽时，库会先计算 tail 的宽度，再在剩余空间内保留原文；如果原文本来就在预算内，则会原样返回，不会无条件追加省略号。输出中的具体保留字符取决于每个字符的宽度，但结果列宽不会因为中文而按字节失控。

如果日志系统要求固定列宽，可以在截断后再调用 FillRight 或 FillLeft 补空格。截断和补齐是两个动作：前者解决内容过长，后者解决短内容在表格中的对齐。

按场景选择测量、截断和换行函数

值班排查时可以先按任务选择 API，而不是把所有文本都交给同一个切片函数：

如果程序运行在不同地区或需要模拟 CJK 终端，可以使用 Condition 保存一套独立宽度配置。默认包级变量适合简单场景；需要改变 EastAsianWidth 等选项时，使用 NewCondition 得到条件对象，并让同一列的测量、截断和填充都通过这个对象完成，避免前后采用不同规则。

// 用同一个Condition完成测量和截断，避免两次调用采用不同宽度规则。
condition := runewidth.NewCondition()
condition.EastAsianWidth = true

text := "版本±说明：中文与符号"
width := condition.StringWidth(text)
display := condition.Truncate(text, 18, "…")
fmt.Printf("宽度=%d，显示=%q\n", width, display)

示例只表达配置关系，实际项目中应在程序启动时确定条件，并在同一输出路径复用它。不要先用默认包函数测量，再用另一套东亚宽度开关截断；这样表格可能在判断阶段看似有空间，输出阶段却发生溢出。

处理省略号过宽与组合字形边界

第一个边界是尾标记本身。如果 tail 的显示宽度已经大于总宽度，调用方不能期待它凭空塞进一列；应在业务层先决定返回空串、缩短尾标记，还是提高列宽。建议把这个规则写进字段格式化函数，而不是让每个调用点自行猜测。

第二个边界是“一个 rune”不一定等于“一个完整字形”。当前库的实现会处理 grapheme cluster，因此不要自行按 rune 下标切割后再拼接来替代 Truncate。尤其是组合符号、连接符序列和部分 emoji，码点数量不能直接推导用户看到的字形数量。

第三个边界是固定宽度的含义。go-runewidth 提供的是终端单元格宽度估计，不能保证所有字体、终端模拟器和渲染环境的像素宽度完全一致。如果输出目标是 HTML、GUI 或 PDF，应改用对应渲染系统的测量方式，不要把终端列宽 API 当成通用排版引擎。

常见问题

为什么不用 len 直接截取？

len 统计字节，中文和 emoji 的 UTF-8 字节数与终端列宽不是同一个维度；直接按字节切还可能破坏 UTF-8。即使改成 rune 数量，也仍然没有处理中文双列宽、组合字形和尾标记预算。

Truncate 会自动补省略号吗？

不会。尾标记由第三个参数传入；原文不超宽时会原样返回，原文超宽时才会在剩余列宽内拼接该尾标记。

什么时候应该用 Wrap 而不是 Truncate？

一行必须保持固定高度时用 Truncate；允许内容占多行、希望尽量保留原文时用 Wrap。两者都应使用同一套宽度条件，避免测量规则不一致。

把终端文本放入固定列时，先问清楚“要保留多少显示单元格”，再决定截断、换行还是补齐。对中文混排字段，go-runewidth.Truncate 加上统一的 Condition，比手写字节或 rune 切片更容易把边界规则集中管理。