上周把一个项目从 API 11 往新版本迁移，编译的时候蹦出来一串 Deprecated 警告，其中有一行格外扎眼： measureText 被标废弃了。当时我还愣了几秒，这 API 从 HarmonyOS 第一个 Canvas 版本就在用，怎么说弃就弃？后来翻了官方变更通告和配套文档，又自己动手把项目里的绘图代码全部适配了一遍，才算是彻底搞明白这次变更背后的逻辑。这篇文章就把我的适配过程和踩坑记录完整梳理一遍，当作《精通HarmonyOS NEXT：鸿蒙App开发入门与项目化实战》读者的一份加更福利，希望能帮同样在做 Canvas 绘图的开发者少走弯路。

1. 这次废弃到底波及了谁

先别急着看代码，搞清楚影响范围比闷头改代码更重要。 measureText 是 CanvasRenderingContext2D 对象上的一个方法，核心作用就是测量一段文本在画布上绘制时占用的宽度。只要你的应用里有用 Canvas 绘制文字的场景，比如绘制图表标签、游戏计分板、验证码图片、富文本排版，或者做一个带背景框的文本标签，大概率都调用过它。

我在自己维护的两个项目里搜了一圈，一共找到 13 处直接调用 measureText 的代码，分布在图表库、图像水印模块和两个自定义绘图组件里。这个覆盖面很有代表性—— measureText 属于基础能力，业务代码不会直接感知到它的存在，但一旦底层 API 变动，所有依赖它的模块都会受影响。

值得注意的一点是，这次废弃不是直接删除。官方采取了标准的废弃策略：标记为 deprecated，保留兼容窗口期，但在新版 SDK 和后续系统版本里不再做功能增强和 bug 修复。也就是说，你现在不迁移，项目短期还能跑，但长期停留在老 API 上，会错过新系统在文本渲染、性能优化上的能力，而且越往后迁移成本越高。据我观察，官方推动废弃这套文本测量方式，核心原因是想要统一的文本布局引擎，让 Canvas 侧和 ArkUI 组件侧的文本测量逻辑收敛到同一套底层实现。老接口是 Canvas 自己维护的一套测量逻辑，和 ArkUI 的文本组件走的是两条路，容易出现同一段文字在不同场景下测量结果不一致的问题。

所以这次适配，本质上是把文本测量能力从"画布私有"切换到"全局统一"，理解了这一点，后面的代码改动方向就非常清晰了。

2. 旧接口的四个硬伤，不换不行

很多开发者看到 API 废弃第一反应是"官方又搞事"，但这次我愿意给官方点个赞。旧版 measureText 的问题，我在实际项目里都真切踩到过，随便挑四个典型的说说。

第一个问题是测量结果和实际渲染可能不一致。旧接口的测量依赖当前 Canvas 上下文保存的 font 属性，而这个 font 属性本质上是一个字符串拼接的状态值。一旦你在设置字体时用的字重、字号写法和测量时不完全一致，测出来的宽度就和实际画出来的宽度对不上。我做个一个雷达图，标签文字总是超出背景框，排查了半小时发现是设置字体时写的 "14vp sans-serif" ，测量时写成了 "14vp sans-serif" ，就多了个空格，量出来就不一样了。这种问题排查起来非常恶心，跑起来不报错，就是效果不对。

第二个问题是只能测量单行文本。实际业务里，文字换行、多行文本的区域计算是高频场景，但旧接口只返回一个宽度值，拿到之后还得自己根据宽度手动算换行。换行逻辑一旦涉及中英文混排、标点挤压、断词规则，自己算就很容易和系统排版引擎的规则产生偏差。之前做一个多行文本溢出省略的需求，我用 measureText 循环判断换行位置，在英文长单词和中文长句子混排时，出现了三四次截断位置不理想的问题，用户反馈了好几轮。

第三个问题是性能层面的。每次调用 measureText 都是一次与底层渲染引擎的交互，在循环逻辑里频繁调用时性能损耗会被放大。我做数据可视化大屏时，一个图表要绘制上百个标签，每个标签为了自适应宽度要先测量再调整字号，反复测量导致首屏渲染时间明显变长。后来用缓存宽度值的方式优化了一版，但代码变得很丑。

第四个问题是和 Web Canvas 的兼容性。HarmonyOS 的 Canvas 接口早期参考了 Web 标准， measureText 的命名和用法和浏览器一致，这让前端转鸿蒙的开发者上手很快。但这种方式治理成本高，文本测量逻辑分散在 Canvas 实现内部，很难复用到原生组件，也难做统一的性能优化。官方这次推动废弃，本质上是为后续鸿蒙自研的文本排版引擎铺路。

明白这些之后，适配思路就很清晰了：不再向画布上下文索要测量结果，而是创建一个独立的文本测量器，显式配置字体、字号、字重等参数，再执行测量。这套新方案就是接下来要讲的 TextMeasure 。

3. 新方案 TextMeasure 上手，核心就五步

3.1 从画布独立出来的测量器

新方案的核心是一个独立的 TextMeasure 实例。它和 Canvas 上下文解耦，你可以在任意位置创建，测量任意文本，不再依赖某个画布是否已经初始化、是否设置了 font 属性。我理解它的定位是"文本测量工具箱"，你给它一份文本、一套样式，它给你精确的测量结果。

使用流程干净利落，五步走：创建 TextMeasure 实例、构造 TextStyle 样式对象、把样式挂到测量器上、调用 measureText 方法、从返回的 TextMetrics 里取数据。这套流程不需要画布参与，意味着你可以提前在业务逻辑层完成文字尺寸计算，比如在布局阶段就确定一个标签组件的宽度，而不必等到 Canvas 绘制阶段再去临时量。

3.2 关键代码，新旧接口对照

直接看代码比什么都直观。先看旧写法：

// 旧写法：依赖 CanvasContext 的 font 状态
const ctx = canvas.getContext('2d') as CanvasRenderingContext2D;
ctx.font = '14vp sans-serif';
const metrics = ctx.measureText('鸿蒙开发实战');
const width = metrics.width; // 拿到的是像素宽度

这段代码看起来简洁，但隐患就是前面说的： ctx.font 是个字符串状态，拼写和格式稍有不一致就会导致测量偏差。再看新写法：

import { TextMeasure, TextStyle } from '@kit.ArkGraphics2D';

// 新写法：显式的样式对象
const textMeasure = new TextMeasure();
const style = new TextStyle();
style.fontSize = 14;
style.fontWeight = FontWeight.Normal;
// 其他可选设置
// style.fontFamily = 'HarmonyOS Sans SC';
// style.fontStyle = FontStyle.Normal;
textMeasure.style = style;

const metrics = textMeasure.measureText('鸿蒙开发实战');
const width = metrics.width;

视觉上确实比旧写法多了几行代码，但换来的是明确性和可靠性。 TextStyle 是一个结构化对象，每个属性都是独立字段，不会再出现字符串解析的歧义。实际工程里，我会把创建 TextMeasure 的代码封装成一个小工具类，内部缓存测量器实例和样式对象，避免每次测量都重复创建。

3.3 返回结果直观且丰富

measureText 返回 TextMetrics 对象，除了基础的 width ，还能拿到 height 、 actualBoundingBoxLeft 、 actualBoundingBoxRight 等字段。对于只想知道文字有多宽的简单场景，用 width 就够了，比如判断文本是否超长需要截断；对于需要精确定位绘制起点的场景， actualBoundingBoxLeft 和 actualBoundingBoxRight 就派上大用场了，它们描述的是文本实际绘制区域的左右边界，比单纯用 width 做对齐更精确。

我自己的使用习惯是：涉及文字垂直居中的场景，一定会用 height 或者 actualBoundingBoxAscent 加上 actualBoundingBoxDescent 来算基线偏移，直接用字体高度除以二大概率会偏。这个细节在绘制中文文本时尤其重要，中文字形的上下留白空间和拉丁字母不同，简单的居中算法经常会出现视觉上的偏差。

3.4 多行文本测量，一个容易被忽略的宝藏能力

TextMeasure 还有一个在老接口上做起来很痛苦的能力：多行文本测量。它支持通过参数控制最大行数和换行策略，然后直接返回整体尺寸。我接手过一个文本卡片组件，卡片高度需要根据文字多少自适应，文字两三行以内用单行文本，超过之后显示省略号。旧方案需要循环调用 measureText 拼凑逻辑，换用新接口后直接设置 maxLines 等于 2，测量一次就拿到整体宽度和高度，代码量少了一半还多，计算逻辑也更贴合系统排版引擎的真实行为。

这个能力对做动态排版、文字自适应布局的开发者来说，基本可以替代手写换行判断的整套逻辑。我强烈建议在适配时重新审视一下你项目里所有涉及文字换行计算的代码，很可能有一大半可以直接砍掉。

4. 实操演练：把两个真实场景从旧迁移到新

4.1 场景一：自适应宽度的文本标签

我项目里有个标签组件，需求是标签的背景框宽度跟随文字宽度自适应，同时保持左右内边距。旧实现里，绘制顺序是先用 Canvas 测宽度，再加内边距画圆角矩形，最后绘制文字。

迁移后的逻辑大致是这样：

import { TextMeasure, TextStyle, TextMetrics } from '@kit.ArkGraphics2D';

function drawAdaptiveLabel(canvasCtx: CanvasRenderingContext2D, text: string, fontSize: number, padding: number) {
  // 1. 创建并配置测量器（实际工程建议缓存复用）
  const textMeasure = new TextMeasure();
  const style = new TextStyle();
  style.fontSize = fontSize;
  style.fontFamily = 'HarmonyOS Sans SC';
  textMeasure.style = style;

  // 2. 测量文本
  const metrics: TextMetrics = textMeasure.measureText(text);
  const textWidth = metrics.width;

  // 3. 计算容器宽度
  const labelWidth = textWidth + padding * 2;
  const baselineY = 50;
  // 4. 绘制背景框
  canvasCtx.fillStyle = '#1E88E5';
  canvasCtx.fillRect(10, baselineY - fontSize, labelWidth, fontSize * 1.5);

  // 5. 绘制文字（注意此时画布的 font 需要和测量时保持一致）
  canvasCtx.fillStyle = '#FFFFFF';
  canvasCtx.font = `${fontSize}vp HarmoneyOS Sans SC`;
  canvasCtx.fillText(text, 10 + padding, baselineY);
}

这里有个细节必须强调：虽然 TextMeasure 不再依赖画布的 font 属性，但最终绘制文字时，画布的 font 属性依然要保证和测量样式一致。测量归测量，绘制归绘制，两边的字体参数对不上，照样会出现文字溢出背景框的问题。这是迁移过程中最容易踩的坑，没有之一。

4.2 场景二：在绘制前确定动态换行位置

这个场景的需求是把一段话绘制到一个固定宽度的区域内，超出部分不显示。以前我只能在绘制阶段拿到 Canvas 上下文之后才能测量，导致布局计算和绘制逻辑强耦合在一起。现在可以在业务逻辑层完成所有测量，代码如下：

import { TextMeasure, TextStyle } from '@kit.ArkGraphics2D';

function measureWrappedText(text: string, maxWidth: number, fontSize: number): string[] {
  const textMeasure = new TextMeasure();
  const style = new TextStyle();
  style.fontSize = fontSize;
  textMeasure.style = style;

  // 先用基础测量得知单个字符的宽度
  const singleCharMetrics = textMeasure.measureText('测');
  const singleCharWidth = singleCharMetrics.width;
  // 粗略估算可容纳字符数
  const estimatedCharCount = Math.floor(maxWidth / singleCharWidth);

  const lines: string[] = [];
  let currentLine = '';
  for (let i = 0; i < text.length; i++) {
    const char = text[i];
    const testLine = currentLine + char;
    const lineMetrics = textMeasure.measureText(testLine);
    if (lineMetrics.width <= maxWidth) {
      currentLine = testLine;
    } else {
      lines.push(currentLine);
      currentLine = char;
    }
  }
  if (currentLine) {
    lines.push(currentLine);
  }
  return lines;
}

这套逻辑的核心思路还是逐字累加测量，但和旧版不同的是，它可以在任何代码位置执行，不依赖 Canvas 上下文，可以放到 ViewModel、工具类、甚至 Worker 线程里。这对性能优化是质的提升——以前必须在 UI 线程拿到画布才能算布局，现在布局计算和绘制彻底分开了，绘制阶段只需要按照算好的结果执行即可。

实际工程中，图表库、排版引擎这类重 Canvas 场景，完全可以把所有文本测量和换行计算提前到数据准备阶段，绘制时零测量直接渲染，首帧时间能有明显优化。

5. 迁移避坑指南：这些问题我替你踩过了

5.1 字体没加载完就测量，结果必错

这是最容易踩的坑，也是最隐蔽的。鸿蒙系统里字体是异步加载的，特别是自定义字体。如果在字体注册完之前就用 TextMeasure 去测量文本，它拿不到真实的字形数据，只能用默认字体宽度的近似值，测出来的宽度会明显小于实际渲染宽度。我做过一个数字大屏项目，数字字体是自定义下载的，首帧绘制时经常出现数字宽度不足、重叠的问题。

解决方案是确保字体加载完成后再执行测量和绘制。可以通过 font.registerFont 的回调或者在自定义字体加载的 Promise 链中统一处理，让绘制函数等待字体就绪的信号再执行。

5.2 样式参数保持一致性，一个都不能漏

新方案解决了旧接口字符串拼接的歧义，但引入了新的要求： TextStyle 和绘制时的字体参数必须一致。不要只设置 fontSize 就以为完事了，还有 fontWeight 、 fontStyle 、 fontFamily 这些因素都会影响测量结果。实际适配时，我建议把样式对象抽取成公共常量，测量和绘制都引用同一份，从根本上杜绝不一致。

// 公共样式常量，测量和绘制共用
export const LABEL_TEXT_STYLE = {
  fontSize: 14,
  fontWeight: FontWeight.Medium,
  fontFamily: 'HarmonyOS Sans SC'
};

5.3 单位换算的坑：vp 和 px 别混用

鸿蒙开发里的尺寸单位主要有 vp （虚拟像素）和 px （物理像素）。 TextStyle 里 fontSize 字段默认使用的是 vp 。如果你在测量时传的是 vp 值，但绘制时把画布的 font 写成了像素值，或者反过来，测量结果会有明显偏差。特别是在不同分辨率的设备上， vp 和 px 的换算系数不一样，一旦混用，同一个布局在不同设备上会出现不同的表现效果，严重的话直接文字溢出。

我的建议很简单： TextStyle 里写 vp 值，Canvas 绘制文字时把 font 也设置为对应的 vp 格式，两边对齐，不要混写。

5.4 版本兼容与降级策略

新系统支持 TextMeasure ，但你的应用可能还需要兼容老版本设备。我目前的处理方式是做一个能力检测，支持就直接用新接口，不支持就走旧逻辑。具体做法是用 canIUse 接口判断 TextMeasure 是否可用：

function isTextMeasureAvailable(): boolean {
  return canIUse('TextMeasure') || typeof (globalThis as any).TextMeasure !== 'undefined';
}

或者更稳妥一点，根据 API version 做判断。兼容层代码如下：

import { TextMeasure, TextStyle } from '@kit.ArkGraphics2D';

function measureTextWidth(text: string, fontSize: number): number {
  if (isTextMeasureAvailable()) {
    const textMeasure = new TextMeasure();
    const style = new TextStyle();
    style.fontSize = fontSize;
    textMeasure.style = style;
    return textMeasure.measureText(text).width;
  } else {
    // 降级方案：暂存画布上下文，后续创建Canvas时补充测量
    // 这里可以按旧逻辑实现，或者接受一个 canvas context 参数
    // 实际工程中结合业务场景选择
    return fontSize * text.length; // 仅降级估算
  }
}

降级方案只是一个兜底策略，核心逻辑还是尽快全面迁移到新接口，不要对旧接口有依赖心理。

5.5 实测对比验证

全部迁移完成后，我针对相同的 100 组文本在旧接口和新接口上分别做了测量对比。结论是：在字体正确加载、样式参数设置一致的前提下，两者的测量结果误差在 1vp 以内，肉眼层面完全无感。但在设置了自定义字体、复杂字重、多行排版等场景下，新接口的测量结果更接近系统 ArkUI 组件的实际渲染效果。这说明官方的统一文本渲染策略确实在起作用——Canvas 绘制出来的文字和普通 Text 组件的排版表现越来越一致了，这是个很积极的信号。

我还做了一个小工具做批量测量对比，把新旧两种情况画在同一张图上，用不同颜色标出边界，方便直观看到差异。适配完成后，整体渲染效果和旧版保持一致，但代码的结构清爽了很多，性能也有小幅提升。

6. 读者福利：适配包和源码同步更新

这次 measureText 的适配，正好是我在整理《精通HarmonyOS NEXT：鸿蒙App开发入门与项目化实战》配套源码时完成的。随书项目里有几个 Canvas 绘制相关的案例，这次全部同步做了适配更新。如果你是这本书的读者，不需要自己去翻变更日志和逐行改代码，直接去配套资源里拉取更新就好，仓库里已经准备好了适配后的版本，并保留了新旧两版代码的对照说明，方便你理解差异。

另外，为了让大家更平滑地完成这次迁移，我把一个可复用的 TextMeasureUtils 封装代码整理了出来，包括样式统一管理、旧版本降级逻辑、字体加载后的自动重测方案，都在源码仓库的工具模块里。公众号后台回复"measureText"可以直接获取详细的迁移笔记和比对工具源码。如果适配过程中遇到问题，欢迎在读者群或评论区交流，一个人踩坑是困惑，一群人踩坑就成了经验。

7. 这次迁移带给我的几个思考

API 废弃这件事，在一个平台快速迭代的时期其实是常态。老开发者可能觉得烦，但从另一个角度看，系统在进步，API 在收敛，新工具的出现是为了解决老工具解决不好的问题。

从 measureText 迁移到 TextMeasure ，表面上只是换了一个方法名，实际上是从"画布上下文附属能力"到"独立文本测量引擎"的思路转变。这个转变让文本测量从 Canvas 里解放了出来，可以服务于更广泛的场景。做完这次适配之后，我更倾向于在项目里给文本测量单独抽一层封装，不管是 Canvas 绘制还是自定义组件布局，都走同一个测量入口。这样以后底层 API 再有变动，只需要改封装内部，业务代码一行不动。

最后分享一个小技巧：每次升级 SDK 版本或者系统版本，不要只盯编译报错，把编译警告也当回事。Deprecated 警告就是官方在给你提前打招呼——这东西要变了，尽早调整。养成这个习惯之后，很多看似措手不及的 API 变动，其实你早就提前知道了。这次要是没有编译警告的提示，我可能还不会意识到 measureText 已经进入了废弃流程，到时候等它在某个版本里真正移除后再迁移，成本远高于现在。