自家项目里存着一张海报模板，文案是后台配置的一段产品介绍，直接ctx.fillText画上去之后，超过画布宽度的文字被安静地裁掉，第一行最后一个字还露出半个头。这种问题在 Canvas 里太典型了：原生 API 只负责“画字”，不负责“排字”，所以自动换行这件事，本质上得自己实现一套“测量宽度 + 切行 + 逐行绘制”的小流程。这篇就把我的封装过程完整拆开讲，从基础算法到挂到原型上的自定义扩展方法，一步到位。
1. 先搞清楚 fillText 为什么不自动换行，换行到底难在哪
1.1 原生 Canvas 的文本 API 只做“画”这一件事
CanvasRenderingContext2D上最常见的文本方法是fillText(text, x, y)，它的语义很简单：从(x, y)这个坐标开始，把字符串沿基线画出来。注意这里有两个关键点。
第一，y是文本的基线位置，不是文字顶部。同样一行字，把textBaseline从top改成middle再改成alphabetic，画出来的视觉位置完全不同。我们做多行排布时，如果只在y上简单加行高，还要确认它和当前textBaseline的设置一致，否则行与行之间的距离会忽大忽小。
第二，fillText还有个容易被忽略的第四个参数maxWidth，但它的行为不是“超过宽度就换行”，而是“超过宽度就把整行文字水平压缩”。这个参数原名其实是用来限制文本显示宽度的，在遇到超长单词或者防溢出场景时能用，但它绝对不解决换行问题。这一点很多人第一次接触时会被误导。
所以结论很明确：Canvas 里没有div那种块级布局模型，没有“自动换行”“文本块”“行内元素”的概念。它就是一个画布，所有文字排版都得由开发者自己把坐标算明白。
1.2 换行的本质是“测量 + 判断 + 绘制”三段式流程
要在 Canvas 上实现任意文本的自动换行，绕不开一条流水线：
- 测量：用
ctx.measureText()量出当前这段文字的实际像素宽度。 - 判断：累加宽度，每加一个字符或词，就检查是否超过预设的
maxWidth。 - 绘制：把切成一行一行的字符串，逐行
fillText画出来，行间累加lineHeight。
听起来很简单，但实际做起来会碰到一堆细节问题：中英文混排怎么切？Emoji 会不会被劈成两半？文字里有换行符\n怎么处理？行数太多要不要省略号？字体没加载完的时候测量结果准不准？
这一系列问题叠加起来，就会让“为什么我画出来和量出来不一样”成为 Canvas 新手最常踩的坑。所以比较好的做法，不是每次用的时候现场临时拼逻辑，而是把这些规则沉淀成一个“自定义扩展方法”，以后在任何项目里都能直接调用。
1.3 为什么社区里很少有人直接给你一个标准答案
你可能会想，既然大家都需要换行，怎么浏览器不直接提供ctx.fillTextWrap？其实不是没人做，而是没法做一个通用的标准实现。
不同场景对“换行”的诉求差异很大：聊天界面可能需要按单词切，还要保留长 URL 不拆；海报生成器可能需要按字符切，让中文语义完整；图表标签可能只想截断成一行加省略号；导出服务还可能需要支持换行缩进。这些逻辑没法用一套配置全部覆盖，所以最好的方案不是“等一个官方 API”，而是自己封装一层，把可变的规则变成参数暴露出去。
2. 换行算法核心：先量宽度，再决定从哪断开
2.1 measureText 才是整个方案的主角
在 Canvas 中，任何换行判断都离不开ctx.measureText()。这个方法返回一个TextMetrics对象，里面最常用的属性是width，它表示当前字体状态下这段文本的渲染宽度，单位是 CSS 像素。
这里有个容易踩的点：measureText的结果和当前ctx.font、ctx.letterSpacing、ctx.fontKerning、ctx.direction都有关系。如果你先量了宽度，然后换了个字体再画，量出来的数据和画出来的东西就对不上。所以封装函数时要保证“测量用的上下文状态”和“绘制用的上下文状态”完全一致，最简单的方法就是测量和绘制都用同一个ctx。
另外，如果你需要精确的文本边界框，TextMetrics里还有actualBoundingBoxLeft/Right/Ascent/Descent，这些字段能算出文字相对基线的真实外框，适合做“文本到底占了多少空间”的判断。不过日常换行场景里，width已经足够了。
2.2 按字符切和按单词切，应该怎么选
不同语言的断行策略不一样。英文和大多数欧洲语言是“按空格分隔的单词为单位”断行，中文则是“按字符为单位”断行，因为中文词之间没有天然空格，一行里每个汉字都可能成为断点。
社区里常见的第一版实现是遍历字符串中的每一个字符，累加单个字符的宽度，超过maxWidth就换行。这个方案的优点是简单、通用、对中英文混排都有效，缺点是某个特别长的英文单词会被硬生生拆开，比如internationalization这种二十多个字母的单词。
更合理的策略是“英语按词切，中文按字切”，或者退一步“先尝试按词放进一行，词放不下了再退回按字符拆”。这样既保证了英文排版可读性，也不会在遇到超长 token 时死循环。
2.3 第一版可用代码：逐字符累加宽度
先不看那些花哨的优化，直接上一版最简单的逐字符换行封装：
function wrapTextByChar(ctx, text, maxWidth) { const lines = []; let line = ''; let lineWidth = 0; for (const ch of text) { const w = ctx.measureText(ch).width; if (line && lineWidth + w > maxWidth) { lines.push(line); line = ch; lineWidth = w; } else { line += ch; lineWidth += w; } } if (line) lines.push(line); return lines; }这段代码里有个容易被忽略的地方：换行时把当前字符作为下一行的开头，也就是说第一个字符不算进上一行。这样处理是为了避免某个单独的字符宽度超过maxWidth时导致死循环。理论上极限情况下单字符就会超宽，那这一行超了也只能硬画，否则永远切不完。
这个版本已经能解决大部分中英文混排问题，而且for...of迭代字符串可以正确处理 UTF-16 代理对，不会把一个 Emoji 直接拆成两个乱码字符。实际项目里如果只是偶尔画几段文案，这个函数已经够用。
2.4 优化：用二分查找减少 measureText 调用
逐字符循环有个性能隐患：一个字符调用一次measureText，画 500 字文案就要调用 500 次。measureText本身并不算便宜，尤其是字体复杂或绘制频率高时，这会造成明显的卡顿。
因为ctx.measureText(text)的宽度是随文本长度单调增长的，所以可以用二分查找，在[0, text.length]区间里定位“当前行最多能容纳多少个字符”：
function findMaxChars(ctx, text, maxWidth) { let low = 0; let high = text.length; while (low < high) { const mid = (low + high + 1) >> 1; if (ctx.measureText(text.slice(0, mid)).width <= maxWidth) { low = mid; } else { high = mid - 1; } } return low; } function wrapTextByBinary(ctx, text, maxWidth) { const lines = []; let rest = text; while (rest.length > 0) { const take = findMaxChars(ctx, rest, maxWidth); if (take === 0) break; lines.push(rest.slice(0, take)); rest = rest.slice(take); } return lines; }这个版本的测量次数从“字符总数”降到“每行约log2(行宽/字宽)次”，长文本收益非常明显。但要注意，二分查找用到的是text.slice()，如果切点恰好落在代理对中间，就会切断 Emoji。所以如果你明确知道自己要处理大量 Emoji，我建议在拿到切点后做一次“安全边界修正”，把切点向前移，直到不再落在代理对内部。实际项目中我一般会用逐字符遍历处理特殊文案，用二分查找处理纯文本长段，两种策略配合使用。
3. 完整封装 wrapText：段落、最大行数、省略号一次到位
3.1 设计一个能上线的 API，而不是一个一次性函数
开发习惯上，我倾向把“换行计算”和“Canvas 绘制”拆开。换行计算是一个纯函数，输入文本和宽度，输出每一行的字符串数组；绘制则是在拿到数组之后逐行fillText。这样拆的好处是方便测试，也方便后续在导出图片、服务端 Canvas、离屏 Canvas 上复用同一套逻辑。
所以我封装了这样一个工具函数：
function wrapText(ctx, text, maxWidth, options = {}) { const { maxLines = Infinity, ellipsis = '' } = options; const paragraphs = String(text).split('\n'); const result = []; for (const paragraph of paragraphs) { if (paragraph === '') { result.push(''); continue; } let line = ''; let lineWidth = 0; for (const ch of paragraph) { const w = ctx.measureText(ch).width; if (line && lineWidth + w > maxWidth) { result.push(line); line = ch; lineWidth = w; } else { line += ch; lineWidth += w; } } if (line) result.push(line); } if (maxLines !== Infinity && result.length > maxLines) { const visible = result.slice(0, maxLines); if (ellipsis) { visible[maxLines - 1] = truncateLine(ctx, visible[maxLines - 1], maxWidth, ellipsis); } return visible; } return result; } function truncateLine(ctx, line, maxWidth, ellipsis) { const ellipsisWidth = ctx.measureText(ellipsis).width; if (ctx.measureText(line).width <= maxWidth) { return line; } let end = line.length; while (end > 0) { const temp = line.slice(0, end) + ellipsis; if (ctx.measureText(temp).width <= maxWidth) { return temp; } end--; } return ellipsis; }这段代码里有几个需要考虑的点。
split('\n')处理了文案里自带换行符的情况。如果原始文本是多段落的，我们肯定希望保留作者手动的换行意图，而不是把所有段落重新拼成一行。空段落也保留，避免段落之间的空行丢失。
maxLines配合ellipsis解决“最多显示 N 行，超出部分用省略号”的典型需求。注意省略号不会平白增加，这里是在超过最大行数后才把最后一行截断。截断时用truncateLine不断收缩字符串，直到“原文截断部分 + 省略号”的总宽度不超过maxWidth。这个循环在真实长文本上可能比较慢，所以如果文本特别长，可以换用二分搜索优化，但一般海报文案长度撑死几百字，这里线性收缩即可。
3.2 标点悬挂：中文行首的逗号句号要不要处理
中文排版里，行首出现逗号、句号、问号会显得很业余。比如“你好，世界”这段文字，如果因为宽度问题在“，”处换行，下一行开头出现一个逗号，看起来就很难受。
我一般会在换行前做一个简单的规则判断：如果当前字符是中文行首禁则标点（如，。、；：？！）》】…），并且当前行已经有了内容，就把它“挤”到上一行末尾，然后再换行。虽然这会让上一行稍微超出maxWidth，但视觉上通常是可以接受的，而且在大部分 Canvas 文案场景里几乎是必须的。
const PUNCT_NO_START = new Set('，。、；：？！）》】…'); // 在换行判断时加一个条件： if (line && lineWidth + w > maxWidth && !PUNCT_NO_START.has(ch)) { result.push(line); line = ch; lineWidth = w; } else { line += ch; lineWidth += w; }这个规则要做全其实很复杂，比如省略号、破折号连排，不同语言标点规则还不一样。但作为第一版，处理最常见的“句尾标点不开头”已经能让效果提升一大截。
3.3 为什么我建议 return 一个数组，而不是只画完就算了
很多人封装函数时会直接写成“调用即绘制”，返回undefined。这样虽然方便，但后续想给文本算高度、想居中、想生成多页文字、想预判是否溢出，都得重新调用一次换行逻辑，非常浪费。
我习惯让纯函数返回string[]，绘制方法再拿这个数组去逐个fillText。这样高度计算、行数判断、点击区域判断都能复用同一份结果，逻辑也不会因为“绘制副作用”被搞得一团糟。
4. 把它变成自定义扩展方法：直接在 ctx 上调用
4.1 扩展原型还是写独立函数，我的选择标准
标题里提到“封装自定义扩展方法”，这里就得讨论一下到底要不要挂在CanvasRenderingContext2D.prototype上。
好处很直观：调用自然，ctx.wrapFillText(...)就像原生方法一样，别人读代码时能马上理解上下文。坏处也很明显：修改全局内置对象的原型，在严格模式或多人协作的大型项目里可能有冲突风险，尤其是你无法控制第三方库是否也做了类似扩展。
我的取舍标准是：如果这个项目只有一套 Canvas 绘制代码，且团队规范允许扩展原型，那就挂原型，代码最干净；如果项目是多 Canvas 封装、跨端运行、要发布 SDK，那就不要改原型，单独导出工具函数更稳妥。两个方案底层逻辑是一样的，所以我这里先讲清楚工具函数，再给原型扩展版本。
4.2 挂到原型上的参考实现
CanvasRenderingContext2D.prototype.wrapFillText = function (text, x, y, options = {}) { const { maxWidth = 200, maxLines = Infinity, lineHeight = 1.2, ellipsis = '', align = 'left', } = options; const fontSize = parseFloat(this.font) || 16; const leading = fontSize * lineHeight; const lines = wrapText(this, text, maxWidth, { maxLines, ellipsis }); const prevAlign = this.textAlign; this.textAlign = align; for (let i = 0; i < lines.length; i++) { this.fillText(lines[i], x, y + i * leading); } this.textAlign = prevAlign; return lines; };使用起来就很直观了：
ctx.font = '16px PingFang SC, Microsoft YaHei, sans-serif'; ctx.fillStyle = '#333'; ctx.wrapFillText('这是一段很长的文案，用来测试自动换行效果', 24, 40, { maxWidth: 180, lineHeight: 1.5, maxLines: 3, ellipsis: '…', align: 'left', });这里要解释两个容易踩的细节。
lineHeight的处理：我把lineHeight定义为相对于当前字体大小的倍数，然后计算出像素间距leading = fontSize * lineHeight。如果你的设计稿里行高是固定像素值，直接传lineHeight: 24，那在实现上就得区分“倍数”和“像素”，否则画出来会差很多。我这里的参考实现采用“倍数”的方式，更贴近 CSS 习惯。
textAlign的处理：对齐我暂时没有手动计算每行的偏移，而是直接临时修改this.textAlign，因为多行文本左对齐、右对齐、居中对齐时，textAlign本身就决定了x是文本的哪个锚点。画完再恢复原值，避免影响后续其他绘制逻辑。这个方案最简单，代价是你必须接受“同一段多行文本所有行都以同一个x为对齐锚点”，不过这正是align想要的语义。
4.3 返回值给到行数组，方便上层做更多判断
wrapFillText会把最终画出来的行数组返回，这意味着调用方还能继续做别的事：拿lines.length * leading算多行文字总高度，用于垂直居中；拿lines做点击区域的命中检测；拿行数和文本高度判断要不要给背景块加边框。
在我实际做海报编辑器时，这个返回值帮了大忙。文字下方要放一个渐变色块，背景块的高度必须跟着换行结果走，没有返回行数组，就得再调用一次 wrapText，还得保证两次传入的参数完全相同，否则行数一旦不一致，背景就穿帮了。
4.4 TypeScript 项目里如何给 CanvasRenderingContext2D 类型“打补丁”
团队里用 TypeScript 的话，直接在ctx.wrapFillText上调用会报类型错误。处理方式是在全局声明文件里扩展接口：
declare global { interface CanvasRenderingContext2D { wrapFillText( text: string, x: number, y: number, options?: { maxWidth?: number; maxLines?: number; lineHeight?: number; ellipsis?: string; align?: CanvasTextAlign; } ): string[]; } }这样在ctx上调用wrapFillText时就能拿到完整类型提示，团队协作时别人也不会因为找不到方法定义而困惑。
5. 实测避坑清单：这些坑不处理，线上必翻车
5.1 字体没加载完就测量，画出来一定错位
Canvas 的measureText用的是当前上下文的字体状态。如果你在页面里通过@font-face加载了自定义字体，但字体文件还没下载完，ctx.font设置的自定义字体名会先退回到默认字体，测量出来的宽度是 fallback 字体的宽度。等字体真正加载完再画，字形变宽变窄，换行结果就全乱了。
解决方法是绘制前等待字体加载完成：
async function render() { await document.fonts.ready; // 此时再调用 wrapFillText drawCanvas(); }如果业务上有“首屏进入必须立刻展示海报”的强需求，可以结合document.fonts.load('16px YourFont')更精确地等待特定字体，而不是等全部字体。实测下来，字体加载问题是最隐蔽的痛点，因为它只在特定字体、特定系统下出现，本地开发时字体往往是系统字体，根本复现不出来。
5.2 Emoji 被拦腰截断和“看起来没问题”的假象
逐字符用for...of遍历字符串时，Emoji 会被当做一个完整的码点处理，至少不会被劈成两半。但如果你用了二分查找版本，text.slice(0, take)的take是按 UTF-16 代码单元计算的，遇到占两个代码单元的 Emoji，切片位置就可能落在代理对中间，产生一个半截乱码字符。
规避方法有两种：第一种是在二分切点确定后，检查切点是否落在代理对中间，是则向前修正到安全位置；第二种是干脆把二分查找换成逐字符遍历，并用Array.from(text)先把字符串转成码点数组。复杂 Emoji 还有组合序列的问题，比如家庭成员这种由多个 Emoji 用零宽连接符拼起来的序列，逐字遍历也会拆散。如果文本里这类内容很多，建议用Intl.Segmenter做字素分割，这是目前比较标准的解决方案。
const segmenter = new Intl.Segmenter('zh', { granularity: 'grapheme' });不过要诚实说一句，Canvas 测量宽度的时候，对复杂 Emoji 序列的宽度支持和 DOM 并不完全一致，实测中我也只能做到“不断裂、不乱码”，像素级完美对齐仍然需要依赖具体字体和运行环境的实测。
5.3 devicePixelRatio 和高分屏模糊
很多项目会做 Canvas 高分屏适配，把canvas.width设为cssWidth * devicePixelRatio，再通过ctx.scale(dpr, dpr)绘制。这种情况下，measureText返回的是当前变换后的逻辑像素宽度，还是基于物理像素？这取决于你的缩放时机。
如果你先setTransform(dpr, 0, 0, dpr, 0, 0)，那么后续fillText和measureText都是在 CSS 像素坐标系里工作，测量和绘制是一致的。如果你忘了setTransform，直接用物理像素绘制文字，那不仅测量结果要乘比例，文字还会因为放大而发虚。最稳妥的写法是在初始化 Canvas 后固定执行一次：
ctx.setTransform(dpr, 0, 0, dpr, 0, 0);这样整个绘制流程都用 CSS 像素坐标，换行的maxWidth也不用管 DPR，代码清爽很多。
5.4 性能：重复测量和频繁重绘时的缓存策略
画布动画里如果每帧都重新计算一段长文本的换行，measureText的调用次数会直接拖垮帧率。我的做法是加一层简单缓存，以“文本 + 最大宽度 + 字体状态”作为 key，缓存换行结果：
const wrapCache = new Map(); function wrapTextCached(ctx, text, maxWidth, options = {}) { const key = `${text}|${maxWidth}|${ctx.font}|${options.maxLines}|${options.ellipsis}`; if (wrapCache.has(key)) return wrapCache.get(key); const result = wrapText(ctx, text, maxWidth, options); wrapCache.set(key, result); return result; }注意 key 里一定要包含ctx.font，因为同一个ctx上字体一变，测量结果也就变了。缓存也不用做得多复杂，Map 默认就够用，如果担心内存占用，限制一下条数或只在静态文案场景里使用即可。
5.5 换行结果受 textBaseline 影响，别只调行高
前面提过lineHeight是按字体大小计算的，但最终绘制时还要结合textBaseline。如果ctx.textBaseline是默认的alphabetic，那么第一行的基线位置是y，第二行的基线应该是y + leading，这个逻辑没毛病。但如果textBaseline是top，文字是从y往下画，多行叠加时行距计算还得考虑上一行文字的实际高度，否则行与行之间会重叠得很厉害。
简化方案是：多行文本框绘制前统一把textBaseline设成top或middle，然后手动按行高递增；绘制完再恢复。这样至少你不会在切换文字基准模式时突然发现行距不对。
6. 从“能换行”到“排得漂亮”：文本排版还能继续扩展什么
6.1 首行缩进、悬挂标点和两端对齐
上面的封装解决了“换行”这个基本问题，但实际做富文本排版时，你可能还需要补三类规则。
首行缩进：中文正文段落喜欢开头空两格，这个可以在第一行前面拼两个全角空格，或者通过额外参数firstLineIndent在绘制第一行时传入x + indent。
悬挂标点：行首不允许出现某些标点，行尾尽量不让标点单独成行。这需要维护一个更大的“禁则表”，并在换行的时候把标点归到上一行。规则复杂时，建议单独抽一个lineBreakRules.js，而不是塞在 wrapText 里。
两端对齐：Canvas 默认左对齐，行尾参差不齐。要做出类似 Word 的两端对齐效果，需要对每一行计算“还差多少宽度”，然后把这些差值平均分配到行内每个字符的间距上。这个逻辑并不复杂，但实测中碰到标点、空格和混合字体时要非常小心，否则间距会忽大忽小。
6.2 富文本：一行里多种颜色、字号、字体怎么画
自动换行只是文本排版的第一步。实际项目中经常出现“标题文案里某几个字要高亮”，或“价格数字要用大字号”这种需求。这时候不能每次整行fillText，因为一行里不同字符有不同样式。
我的做法是先把文本拆成若干个“样式片段”，每个片段记录text、font、color。换行计算时，以片段为单位测量宽度并判断是否跨越行边界；绘制时按片段逐个fillText。这样一行可能被拆成三四次绘制，但视觉上是连续完整的。这个模式做起来比单行样式复杂，但它是 Canvas 富文本落地的必经之路，后续我可能会单独写一篇展开讲。
6.3 多文案回归测试，比任何参数都重要
最后分享一个我踩过好几次坑之后的经验：Canvas 换行逻辑改一版，就一定要做回归测试。因为换行结果依赖字体、宽度、标点规则、Emoji 处理，任何一个环节变了都会让输出完全不一样。
我在项目里维护了一份固定文案清单，包含超长英文单词、中英文混排、emoji 组合、换行符段落、超长数字这几种典型场景。每次改完 wrapText，我就会在离屏 Canvas 上一一渲染，导出一张测试图，用截图对比的方式确认没有出现明显回归。这个方法虽然老土，但对比手工肉眼检查高效得多。
封装自定义扩展方法这件事，本质上就是把你对业务的理解沉淀成可复用的代码。换行规则没有放之四海而皆准的标准答案，但上面这套“测量—切行—绘制—扩展原型”的流程，已经能覆盖绝大多数 Canvas 文案场景。哪天你遇到更刁钻的排版需求，至少知道该从哪一层去改，而不是从头硬写。
