本教程旨在解决 HTML5 Canvas 在高分辨率屏幕上显示模糊，以及采用 `devicePixelRatio` 缩放后绘图坐标偏移的问题。文章将深入探讨 Canvas 内部尺寸、CSS 样式尺寸与绘图上下文缩放之间的关系，并提供一套完整且专业的解决方案，确保 Canvas 内容在不同分辨率下均能清晰且准确地居中显示。
在现代前端开发中，HTML5 Canvas 因其强大的绘图能力而被广泛应用。然而，在高分辨率（High-DPI）屏幕上，Canvas 默认绘制的内容往往显得模糊。为了解决这一问题，开发者通常会利用 window.devicePixelRatio 对 Canvas 进行缩放。但随之而来的挑战是，一旦 Canvas 的内部绘图缓冲区被放大，原有的绘图坐标计算逻辑可能会失效，导致绘制的元素（如矩形）出现位置偏移。本文将详细阐述这一问题的根源，并提供一套系统化的解决方案。
理解 Canvas 尺寸与设备像素比
要正确处理 Canvas 的高分辨率显示，首先需要理解几个关键概念：
- Canvas 内部绘图尺寸 (canvas.width, canvas.height): 这代表 Canvas 内部绘图缓冲区的实际像素尺寸。例如，如果 canvas.width 为 1000，则内部有 1000 个物理像素点可用于绘图。
- Canvas CSS 样式尺寸 (canvas.style.width, canvas.style.height): 这代表 Canvas 元素在浏览器布局中的显示尺寸，以 CSS 像素为单位。例如，如果 canvas.style.width 为 500px，则该 Canvas 元素在页面上占据 500 CSS 像素的宽度。
- 设备像素比 (window.devicePixelRatio): 这是一个比率，表示一个 CSS 像素对应多少个物理设备像素。在高分辨率屏幕上，devicePixelRatio 通常大于 1（例如，Retina 屏可能为 2 或 3）。这意味着一个 CSS 像素可能由多个物理像素组成。
问题根源分析：
立即学习“前端免费学习笔记（深入）”；
当 devicePixelRatio 大于 1 时，如果 canvas.width 和 canvas.height 与 canvas.style.width 和 canvas.style.height 保持一致，那么 Canvas 的一个内部绘图像素将对应多个物理设备像素，导致绘制的线条和图像看起来模糊。
为了解决模糊问题，一种常见的做法是：
- 将 canvas.width 和 canvas.height 设置为 CSS 样式尺寸乘以 devicePixelRatio。
- 使用 ctx.scale(devicePixelRatio, devicePixelRatio) 缩放绘图上下文。
- 将 canvas.style.width 和 canvas.style.height 设置回原始的 CSS 样式尺寸。
这种方法在高分辨率屏幕上确实能提升清晰度。然而，它也改变了绘图上下文的坐标系。如果绘图逻辑（例如计算居中位置）仍然基于 canvas.width 和 canvas.height（即放大的内部尺寸），那么绘制出来的元素就会显得偏移，因为 ctx.scale 已经将绘图指令的坐标系“放大”了。正确的做法是，绘图逻辑应该始终基于 Canvas 的逻辑尺寸（即 CSS 样式尺寸），而 ctx.scale 会自动将其转换到高分辨率的内部缓冲区。
解决方案：统一逻辑尺寸与绘图上下文
核心思想是：Canvas 绘图逻辑应始终基于其在页面上的逻辑尺寸（CSS 像素），而 devicePixelRatio 相关的缩放应由 Canvas 自身及其绘图上下文来处理。
以下是实现这一目标的步骤和示例代码：
1. Canvas 初始化与缩放函数
我们需要一个函数来负责根据 devicePixelRatio 调整 Canvas 的物理尺寸、CSS 样式尺寸以及绘图上下文。
import React, { useRef, useEffect, useCallback } from 'react';
import style from './CanvasComponent.module.css'; // 假设你的CSS模块
interface Rect {
width: number;
height: number;
}
const CanvasComponent: React.FC = () => {
const canvasRef = useRef<HTMLCanvasElement>(null);
const canvasParentRef = useRef<HTMLDivElement>(null); // Canvas的父容器
// 示例矩形尺寸，这些是逻辑像素尺寸
const rect: Rect = { width: 100, height: 50 };
/**
* 负责 Canvas 的高DPI缩放。
* 它将 Canvas 的内部绘图尺寸放大 devicePixelRatio 倍，
* 同时保持其在DOM中的显示尺寸不变，并缩放绘图上下文。
* @param canvas HTMLCanvasElement 实例
* @param ctx CanvasRenderingContext2D 实例
* @param logicalWidth Canvas 的逻辑宽度（CSS 像素）
* @param logicalHeight Canvas 的逻辑高度（CSS 像素）
*/
const scaleCanvas = useCallback(
(
canvas: HTMLCanvasElement,
ctx: CanvasRenderingContext2D,
logicalWidth: number,
logicalHeight: number
): void => {
const { devicePixelRatio } = window;
// 1. 设置 Canvas 的 CSS 样式尺寸为逻辑尺寸
canvas.style.width = `${logicalWidth}px`;
canvas.style.height = `${logicalHeight}px`;
// 2. 设置 Canvas 的内部绘图尺寸为逻辑尺寸 * devicePixelRatio
// 这将提供一个高分辨率的绘图缓冲区
canvas.width = logicalWidth * devicePixelRatio;
canvas.height = logicalHeight * devicePixelRatio;
// 3. 缩放绘图上下文，使后续的绘图指令基于逻辑像素进行
// 例如，绘制一个100x50的矩形，在缩放后的上下文中，它会占用
// 内部缓冲区中 100*devicePixelRatio x 50*devicePixelRatio 的物理像素
ctx.scale(devicePixelRatio, devicePixelRatio);
},
[]
);
/**
* 计算中心矩形的逻辑坐标。
* 此函数应始终使用 Canvas 的逻辑尺寸进行计算。
* @param logicalWidth Canvas 的逻辑宽度（CSS 像素）
* @param logicalHeight Canvas 的逻辑高度（CSS 像素）
* @returns 包含矩形起始和结束坐标的对象
*/
const centerRectCoords = useCallback(
(logicalWidth: number, logicalHeight: number) => {
const { width, height } = rect; // 矩形尺寸也应是逻辑像素
const startX = logicalWidth / 2 - width / 2;
const startY = logicalHeight / 2 - height / 2;
return {
startX,
startY,
endX: startX + width,
endY: startY + height,
};
},
[rect]
);
/**
* 绘制函数，负责在 Canvas 上绘制所有元素。
* 所有的绘图指令都应基于逻辑像素。
* @param ctx CanvasRenderingContext2D 实例
* @param logicalWidth Canvas 的逻辑宽度
* @param logicalHeight Canvas 的逻辑高度
*/
const draw = useCallback(
(ctx: CanvasRenderingContext2D, logicalWidth: number, logicalHeight: number) => {
// 清空 Canvas
ctx.clearRect(0, 0, logicalWidth, logicalHeight); // 注意这里是逻辑尺寸
// 绘制中心矩形
const { startX, startY, width, height } = { ...centerRectCoords(logicalWidth, logicalHeight), ...rect };
ctx.fillStyle = 'blue';
ctx.fillRect(startX, startY, width, height);
// 可以在这里添加其他基于逻辑像素的绘图
ctx.fillStyle = 'red';
ctx.font = '20px Arial'; // 字体大小也是逻辑像素
ctx.fillText('Hello Canvas!', startX, startY - 10);
},
[centerRectCoords, rect]
);
useEffect(() => {
const canvas = canvasRef.current;
const canvasParent = canvasParentRef.current;
if (!canvas || !canvasParent) {
return;
}
const ctx = canvas.getContext('2d');
if (!ctx) {
return;
}
// 获取父容器的实际逻辑尺寸作为 Canvas 的逻辑尺寸
// getBoundingClientRect() 提供了元素在DOM中的实际布局尺寸
const dimensions = canvasParent.getBoundingClientRect();
const logicalWidth = dimensions.width;
const logicalHeight = dimensions.height;
// 执行 Canvas 缩放
scaleCanvas(canvas, ctx, logicalWidth, logicalHeight);
// 执行绘图
draw(ctx, logicalWidth, logicalHeight);
// 可以在这里添加 resize 监听器，以便在父容器尺寸变化时重新绘制
const handleResize = () => {
const newDimensions = canvasParent.getBoundingClientRect();
const newLogicalWidth = newDimensions.width;
const newLogicalHeight = newDimensions.height;
// 重新执行缩放和绘图
scaleCanvas(canvas, ctx, newLogicalWidth, newLogicalHeight);
draw(ctx, newLogicalWidth, newLogicalHeight);
};
window.addEventListener('resize', handleResize);
return () => {
window.removeEventListener('resize', handleResize);
};
}, [scaleCanvas, draw]); // 依赖项确保在函数更新时重新执行
return (
<div ref={canvasParentRef} className={style.canvasContainer}>
<canvas ref={canvasRef} className={style.canvas} />
</div>
);
};
export default CanvasComponent;2. JSX 结构与 CSS 样式
确保 Canvas 及其父容器有明确的 CSS 尺寸，这样 getBoundingClientRect() 才能返回正确的逻辑尺寸。
// CanvasComponent.tsx // ... (如上所示的 React 组件代码)
/* CanvasComponent.module.css */
.canvasContainer {
width: 100%; /* 确保父容器有明确尺寸 */
height: 400px; /* 或者其他固定高度，或者使用 flex/grid 布局 */
border: 1px solid #ccc;
display: flex; /* 如果需要 Canvas 填充父容器，可以这样设置 */
justify-content: center;
align-items: center;
}
.canvas {
/* Canvas 自身的 style.width/height 会在 JS 中设置，
这里可以不设置，或者设置一个默认的，但会被JS覆盖 */
display: block; /* 避免 Canvas 元素下的额外空间 */
/* 不要在这里设置 width/height，让JS控制 */
}注意事项与总结
- 逻辑尺寸的获取: canvasParentRef.current?.getBoundingClientRect() 是获取 Canvas 逻辑尺寸最可靠的方式，因为它反映了元素在 DOM 中的实际布局尺寸。即使 Canvas 元素在加载时不可见（例如，在 display: none 的标签页中），如果其父容器有明确的尺寸，getBoundingClientRect() 仍能返回这些尺寸。如果父容器也无尺寸，那么需要确保在 Canvas 及其父容器可见并布局完成后再进行尺寸计算和绘图。
- ctx.scale() 的影响: ctx.scale() 会影响所有后续的绘图操作。如果需要绘制不缩放的元素（例如，某些固定大小的 UI 元素），可以使用 ctx.save() 和 ctx.restore() 来保存和恢复上下文状态。
- 事件坐标: 如果需要处理 Canvas 上的鼠标或触摸事件，事件对象中的 offsetX 和 offsetY 属性通常是基于 CSS 像素的。由于我们已经通过 ctx.scale 调整了绘图上下文，这些坐标可以直接用于绘图指令，无需额外转换。
- 响应式设计: 在 useEffect 中添加 window.addEventListener('resize', handleResize) 可以确保当浏览器窗口大小改变时，Canvas 能够重新计算尺寸并重绘，从而实现响应式布局。
- 性能优化: 对于复杂的 Canvas 动画，频繁地重绘整个 Canvas 可能会影响性能。可以考虑使用离屏 Canvas 进行预渲染，或者只重绘发生变化的区域。
通过上述方法，我们实现了 Canvas 在高分辨率屏幕上的清晰显示，同时确保了绘图坐标的准确性，解决了因 devicePixelRatio 缩放导致的元素偏移问题。关键在于始终将绘图逻辑与 Canvas 的逻辑尺寸关联起来，让 ctx.scale() 负责底层物理像素的转换。
