HTMLImageElement: decoding 属性

值

表示解码提示的字符串。可能的值有：

"sync"

同步解码图像，以便与其他内容进行原子性呈现。

"async"

异步解码图像，允许在完成之前渲染其他内容。

"auto"

对解码模式没有偏好；浏览器会决定对用户来说什么最合适。这是默认值，但不同浏览器有不同的默认值。

• Chromium 默认值为 "sync"。
• Firefox 默认值为 "async"。
• Safari 默认值为 "sync"，但有少数例外情况。

用法说明

decoding 属性为浏览器提供了一个提示，说明它应该将图像解码与其他任务一起执行（"sync"），还是允许在完成之前渲染其他内容（"async"）。实际上，这两个值之间的差异通常难以察觉，而且在有差异的情况下，通常有更好的方法。

对于插入到视口内的 DOM 中的图像，"async" 可能导致未样式化的内容闪烁，而 "sync" 可能导致少量的卡顿。使用 HTMLImageElement.decode() 方法通常是实现原子性呈现而又不延迟其他内容的好方法。

对于插入到视口外的 DOM 中的图像，现代浏览器通常会在它们滚动到视图之前对其进行解码，使用这两种值不会有明显的区别。

示例

在下面的示例中，在图像下载过程中，页面上很可能显示一个空白图像。设置 decoding 属性不会阻止这种情况。

const img = new Image();
img.decoding = "sync";
img.src = "img/logo.png";
document.body.appendChild(img);

下载后插入图像可以使 decoding 属性更具相关性。

async function loadImage(url, elem) {
  return new Promise((resolve, reject) => {
    elem.onload = () => resolve(elem);
    elem.onerror = reject;
    elem.src = url;
  });
}

const img = new Image();
await loadImage("img/logo.png", img);
// Using `sync` can ensure other content is only updated with the image
img.decoding = "sync";
document.body.appendChild(img);
const p = document.createElement("p");
p.textContent = "Image is fully loaded!";
document.body.appendChild(p);

然而，一个更好的解决方案是使用 HTMLImageElement.decode() 方法来解决这个问题。它提供了一种异步解码图像的方法，延迟将其插入 DOM，直到它完全下载并解码，从而避免了上述空白图像的问题。如果你正在动态地将一个现有图像替换为新图像，这一点尤其有用，而且它还可以防止在图像解码时，与此代码无关的绘制操作被延迟。

使用 img.decoding = "async" 可能会避免在解码时间较长时延迟其他内容的显示。

const img = new Image();
img.decoding = "async";
img.src = "img/logo.png";
document.body.appendChild(img);

规范

浏览器兼容性

另见

• HTMLImageElement.decode() 方法
• <img> 元素 decoding 属性
• What does the image decoding attribute actually do? (tunetheweb.com, 2023)