• CLI
• 开发工具

本文围绕 fish-shell 内置命令string pad展开，讲解如何通过-w/--width、-r/--right、-C/--center、-c/--char等参数将字符串填充（pad）到指定终端列宽，实现左对齐、右对齐与居中对齐的格式化输出。读完本文，你将掌握string pad的完整参数语义、可见宽度（visible width）的计算原理（含 ANSI 转义序列剔除与fish_emoji_width/fish_ambiguous_width的作用），并能用它在提示符、表格、状态栏等场景中稳定对齐中文、Emoji 与彩色文本。string pad的完整命令说明位于 doc_src/cmds/string-pad.rst，其实现位于 src/builtins/string/pad.rs。

一、命令概览与 Synopsis

string pad是 fish 内置string命令的一个子命令，用于把每个输入字符串扩展到指定的"可见宽度"，缺省在左侧填充空格。官方语法如下：

string pad [-r | --right] [-C | --center] [(-c | --char) CHAR] [(-w | --width) INTEGER] [STRING ...]

在源码中，该子命令被注册在 src/builtins/string.rs#L318（"pad" => pad::Pad::default().run(...)），是一个独立的模块 src/builtins/string/pad.rs。参数解析由该模块的LONG_OPTIONS与SHORT_OPTIONS定义（见 src/builtins/string/pad.rs#L26-L35）：

值得注意的是，--chars是--char的历史别名（源码中同时注册了wopt(L!("char"), ...)与wopt(L!("chars"), ...)），两者等价，用于兼容旧版本 fish 的拼写。

二、核心语义：什么是"可见宽度"

文档强调，string pad填充的目标是"可见宽度"（visible width），即所有可见字符宽度之和——剔除转义序列（escape sequences），并计入fish_emoji_width与fish_ambiguous_width的影响。简言之，它就是该字符串在终端中实际占用的列数。

这意味着：

• 字符串中的 ANSI 颜色/样式转义序列（如\e[31m）不会被算作宽度；
• 双宽字符（CJK、Emoji）按其真实渲染宽度计算；
• 终端支持的转义序列可能与 fish 认知的不一致：fish 只识别它自己知道的那部分转义序列，你的终端可能支持更多，也可能不支持 fish 认识的那些。

该逻辑在 src/builtins/string.rs#L239-L268 的width_without_escapes()中实现：先逐字符用fish_wcwidth_visible()累加宽度，再扫描\x1B（ESC）开头的转义序列，把其中包含的可打印字符宽度从总和中减去。string pad在 src/builtins/string/pad.rs#L81 调用此函数计算每个输入的实际宽度。

两个宽度环境变量的作用

可见宽度的计算还受到两个全局变量影响（定义见 doc_src/language.rst#L1574-L1580）：

• fish_emoji_width：控制 fish 假定 Emoji 渲染为 2 列还是 1 列宽。Unicode 9 中 Emoji 宽度由 1 变为 2，而部分终端仍按旧标准渲染。默认值为 2；若看到 Emoji 相关的图形错位，可设为 1。
• fish_ambiguous_width：控制"宽度不明确"字符的计算宽度。若你的终端将这些字符渲染为单宽（常见情况）则设为 1，若渲染为双宽则设为 2。

在 tests/checks/string.fish#L104-L110 的测试中可以看到它们的实际作用——测试先把fish_emoji_width设为 2，于是string pad -w 4 -c . 🐟输出..🐟（Emoji 占 2 列，还需补 2 个点），而-C居中时输出.🐟.。

三、参数详解与行为规则

综合官方文档与 pad.rs 的parse_opt/handle实现，各参数的行为如下。

1. 填充方向：-r/--right与-C/--center

• 缺省（不加任何方向参数）：填充加到字符串左侧，即左对齐输出，如string pad -w 10 abc得到abc；
• -r/--right：填充加到字符串右侧，即右对齐输出；
• -C/--center：左右两侧都填充。若总填充量是奇数无法完美居中，多余的 1 列加到左侧，除非同时给出--right（此时多余列加到右侧）。

在 src/builtins/string/pad.rs#L90-L96 中，四个方向的分配逻辑为：

测试 tests/checks/string.fish#L88-L102 直观验证了这一点：宽度 8 居中foo时奇数余量在左（===foo==），加-r后余量在右（==foo===）；宽度 10 时居中输出| foo |（5 左 4 右），--right --center输出| foo |（4 左 5 右）。

2. 填充字符：-c/--char CHAR

缺省用空格填充；-c/--char可指定任意单个字符（Emoji 等宽字符亦可）。源码对其做了两条校验（见 src/builtins/string/pad.rs#L37-L55）：

• 必须是单个字符，多字符报错：string pad: Padding should be a character 'ab'（对应测试 tests/checks/string.fish#L162-L163）；
• 填充字符的可见宽度不能为 0（不可打印字符没有填充意义），否则报错：string pad: Invalid padding character of width zero（测试见 tests/checks/string.fish#L166-L169，\x07与零宽字符\u200b均被拒绝）。

若填充字符本身是双宽字符（如 🐟），而所需填充量为奇数时，fish 会用空格补足余下的 1 列——源码 src/builtins/string/pad.rs#L98-L105 中chars(w)重复填充字符、spaces(w)用空格兜底，测试 tests/checks/string.fish#L117-L121 注释也说明："fish 宁愿结果真正居中，而不是硬塞半个 🐟"。例如string pad -w 3 -c 🐟 -C .输出| . |而不是|🐟.|。

3. 目标宽度：-w/--width INTEGER

• 缺省时，输出宽度为所有输入字符串可见宽度的最大值（"Pad to the maximum length"，见 tests/checks/string.fish#L134-L158 的long/longer/longest系列测试）；
• 显式给出-w/--width时，使用max(最大输入宽度, 指定宽度)——即输入中最长的字符串会"撑破"指定的宽度参数，比-w更长的输入不会被截断，只会原样输出（源码 src/builtins/string/pad.rs#L87 的pad_width = max_width.max(self.width)，测试 tests/checks/string.fish#L150-L158 用longer-than-width-param验证了这一行为）；
• 宽度为负数时报错：string pad: Invalid width value '-1'（tests/checks/string.fish#L171-L172）。

四、实战示例

以下是官方文档 doc_src/cmds/string-pad.rst#L38-L53 中的示例及展开：

1. 左对齐到固定宽度 10：

>_ string pad -w 10 abc abcdef abc abcdef

2. 右对齐并用 Emoji 填充：

>_ string pad --right --char=🐟 "fish are pretty" "rich. " fish are pretty rich. 🐟🐟🐟🐟

第一条字符串本身就达到目标宽度，故不加填充；第二条在右侧补足 4 列宽度（以fish_emoji_width=2计，即两个 🐟……实际输出随环境变量而不同）。

3. 把当前时间顶到屏幕右缘：

>_ string pad -w$COLUMNS (date) # 将当前时间打印在屏幕右边缘。

$COLUMNS是 fish 提供的终端列数变量，配合-w即可让内容靠右对齐到屏幕边缘。这是状态栏、欢迎信息、提示符右上角时间的常见写法。

4. 居中对齐与混合参数：

>_ string pad -w 10 -c '=' -C foo ===foo====

（宽度 10、填充=、居中：左边 3 个、右边 4 个。）

五、与其他命令的协作

string pad常与同族命令搭配使用：

• string length --visible：--visible模式返回的正是 fish 计算出的可见宽度（实现同样调用width_without_escapes，见 src/builtins/string/length.rs#L48），可用来核对string pad的目标宽度是否符合预期；
• string shorten：与pad互补，用于按可见宽度截断超长文本并追加省略号（同样受fish_emoji_width/fish_ambiguous_width影响，见 src/builtins/string/shorten.rs）；
• printf：可以做简单填充，如printf %10s\n等价于string pad -w10（官方文档 See Also 明确指出）。当需要复杂的方向控制、宽字符感知或 Emoji 填充时，string pad是更可靠的选择。

六、最佳实践小结

• 对齐中文、日文、Emoji 或含 ANSI 颜色的文本时，优先使用string pad而非printf的%Ns格式，因为它按真实终端列宽计算而非按字符个数；
• 若输出出现错位，先检查fish_emoji_width（终端按 Unicode 8 渲染时设为 1）与fish_ambiguous_width（终端单宽设为 1、双宽设为 2）；
• 记住-w是"至少"宽度：超长输入会原样输出，不会截断，如需截断请组合string shorten或string length --visible自行裁剪；
• 填充字符只接受单个可见字符，双宽字符配合奇数宽度时多余列会以空格代替，属预期行为而非 bug；
• 在提示符函数中做右缘对齐（如时间、git 状态）时，string pad -w$COLUMNS ...是最简洁的写法，但注意提示符重绘时$COLUMNS的变化。

• CLI
• 开发工具