Go go-runewidth 的组合字符宽度怎样计入字符串

在 Go 中显示带重音符号的文字时，len 统计的是 UTF-8 字节数，utf8.RuneCountInString 统计的是 Unicode 码点数，而终端对齐真正关心的是占用了多少个显示单元格。github.com/mattn/go-runewidth 的答案是：组合字符通常按 0 个 cell 计入，基字符保留自己的宽度，整段文本再由 StringWidth 汇总。

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

因此，e 和后面的组合重音符号组成一个用户看到的字符时，组合符号不会把宽度从 1 推成 2。这个规则解决的是终端列宽，不等同于“字符串只有一个 rune”，也不等同于中文搜索分词。

组合字符为什么通常不增加列宽

Unicode 文本可能把一个带音标的字符写成“基字符 + 组合标记”。两部分在 UTF-8 中会占用多个字节，在 Go 的 range 中也会得到多个 rune，但组合标记的显示职责是附着在前一个字符上，所以 go-runewidth 的字符宽度表会把它视为零宽。

这里的“宽度”是终端 cell，不是像素，也不是字节。普通拉丁基字符通常占 1 个 cell，许多中日韩字符占 2 个 cell，而组合标记本身通常占 0 个 cell。多码点 emoji、旗帜和 ZWJ 序列还会按 grapheme cluster 处理，不能用逐 rune 相加的直觉替代库的实现。

先用 RuneWidth 观察单个码点

排查某个字符导致表格错位时，先看 RuneWidth 和 IsCombiningWidth。前者返回该 rune 的终端 cell 宽度，后者只回答它是否属于组合宽度集合。它们适合诊断单个码点，不适合代替整段字符串的 grapheme 处理。

package main

import (
	"fmt"

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

func inspectRunes(s string) {
	// range 按 Unicode rune 遍历，便于观察基字符和组合标记的差异。
	for _, r := range s {
		fmt.Printf("%U width=%d combining=%v\n",
			r,
			runewidth.RuneWidth(r),
			runewidth.IsCombiningWidth(r),
		)
	}
}

func main() {
	// 使用转义写出“e + 组合重音符号”，避免编辑器替换成预组字符。
	inspectRunes("e\u0301")
}

这个观察可以帮助定位问题：组合标记一般会报告 0 宽，但它仍然是一个独立的 rune。不要因为宽度为 0 就把它从字符串中删除，否则会改变用户看到的字符。

StringWidth 如何把组合字符算进整段字符串

真正要给表格列、状态栏或截断逻辑设定宽度时，直接调用 StringWidth。当前版本在遇到可能组成多 rune cluster 的文本时，会按 grapheme cluster 计算；组合标记的宽度仍然为 0，基字符的 cell 宽度仍然保留。

package main

import (
	"fmt"
	"unicode/utf8"

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

func reportWidths(s string) {
	// 三个指标回答不同问题，不能互相替代。
	fmt.Println("bytes:", len(s))
	fmt.Println("runes:", utf8.RuneCountInString(s))
	fmt.Println("cells:", runewidth.StringWidth(s))
}

func main() {
	// 组合形式含两个 rune，但显示宽度应接近一个拉丁字符。
	reportWidths("e\u0301")
}

判断结果时记住三层含义：字节数用于存储和切片边界，rune 数用于 Unicode 码点遍历，cell 宽度用于终端布局。如果业务是按用户感知字符截断，还要配合库的 Truncate 或其他 grapheme 级策略，不能在任意字节位置切开。

整段字符串和终端环境怎样一起处理

默认函数使用 DefaultCondition。如果程序需要显式控制 CJK 环境下的 East Asian Width，可以创建自己的 Condition，再用它调用字符宽度、字符串宽度和填充方法。修改条件字段后，如果要预建查找表，应按官方说明调用 CreateLUT，并且不要与同一个条件对象的其他操作并发执行。

package main

import (
	"fmt"

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

func printRow(label, value string, width int) {
	// FillRight 按 cell 宽度补空格，不按字节长度补齐。
	fmt.Println(runewidth.FillRight(label, width), value)
}

func main() {
	condition := runewidth.NewCondition()
	// CJK 终端可按需要启用东亚宽度策略，再复用同一个条件对象。
	condition.EastAsianWidth = true
	condition.CreateLUT()

	text := "e\u0301"
	fmt.Println("cells:", condition.StringWidth(text))
	printRow("名称", text, 8)
}

EastAsianWidth 影响的是具有东亚宽度歧义的字符，不会把一个普通组合标记突然变成可见列。实际部署时还要考虑终端字体和渲染器差异：库给出的是 Unicode 与终端 cell 规则下的稳定估计，不是像素测量。

四个容易混淆的边界

1. 组合字符不是空字符：它的 cell 宽度通常为 0，但仍然参与 Unicode 文本的显示和规范化语义。
2. RuneWidth 不是整串答案：逐 rune 相加可能忽略 grapheme cluster、emoji 或 ZWJ 的显示关系，整串应优先用 StringWidth。
3. len 不能用来补表格：UTF-8 字节数与终端列数没有一一对应关系，填充时使用 FillLeft 或 FillRight。
4. 预组字符与组合形式都要考虑：用户输入可能来自不同 Unicode 表示，代码不要假定每个“看起来的字符”只有一个 rune。

一句话总结：组合字符通常以 0 cell 计入，基字符负责可见宽度；诊断单个码点用 RuneWidth 和 IsCombiningWidth，计算整段终端宽度用 StringWidth，表格补齐用基于 cell 的填充函数。

相关问题

组合字符宽度为 0，能不能直接删除？

不能。0 宽只表示它不额外占终端列，删除会丢失重音、变音或其他附着语义。需要清理文本时，应使用明确的规范化或业务规则。

为什么 rune 数和终端宽度不一样？

因为一个用户感知字符可能由多个 rune 组成，且不同 rune 的终端宽度可能是 0、1 或 2。rune 数描述码点数量，StringWidth 描述 cell 数量。

资料来源：https://pkg.go.dev/github.com/mattn/go-runewidth；https://github.com/mattn/go-runewidth/blob/v0.0.31/runewidth.go