HTMLImageElement: decoding 属性

The decoding 属性 of the HTMLImageElement interface provides a hint to the browser as to how it should decode the image. More specifically, whether it should wait for the image to be decoded before presenting other content updates or not.

"sync"

同步解码图像，以便与其他内容以原子方式呈现。

"async"

异步解码图像，并允许在图像解码完成之前呈现其他内容。

"auto"

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

• Chromium 默认值为 "sync"。
• Firefox 默认值为 "async"。
• Safari 默认值为 "sync"，除了少数情况。

The decoding property provides a hint to the browser as to whether it should perform image decoding along with other tasks in a single step ("sync"), or allow other content to be rendered before this completes ("async"). In reality, the differences between the two values are often difficult to perceive and, where there are differences, there is often a better way.

For images that are inserted into the DOM inside the viewport, "async" can result in flashes of unstyled content, while "sync" can result in small amounts of jank. Using the HTMLImageElement.decode() method is usually a better way to achieve atomic presentation without holding up other content.

For images inserted into the DOM outside of the viewport, modern browsers will usually decode them before they are scrolled into view and there will be no noticeable difference using either value.

In the below example, you'll likely get an empty image shown on the page as the image is downloaded. Setting decoding won't prevent that.

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

Inserting an image after download can make the decoding property more relevant

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);

A better solution, however, is to use the HTMLImageElement.decode() method to solve this problem. It provides a way to asynchronously decode an image, delaying inserting it into the DOM until it is fully downloaded and decoded, thereby avoiding the empty image problem mentioned above. This is particularly useful if you're dynamically swapping an existing image for a new one, and also prevents unrelated paints outside of this code from being held up while the image is decoding.

Using img.decoding = "async" may avoid holding up other content from displaying if the decoding time is long

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

• The HTMLImageElement.decode() method
• The <img> element decoding attribute
• What does the image decoding attribute actually do? on tunetheweb.com (2023)