SVGImageElement：decoding 属性

decoding 是 SVGImageElement 接口的一个属性，它为浏览器提供了一个提示，指示它是否应该同步或异步执行图像解码。

值

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

"sync"

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

"async"

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

"auto"

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

  • Chromium 默认值为 "sync"。
  • Firefox 默认值为 "async"。
  • Safari 默认值为 "sync"，但在少数情况下除外。

用法说明

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

对于插入视口内部 DOM 中的图像，"async" 可能会导致未设置样式的内容闪烁，而 "sync" 可能会导致少量 卡顿。使用 SVGImageElement.decode() 方法通常是实现原子化呈现而不会阻止其他内容的更好方法。

对于插入视口外部 DOM 中的图像，现代浏览器通常会在将其滚动到视图中之前对其进行解码，并且使用任一值都不会有明显的区别。

示例

在下面的示例中，您可能会看到页面上显示了一个空图像，因为图像正在下载。设置 decoding 不会阻止这种情况。

js
const SVG_NS = "http://www.w3.org/2000/svg";
const svg = document.querySelector("svg");

const img = document.createElementNS(SVG_NS, "image");
img.decoding = "sync";
img.setAttribute("href", "img/logo.svg");
svg.appendChild(img);

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

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

const SVG_NS = "http://www.w3.org/2000/svg";
const svg = document.querySelector("svg");

const img = document.createElementNS(SVG_NS, "image");
await loadImage("img/logo.svg", img);
// Using `sync` can ensure other content is only updated with the image
img.decoding = "sync";
svg.appendChild(img);
const text = document.createElementNS(SVG_NS, "text");
text.textContent = "Image is fully loaded!";
svg.appendChild(text);

但是，更好的解决方案是使用 SVGImageElement.decode() 方法来解决此问题。它提供了一种异步解码图像的方法，将将其插入 DOM 推迟到它完全下载并解码，从而避免上述空图像问题。如果您动态地将现有图像替换为新图像，这尤其有用，并且还可以防止在图像解码期间阻止与此代码无关的绘制。

使用 img.decoding = "async" 可能会避免阻止其他内容显示，如果解码时间较长。

js
const SVG_NS = "http://www.w3.org/2000/svg";
const svg = document.querySelector("svg");

const img = document.createElementNS(SVG_NS, "image");
img.decoding = "async";
img.setAttribute("href", "img/logo.svg");
svg.appendChild(img);

规范

规范
HTML 标准
# dom-img-decoding

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅