HTMLImageElement: decode() メソッド

構文

decode()

引数

なし。

返値

Promise で、画像データが利用できるようになったときに undefined で履行されます。

例外

EncodingError

画像のデコード中にエラーが発生したことを示す DOMException です。

使用上の注意

decode() の潜在的な使用例の一つです。非常に大きな画像を読み込む場合（例えばオンラインのフォトアルバムで）、最初は低解像度のサムネイル画像を表示し、その後、新しい HTMLImageElement をインスタンス化してそのソースにフル解像度画像の URL を設定し、decode() を使ってプロミスを取得し、フル解像度画像が使えるようになったときに解決することによって、画像をフル解像度画像と交換することが可能です。その際、低解像度の画像を、現在利用可能なフル解像度の画像に置き換えることができます。

例

基本的な使い方

次の例では、 decode() メソッドを使って、画像が DOM に追加されるタイミングを制御しています。

const img = new Image();
img.src = "nebula.jpg";
img
  .decode()
  .then(() => {
    document.body.appendChild(img);
  })
  .catch((encodingError) => {
    // エラー時に何かをする。
  });

空の画像の防止

下記の例では、画像がダウンロードされると、ページに空の画像が表示されることになります。

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

decode() を使用すると、画像が完全にダウンロードされデコードされるまで DOM への挿入を遅らせることができ、空の画像の問題を避けることができます。

async function getImage() {
  const img = new Image();
  img.src = "img/logo.png";
  await img.decode();
  document.body.appendChild(img);
  const p = document.createElement("p");
  p.textContent = "Image is fully loaded!";
  document.body.appendChild(p);
}

これは、既存の画像と新しい画像を動的に入れ替える場合に具体的な有益な方法です。また、画像のデコード中に、このコード以外の無関係な描画が中断されるのを防ぐこともできます。

仕様書

ブラウザーの互換性

関連情報

• What does the image decoding attribute actually do? (tunetheweb.com, 2023)
• HTMLImageElement.decoding プロパティ