| Files | Last commit | Last update |
|---|---|---|
| 26 days ago | ||
| 26 days ago | ||
| 26 days ago | ||
| 26 days ago |
Markdown 表格生成器:粘贴 Excel 出对齐表,中文占 2 格实测
从 Excel 复制一张 5 行 5 列的中文表格粘进来,页面立刻吐出三种 Markdown 源码。
按显示宽度补齐的那份是 402 个字符、153 个空格,比完全不补齐多出 93 个空格。
按「字符个数」补齐的那份只有 317 个字符、93 个空格,看着更省,粘到编辑器里竖线却是歪的。
差别只在一点:等宽字体下汉字占 2 格,字母占 1 格。

在线案例与源码:https://atomgit.com/deli007/demo_park/tree/main/codearts-markdown-table-generator 页面是 3.3 万字符的单文件,宽度函数、三种补齐口径、折行和 32 条自检都在里面,不发任何网络请求。
一、为什么值得看:表格歪不歪,只取决于你用哪套宽度口径
写 Markdown 表格时,源码里想对齐,靠的是每列都补齐到同一个宽度。
难点在于宽度不是字符个数。等宽字体下「汉」占 2 格,「A」占 1 格,两者都算一个字符。
很多生成器图省事,按字符个数补齐,把汉字当 1 格,于是列里的空格数对了、显示宽度不对。
我把三套口径放进同一个页面并排跑,谁歪、歪多少,同屏就能看出来。
我拿销售表、成员表、接口清单三张表各粘了一遍,三种模式的总字符数和空格数都留在统计面板上。
二、准备环境:进入码道 Web,把 13 条需求一次说清
浏览器打开码道 Web 版:https://devcloud.cn-north-4.huaweicloud.com/chat?source=dmzntgwsf&sourcead=dmzntgwwbwz ,登录后就能在对话窗口输入需求,不需要装软件。
码道有三种使用方式:WebUI(浏览器对话)、TUI(终端命令行)和桌面 IDE(IDE 插件)。本文用 WebUI 版演示。
这一轮我把需求拆成 13 条,一次性贴进对话:
- 左侧是输入框,粘贴从 Excel 里复制的内容(单元格之间是 Tab,也兼容逗号、分号、竖线分隔),右侧实时生成 Markdown 表格源码并显示。
- 显示宽度函数按等宽字体口径:半角字符(ASCII 字母数字、半角标点)算 1 格;汉字、全角标点、日文假名算 2 格;emoji 与代理对字符算 2 格;零宽空格(U+200B)等零宽字符算 0 格。
- 支持三种对齐方式:左对齐(分隔行 ---)、居中(:---:)、右对齐(---:),分隔行每列至少 3 个短横线。
- 对齐时按列补齐半角空格到该列最大显示宽度;右对齐补齐在左边,居中两侧平分、奇数时右侧多一个空格。
- 三种模式同屏并排对比,每张表都显示它算出来的总字符数:模式 A 不补齐(直接原样输出)、模式 B 按字符个数补齐(把汉字当 1 格算,会歪)、模式 C 按显示宽度补齐(正确)。
- 单元格里的竖线自动转义成 |,单元格内的换行替换成
,前后空白裁剪,空单元格保留占位。 - 每列最大显示宽度可设置(默认 20),超出的单元格按显示宽度折行,用
拼接,并显示折成了几个物理行。 - 统计面板显示:行数、列数、最大列宽(显示宽度)、含汉字的单元格数、补齐后的总字符数、比不补齐多出的空格数、模式 B 与模式 C 的空格数差。
- 宽度自检面板:对一组固定字符逐个打印判定宽度与期望宽度(中文「汉」、字母 A、数字 5、全角逗号、半角逗号、emoji、零宽空格等),全部一致才显示绿色通过。
- 页面底部至少 20 条自检,期望值必须由页面现算,不能写死:宽度函数各档边界、分隔行最少 3 个短横线、转义后列数不变、折行的物理行数、每列补齐空格总数与公式「最大列宽减本格宽度」之和一致、空输入时的提示、行尾不留多余空格。
- 参数非法时给中文提示并保留上一次的有效值:列宽上限填 0 或非数字、一行里列数超过 12 列。
- 三个示例数据按钮:销售表、成员表、中英混排的接口清单,点了直接填入输入框。
- 一键复制生成的 Markdown 源码,复制后按钮文案变成「已复制」。
第十条和第十一条是这一轮最值钱的两句。
自检的期望值必须由页面现算,页面就没法用「我算出来是对的」糊弄过去。
参数非法要给中文提示并保留上一次的有效值,边界行为就能直接抓原文,不用我再去猜。
三、三种补齐口径差在哪,一张表看完
| 模式 | 列宽怎么定 | 销售表 5×5 | 成员表 6×4 | 接口表 6×4 |
|---|---|---|---|---|
| A 不补齐 | 原样输出,分隔行固定 3 个短横线 | 268 字符 / 60 空格 | 192 / 58 | 360 / 57 |
| B 按字符个数 | 汉字记 1 格 | 317 / 93 | 265 / 119 | 430 / 102 |
| C 按显示宽度 | 汉字记 2 格 | 402 / 153 | 259 / 106 | 446 / 105 |
汉字越多的表,B 和 C 的差距越大。
销售表的备注列全是汉字,C 比 B 多补 60 个空格;接口清单里英文路径多,两者只差 3 个。
成员表是唯一反过来的一张:B 补 61 个空格,C 只补 48 个。
我把逐列的补齐数拉出来对了一遍,原因在列宽的定义上。
成员表四列,B 的列宽是 [6, 6, 8, 4],C 是 [6, 10, 8, 7],补齐数 B 为 [15, 10, 27, 9],C 为 [5, 11, 19, 13]。
角色列和状态列里汉字密集,两套口径把列宽定得差 4 格和 3 格,补齐的方向就翻转了。
所以模式 B 的偏差方向会随数据变,不总是「少补」,这一点发布前得拿自己的表跑一遍。

四、验证与踩坑:三张表怎么量,页面自检怎么算
页面上有三个示例按钮,销售表、成员表和中英混排接口清单,点一下直接填进输入框。
统计面板给 8 个数:行数、列数、最大列宽、含汉字的单元格数、模式 C 的总字符数、C 比 A 多出的空格数、C 与 B 的空格数差、折行格数与物理行数。
接口清单那张表里最长的一列是说明列,列宽上限 20,6 个格子被折行,折成 13 个物理行。
格子里的竖线自动转义成 |,格子内部的换行换成
,折行标记也是这个标签。

交付后我点了自检面板,页面直接抛错:TypeError: Cannot read properties of undefined (reading 'replace')。
抛出点在 parseGenRow,调用点在 runSelfChecks。
最小复现是需求第十条里的单行用例:输入 abcde 加一个 Tab 再加 ab,生成出来的表只有表头行和分隔行两行。
代码却去取第二行之后的第三个位置,split 出来是 undefined,再去调用 replace 就炸了。
我把抛出点、调用点、最小复现一起贴回对话,让码道把取值改成按行防御,并给每条自检单独加 try/catch,一条挂掉不影响其他条目。
顺手改了第二处:模式 A 的分隔行原来跟着列宽一起补齐,现在固定用 3 个短横线。这直接影响「比不补齐多出的空格数」这个统计口径,改完那条自检才算得平。
重跑之后运行自检 32/32 全绿,宽度自检 31 项也全绿。

参数不合法时页面不崩,给中文提示并保留上一次的有效值。
列宽上限填 0,提示原文是「列宽上限需为不小于 1 的整数,当前输入 0,已恢复为上一次的有效值 20。」,输入框同时被改回 20。
填 abc 是同一句话,只是把当前输入换成了 abc。
一行里超过 12 列,提示换成「第 1 行解析出 14 列,超过 12 列上限。已保留上一次的有效结果,请检查数据或分隔符设置。」

五、本地复现:一行命令把宽度函数对拍一遍
源码在开放仓库里,clone 下来双击 index.html 就能用,不需要装依赖。
仓库里带了一个独立复算脚本,用 Python 的 unicodedata 自己重写一份宽度判据,再把页面里的宽度函数抽出来交给 node 跑一遍,两边逐字符比。
git clone https://atomgit.com/deli007/demo_park.git
cd demo_park/codearts-markdown-table-generator
python -X utf8 verify_table.py
我本地跑出来 43/43 通过:宽度判据 14 个单字符加 1 个组合串全部一致,组合串 a汉b😀 是 6 格。
三个示例表在 5 种模式下的源码逐字符一致,一共 15 条,包含居中、右对齐两种变体。
想直接在浏览器里看,起个静态服务也行:python -X utf8 -m http.server 8000。
六、边界
宽度口径只对等宽字体有效。汉字 2 格的前提是渲染字体里汉字宽度正好是两个半角字符,换成比例字体,源码里的空格就白补了。
模式 B 的偏差方向会翻转,成员表里它比 C 补得更多,别只看一张表的结论。
一行最多 12 列,超了直接拒绝,不会硬算出一个错的结果。
折行用
标记,源码的物理长度会变长,宽度口径不计
这 4 个字符本身。
页面自检是页面内部自己现算的,不是第三方评测,只能证明这套宽度函数自洽。
七、使用码道体会
- 需求里写「期望值必须由页面现算,不能写死」,自检才有意义;写死常量的自检等于没写。
- 交付后控制台报错要去点一遍,别只看界面能不能画出来;这轮的自检抛错就是点出来的。
- 回修时把抛出点、调用点、最小复现一起贴回对话,比说「自检有问题」有效得多,一次就改到位。
- 边界行为要写进需求,非法参数的中文提示和回退值才能直接抓原文当证据。
- 一次把需求列成编号清单,页面的分区结构基本就跟着清单走了,验收时能一条条对。
- 统计口径要和算法改动一起验收;模式 A 改了分隔行的补齐规则,统计面板的数字跟着变,这条是连带发现的。
八、直接下载试玩
源码和在线案例在 https://atomgit.com/deli007/demo_park/tree/main/codearts-markdown-table-generator 。
亲手点三下,数字都能自己对上:
- 看尺子:点「示例:销售表」,统计面板应是 5 行、5 列、含汉字 13 个格子、模式 C 共 402 字符。
- 换输入:点「示例:中英混排接口清单」,最大列宽仍是 20,折行格数变成 6 格 / 13 物理行。
- 看失败路径:把列宽上限改成 0,必须看到「已恢复为上一次的有效值 20」的提示,输入框回到 20。
九、总结
Markdown 表格对不齐,问题不在手抖,在宽度口径没统一。
汉字按 2 格算,英文按 1 格算,补出来的源码才在等宽字体里对齐。
按字符个数补齐的那套在汉字表上补得更多、在混排表上补得更少,方向随数据翻转,所以别只信一种模式的输出。
页面上三种模式同屏,改个数字就能重跑一遍,我把自己量到的空格数都留在统计面板上了。