HTMLImageElement.decode 怎样在布局前等待图片解码

动态替换图片时，真正容易被忽略的不是下载，而是“浏览器什么时候已经把像素解码到可以绘制”。如果把新图片直接插入 DOM，下一帧可能还要等待解码；如果先调用 HTMLImageElement.decode()，就可以把图片准备和 DOM 更新拆开。

最小原则是：先创建独立的 Image 对象并设置 src，等待 decode() 返回的 Promise 成功，再把它交给布局或替换当前图片。Promise 成功时没有有用的返回值，重点是“此时图片数据已可使用”；失败时要保留当前画面，并处理 EncodingError。

先分清 load、decode 与 DOM 插入

load 关注资源请求完成，decode() 关注图片数据已经解码到可使用状态，DOM 插入则是把元素交给页面渲染。三者可以连续发生，但职责不同。需要避免空白帧或动态替换闪烁时，通常应该让 decode() 成为“允许插入”的条件。

下面的例子把候选图片留在 DOM 外，等 Promise 成功后再插入。代码中的路径只是示例资源名，读者替换成自己的图片地址即可。

async function appendDecodedImage(container, url) {
  // 先创建独立图片对象，避免未解码的候选图影响当前布局。
  const img = new Image();
  img.src = url;

  try {
    // Promise 成功只表示像素已经准备好，返回值本身是 undefined。
    await img.decode();
    container.appendChild(img);
  } catch (error) {
    // 请求失败、数据损坏或 src 被改动都可能让解码 Promise 拒绝。
    if (error instanceof DOMException && error.name === "EncodingError") {
      console.warn("图片解码失败，保留当前内容", url);
      return;
    }
    throw error;
  }
}

这里不要把 decode() 当作网络请求 API：它没有参数，也不替代尺寸预留、懒加载或响应式图片选择。它解决的是“资源已经拿到后，何时适合交给渲染”的等待点。

低清占位图切高清图时，先准备候选元素

图片画廊常见的做法是先显示低清图，再把高清图替换进去。若直接修改当前元素的 src，当前画面和新请求共享一个对象，处理失败时不容易恢复；更稳的方式是创建候选元素，候选图完成解码后再替换当前元素。

async function swapDecodedImage(current, nextUrl) {
  // 候选元素独立承担新请求，失败时当前图片仍可继续显示。
  const candidate = new Image();
  candidate.alt = current.alt;
  candidate.src = nextUrl;

  try {
    // 只有候选图完成解码，才把它提升为新的渲染目标。
    await candidate.decode();
    current.replaceWith(candidate);
  } catch (error) {
    // src 改动或图片数据异常时，不要用失败候选覆盖当前画面。
    if (error instanceof DOMException && error.name === "EncodingError") {
      console.warn("候选图片不可用，继续使用占位图", nextUrl);
      return current;
    }
    throw error;
  }
  return candidate;
}

这段逻辑的关键不是“等待越久越好”，而是让失败有明确归属：候选图失败只影响候选图，当前图仍然是可用的渲染目标。真实项目还应在开始下一次替换前取消或标记过期请求，避免旧 Promise 晚到后覆盖新选择。

处理 src 变化和异常边界

decode() 绑定的是调用当时的图片请求。如果调用后又修改同一个元素的 src，原来的解码承诺可能因为请求变化而拒绝。因此，不要复用同一个候选元素承载多个并行地址；每个候选地址创建一个新的 Image，并在成功时比较当前任务标识。

let activeRequest = 0;

async function loadLatestImage(container, url) {
  // 用递增标识让晚到的旧请求失去替换资格。
  const requestId = ++activeRequest;
  const candidate = new Image();
  candidate.src = url;

  try {
    // 等待当前候选完成解码，不把旧候选直接写回页面。
    await candidate.decode();
    if (requestId !== activeRequest) return;
    container.replaceChildren(candidate);
  } catch (error) {
    // 只有当前请求仍有效时，才记录这次候选的失败。
    if (requestId === activeRequest) {
      console.warn("当前图片未能完成解码", error);
    }
  }
}

异常名为 EncodingError 时，常见原因包括请求失败、图片数据损坏，或调用后改变了 src。无论哪种原因，都不应清空已经可见的旧图片。若业务需要重试，应重新创建候选元素并给重试次数设上限。

一张表记住该用哪个等待点

常见问题

decode() 成功后会返回图片对象吗？

不会。它返回的 Promise fulfilled 值是 undefined，仍然使用原来的 HTMLImageElement。等待的意义是确认该对象的图片数据已经可以使用。

已经插入 DOM 的图片还能调用 decode() 吗？

可以，但动态替换时更推荐先准备独立候选元素，再在成功后替换。这样失败不会把当前可见图片变成空白状态。

decode() 能解决图片布局跳动吗？

不能单独解决。它减少的是插入后等待解码造成的空白或延迟；布局空间仍应通过图片尺寸属性或 aspect-ratio 提前确定。

归纳起来，decode() 最适合放在“候选图片准备完成”和“DOM 目标更新”之间：成功才替换，失败保留当前画面，地址变化则用新的候选对象和请求标识隔离旧任务。