JavaScript TextMetrics 的 width 与实际左右边界有什么区别

在 Canvas 里用 ctx.measureText(text) 测量文本时，TextMetrics.width 和 actualBoundingBoxLeft、actualBoundingBoxRight 说的不是同一件事：前者更像“排版时向后推进多少”，后两者描述“实际画出来的字形占到哪里”。如果字体带有倾斜、外伸或特殊字形，实际墨迹范围可能比 width 更宽，也可能因为左右留白而不同。

官方文档：https://developer.mozilla.org/en-US/docs/Web/API/TextMetrics

先把两个“宽度”分开

TextMetrics.width 返回的是当前字体下，这段行内文本的 CSS 像素宽度。它服务于排版推进：画完一段文本后，下一段通常沿着这个宽度继续放置。它不等于扫描像素后得到的最左点到最右点。

actualBoundingBoxLeft 是从 Canvas 的文本对齐点向左量到字形包围盒左侧的距离，正值表示向左延伸；actualBoundingBoxRight 则是从同一个对齐点向右量到字形包围盒右侧的距离。对于一个已知对齐点 anchorX，可以用下面的关系得到实际水平范围：

const metrics = ctx.measureText(text);

// actualBoundingBoxLeft 的正方向是从对齐点向左，所以左坐标要相减。
const visibleLeft = anchorX - metrics.actualBoundingBoxLeft;
// actualBoundingBoxRight 从对齐点向右量，右坐标直接相加。
const visibleRight = anchorX + metrics.actualBoundingBoxRight;
const visibleWidth = visibleRight - visibleLeft;

当文本是普通正体时，两个结果经常看起来很接近；但这只是常见情况，不是 API 契约。倾斜字体的字形可能越过自己的 advance width，导致左右实际边界之和大于 width。

为什么斜体会让 width 和实际边界错开

绘制文本时，浏览器既要给这段文字安排一个可供后续内容使用的行内宽度，也要按照字体轮廓真正绘制字形。斜体的笔画可能向前或向后探出，字形轮廓的极值因此不必刚好落在 advance width 的两端。MDN 的示例也专门指出，斜体文字的 actualBoundingBoxLeft + actualBoundingBoxRight 可能比 width 更大。

另一个容易忽略的因素是 textAlign。measureText() 得到的左右距离都围绕对齐点表达：left、center、right 会改变对齐点落在哪里，但不会把这两个属性变成“相对于画布左边的绝对坐标”。所以先确认锚点，再做坐标换算。

给文本背景框留空间时，应该用实际边界

例如要给 Canvas 标签文字绘制一个圆角背景，目标通常是包住“看得见的墨迹”，而不是只包住下一段文本的推进区域。此时先测量两个实际边界，再加上内边距：

function drawLabel(ctx, text, boxLeft, boxTop, boxWidth) {
  const metrics = ctx.measureText(text);
  const left = Number.isFinite(metrics.actualBoundingBoxLeft)
    ? metrics.actualBoundingBoxLeft
    : 0;
  const right = Number.isFinite(metrics.actualBoundingBoxRight)
    ? metrics.actualBoundingBoxRight
    : metrics.width;
  const inkWidth = left + right;
  const paddingX = 10;
  const anchorX = boxLeft + (boxWidth - inkWidth) / 2 + left;

  // 先用真实墨迹宽度确定背景框，斜体外伸时不会紧贴或裁掉字形。
  const backgroundLeft = anchorX - left - paddingX;
  const backgroundWidth = inkWidth + paddingX * 2;
  ctx.fillStyle = "#e8f1ff";
  ctx.fillRect(backgroundLeft, boxTop, backgroundWidth, 34);

  // baseline 只控制文字的垂直基线，不改变左右边界的计算方式。
  ctx.fillStyle = "#17324d";
  ctx.textAlign = "left";
  ctx.fillText(text, anchorX, boxTop + 23);
}

这个例子固定使用 textAlign = "left"，因此 anchorX 就是文本的对齐点。若改成 center 或 right，仍然可以用 actualBoundingBoxLeft 和 actualBoundingBoxRight 推导可见左右坐标，但必须把锚点语义保留下来，不能继续把 anchorX 当成文本盒子的左边。

迁移旧代码时按用途选择属性

如果旧代码只做单行文本排列、计算下一个标签的起点，继续使用 width 通常更符合“advance”语义。把它直接换成左右实际边界之和，可能让相邻文本间距随字体轮廓改变，造成布局抖动。

如果代码负责背景框、裁剪区域、命中检测或和图形做碰撞判断，应优先计算可见左右坐标。尤其是斜体、手写风格字体、带明显外伸笔画的字形，单独拿 width 当视觉宽度会留下空隙，或者在紧贴边界时发生裁剪。

对于需要兼容旧环境的组件，可以像示例一样用 Number.isFinite() 做保守兜底：实际左边界缺失时不向左扩展，实际右边界缺失时退回 width。这不是把两种指标混为一谈，而是明确告诉组件：当前环境无法提供墨迹边界时，退回排版宽度。

最小核对：把两个数放在同一张表里

const canvas = document.querySelector("canvas");
const ctx = canvas.getContext("2d");
const text = "Italic canvas label";

// 使用倾斜字体，让 advance width 与可见边界的差异更容易被观察。
ctx.font = "italic 50px serif";
const metrics = ctx.measureText(text);
const inkWidth = metrics.actualBoundingBoxLeft + metrics.actualBoundingBoxRight;

console.table({
  // width 是排版推进宽度，不代表一定覆盖所有可见笔画。
  advanceWidth: metrics.width,
  // 左右实际边界相加更接近本次绘制的水平墨迹范围。
  visibleInkWidth: inkWidth,
  difference: inkWidth - metrics.width,
});

核对时不要只看差值是否为零。应先问清楚目标：若目标是“下一段从哪里开始”，看 advanceWidth；若目标是“背景框或命中区域包住哪里”，看 visibleInkWidth 以及由对齐点换算出的左右坐标。

相关问题

actualBoundingBoxLeft + actualBoundingBoxRight 一定等于可见像素宽度吗？

它是 TextMetrics 提供的字形包围盒水平范围，适合做布局近似和边界计算，但不要把它理解为逐像素 alpha 扫描结果。抗锯齿、字体渲染和具体字形都会影响最终像素。

计算文本背景框时只用 width 有什么问题？

正体短文本可能看不出问题，但斜体或外伸字形可能越过推进盒边缘。背景框贴得很紧时，左右边界会不对称，严重时笔画会被裁掉。

textAlign = "center" 后还要自己换算左右坐标吗？

要。actualBoundingBoxLeft 和 actualBoundingBoxRight 仍然是相对对齐点的距离，先按 anchorX - left 与 anchorX + right 得到可见范围，再决定背景框或碰撞区域。