如何在HTML Canvas中使用fillText绘制文字

很多开发者第一次用Canvas的fillText()方法时，都会遇到一个共同的困惑：明明代码逻辑看起来没问题，为什么画布上就是一片空白？这往往不是语法错误，而是对绘制机制的理解出现了偏差。

简单来说，fillText()并不是一个“傻瓜式”的绘图命令。它背后依赖着一套完整的绘图状态机，其中字体、颜色和坐标基准这三项设置，缺一不可。任何一项没到位，文字就“隐身”了。

绘制生效的前提：font与fillStyle必须显式设置

Canvas的渲染上下文是一个独立的状态环境，它不会自动继承页面的CSS样式。这意味着，你必须手动告诉它用什么字体、什么颜色来画。

最常见的疏忽就是只写了绘制命令，却忘了设置样式：

• font属性必须完整：它需要同时包含字号和字体族，比如"16px Arial"。只写一个"Arial"是无效的。对于中文，强烈建议声明后备字体，例如"14px 'PingFang SC', 'Microsoft YaHei', sans-serif"，以防用户系统缺少首选字体导致显示为方块。
• fillStyle不能是透明或非法值：虽然它的默认值是黑色（"#000000"），但如果上下文中之前被设置过透明色（如rgba(0,0,0,0)）或一个非法的颜色字符串，文字同样不会显示。这是一个容易被忽略的“历史状态”问题。

理解坐标y：它指的是基线，不是顶边

fillText("Text", x, y)中的y参数，指的是文字基线的垂直位置，而不是文字矩形的顶部。这个设计源于西文字母的排版传统，但常常让初学者感到困惑。

这会导致什么现象呢？用同一个y值绘制字母“A”和“g”，它们的视觉顶部根本不在一条线上。如果你想实现“顶部对齐”，需要将textBaseline属性设置为"top"。同理，要实现水平居中，除了将x坐标设为画布宽度的一半，还需要设置textAlign = "center"。

对于需要精确控制布局的场景，现代浏览器提供了ctx.measureText()方法，其返回的actualBoundingBoxAscent等属性可以帮你计算出文字的实际尺寸。

关于maxWidth参数：浏览器兼容性与局限性

fillText()方法支持一个可选的maxWidth参数，用于限制文本的最大宽度。但这里有两个坑：

• Safari直接忽略：在Safari浏览器中，这个参数是无效的，文字不会因此被压缩或换行。
• 压缩效果生硬：即使在支持的浏览器中，其压缩逻辑也是等比例缩放整个文本块，并非智能调整字体大小或自动换行，视觉效果往往不尽如人意。

因此，如果确实需要实现宽度限制，更可靠的做法是使用measureText()进行测量，然后手动进行文本截断或分段绘制。对于复杂的文本布局，有时结合CSS和DOM覆盖可能是更优的方案。

字体加载：一个关键的时机问题

当你使用Web Font（网络字体）时，必须注意绘制的时机。Canvas不会等待字体文件加载完成。如果在@font-face定义的字体尚未加载时就调用fillText()，Canvas会使用默认或后备字体进行渲染，结果可能就是乱码或字体回退。

解决方案是监听字体加载完成事件。不要依赖window.onload，因为它不能保证字体已加载完毕。应该使用document.fonts.load()这个API，并在其Promise解析后再执行绘制操作。在开发阶段，可以通过开发者工具的Network面板过滤字体请求，确认其状态为成功加载（200）。

回过头看，绝大多数fillText()不显示的问题，都集中在三个方面：字体样式没设对、坐标基准理解错了、或者字体文件还没加载完就急着画。下次遇到类似问题，不妨先从这三个方向排查，往往能更快地找到症结所在。