SVGImageElement: decode() 方法

基准线 2025
新推出

自 ⁨2025 年 3 月⁩ 起,此功能可在最新的设备和浏览器版本上使用。此功能可能在旧设备或浏览器上无法正常工作。

SVGImageElement 接口的 decode() 方法会启动图像的异步解码,并返回一个 Promise,该 Promise 在图像解码完成且可以安全地将其添加到 DOM 后解析。

语法

js
decode()

参数

无。

返回值

一个 Promise,一旦图像数据准备好使用(例如,通过将其添加到 DOM、替换现有图像等),就会以 undefined 来 fulfilled。

异常

无。

示例

在下面的示例中,当图像正在下载时,你很可能会在页面上看到一个空白图像。

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

const img = document.createElementNS(SVG_NS, "image");
img.src = "img/logo.svg";
svg.appendChild(img);

使用 decode() 会延迟将图像插入 DOM,直到它完全下载并解码,从而避免了空白图像问题。

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

async function getImage() {
  const img = document.createElementNS(SVG_NS, "image");
  img.src = "img/logo.svg";
  await img.decode();
  svg.appendChild(img);
  const text = document.createElementNS(SVG_NS, "text");
  text.textContent = "Image is fully loaded!";
  svg.appendChild(text);
}

如果你正在动态地将一个现有图像替换为一个新图像,这一点尤其有用,并且还可以防止在图像解码期间,与此代码无关的绘制操作被延迟。

规范

规范
HTML
# dom-img-decode-dev

浏览器兼容性

另见