在 html canvas 上应用自定义字体时，开发者常遇到字体不生效的问题。主要原因在于多词字体名称需要使用引号包裹，并且外部字体必须在绘制前通过 `document.fonts.ready` 确保加载完成。本文将详细讲解这些关键点，并提供实用的代码示例，帮助您在 canvas 中准确渲染自定义文本样式。
HTML Canvas 提供了强大的图形绘制能力，但与 DOM 元素不同，Canvas 内部的文本渲染机制是独立的。这意味着即使您通过 CSS 为父容器设置了自定义字体，Canvas 内部绘制的文本也无法直接继承这些样式。要成功在 Canvas 上应用自定义字体，需要理解并遵循其特有的规则。
一、字体名称的正确引用
在 Canvas 的 2D 渲染上下文（CanvasRenderingContext2D）中，通过 context.font 属性来设置文本样式。其语法与 CSS 的 font 属性类似，但有一个关键区别：对于包含空格的字体名称（即多词字体名称），必须使用单引号或双引号将其包裹起来。
问题分析：
如果您尝试直接使用 context.font = "42px Press Start 2P"; 这样的写法，即使 Press Start 2P 字体已加载并应用于页面的其他 DOM 元素，Canvas 也可能无法识别，并回退到默认字体。这是因为 context.font 解析器会将 Press 视为字体名称，而 Start 和 2P 则被错误地解析为其他字体属性或无效值。
立即学习“前端免费学习笔记（深入）”；
解决方案：
始终将多词字体名称用引号包裹。
// 错误示例：多词字体名称未加引号 // context.font = "42px Press Start 2P"; // 正确示例：多词字体名称使用单引号包裹 context.font = "42px 'Press Start 2P'"; // 或者使用双引号 // context.font = '42px "Press Start 2P"';
请注意，即使您的 CSS 文件中已经正确引入并使用了该字体，Canvas 内部的 context.font 属性仍然需要遵循此引用规则。
二、确保外部字体加载完成
另一个常见的问题是外部字体（如 Google Fonts）的异步加载机制。浏览器加载这些字体文件需要时间，如果 Canvas 在字体文件完全加载并解析完成之前就尝试使用它来绘制文本，那么 Canvas 同样会回退到默认字体。
问题分析：
当您通过 @import 或 标签引入外部字体时，这些字体文件的加载是异步进行的。JavaScript 代码在执行时，可能无法立即获取到这些字体资源。
解决方案：
使用 document.fonts.ready Promise 来确保所有字体都已加载完毕。
document.fonts.ready 是一个 Promise，它在所有通过 CSS 或 FontFace API 定义的字体加载完成（或发生加载错误）后解析。通过 await 或 .then() 方法等待此 Promise 解析，可以确保在绘制 Canvas 文本时，所需的自定义字体已经可用。
综合示例：
以下是一个完整的示例，演示了如何引入 Google Fonts，并在 Canvas 上正确绘制自定义文本，同时处理字体名称引用和异步加载问题。
1. HTML 结构：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Canvas 自定义字体教程</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<div class="canvas-container">
<canvas id="myCanvas" width="600" height="200" style="border: 1px solid #ccc;"></canvas>
</div>
<script src="script.js"></script>
</body>
</html>2. CSS 文件 (style.css)：
/* 引入 Google Fonts 字体 */
@import url('https://fonts.googleapis.com/css2?family=Press+Start+2P&display=swap');
body {
display: flex;
justify-content: center;
align-items: center;
min-height: 100vh;
margin: 0;
background-color: #f0f0f0;
font-family: sans-serif; /* 页面默认字体 */
}
.canvas-container {
/* 这里的 font-family 仅影响 div 内的 DOM 元素，不直接影响 Canvas 绘制 */
font-family: 'Press Start 2P', cursive;
padding: 20px;
background-color: #fff;
box-shadow: 0 4px 8px rgba(0,0,0,0.1);
border-radius: 8px;
}3. JavaScript 文件 (script.js)：
(async () => {
try {
// 等待所有字体加载完成。
// 这包括通过 CSS @import 或 <link> 标签引入的外部字体。
await document.fonts.ready;
console.log('所有字体已加载完成！');
const canvas = document.getElementById("myCanvas");
if (!canvas) {
console.error('Canvas 元素未找到！');
return;
}
const context = canvas.getContext("2d");
// 设置 Canvas 绘制样式
context.fillStyle = 'rgba(50, 70, 90, 0.9)'; // 文本颜色
// 正确引用字体名称，并指定大小
// 建议同时指定备用字体，以防自定义字体加载失败
context.font = "48px 'Press Start 2P', cursive, sans-serif";
context.textAlign = 'center'; // 水平居中
context.textBaseline = 'middle'; // 垂直居中
// 绘制文本
const text = 'Hello Canvas World!';
const centerX = canvas.width / 2;
const centerY = canvas.height / 2;
context.fillText(text, centerX, centerY);
} catch (error) {
console.error('字体加载或 Canvas 绘制时发生错误:', error);
}
})();在上述 JavaScript 代码中，我们使用了 async/await 语法来优雅地处理 document.fonts.ready Promise。await document.fonts.ready; 语句会暂停代码执行，直到所有字体加载完毕，从而确保在 context.fillText 调用时，'Press Start 2P' 字体是可用的。
三、注意事项与最佳实践
- 字体回退机制： 在 context.font 中，除了指定自定义字体外，最好添加一个或多个通用字体族作为备用。例如："48px 'Press Start 2P', cursive, sans-serif"。这样，如果自定义字体因网络问题或其他原因未能加载，Canvas 也能使用一个可接受的默认字体进行渲染。
- 性能考量： 引入过多的自定义字体或字体文件过大可能会影响页面加载性能。仅加载您实际需要的字体样式（例如，只加载常规体，不加载粗体或斜体，除非您真的需要）。
- 错误处理： document.fonts.ready Promise 在字体加载失败时也会解析（尽管通常会回退到默认字体）。在 try...catch 块中包裹您的 Canvas 绘制逻辑，可以更好地处理潜在的加载或渲染错误。
- CSS font-family 与 Canvas context.font 的区别： 再次强调，CSS 中为 DOM 元素设置的 font-family 样式不会直接作用于 Canvas 内部绘制的文本。Canvas 的文本样式必须通过 context.font 独立设置。
总结
在 HTML Canvas 上正确应用自定义字体主要涉及两个关键点：一是多词字体名称必须用引号包裹在 context.font 属性中，例如 'Press Start 2P'；二是必须等待外部字体完全加载完成后才能进行绘制，这通常通过 await document.fonts.ready; 来实现。遵循这些规则，将帮助您避免常见的字体显示问题，并在 Canvas 中准确、美观地渲染自定义文本。
