HTMLImageElement
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
HTMLImageElement
インターフェイスは HTML の <img>
要素を表現し、画像要素を操作するためのプロパティとメソッドを提供します。
コンストラクター
Image()
-
Image()
コンストラクターは、 DOM ツリーに属さない HTML の<img>
要素を表す新しいHTMLImageElement
オブジェクトを生成し、返します。オプションで幅と高さの引数を受け取ることができます。引数なしで呼び出された場合、new Image()
はdocument.createElement('img')
を呼び出すのと同じになります。
インスタンスプロパティ
親である HTMLElement
から継承したプロパティがあります。
HTMLImageElement.alt
-
文字列で、HTML の
alt
属性を反映します。画像が読み込まれなかった場合に表示される代替フォールバックコンテンツを表します。 HTMLImageElement.complete
読取専用-
論理値で、ブラウザーが画像の取得を完了した場合、成功したかどうかに関わらず
true
を返します。つまり、読み込むべき画像を示すsrc
の値が存在しない場合も、この値はtrue
となります。 HTMLImageElement.crossOrigin
-
文字列で、この画像要素の CORS 設定を指定します。詳細は CORS 設定属性を参照してください。これは CORS が使用されていない場合、
null
になることがあります。 HTMLImageElement.currentSrc
読取専用-
現在表示されている画像が読み込まれた URL を表す文字列を返します。この文字列は、メディアクエリーが適用されている場合、状況の変化に応じて画像が調整され、変更される可能性があります。
HTMLImageElement.decoding
-
ブラウザーが画像をどのようにデコードすべきかのヒントを表すオプションの文字列です。この値を指定する場合、許可されている値のいずれかでなければなりません。同期的に画像をデコードする場合は
sync
、非同期的に画像をデコードする場合はasync
、優先順位を指定しない場合はauto
(これが既定値)です。このプロパティの値の意味については、decoding
のページを参照してください。 HTMLImageElement.fetchPriority
-
オプションの文字列で、他の画像との比較において画像の取得を優先させるためのブラウザーへのヒントを表します。この値を指定する場合、許可されている値のいずれかでなければなりません。高い優先度で取得する場合は
high
、低い優先度で取得する場合はlow
、優先度を設定しない場合はauto
(これが既定値)です。 HTMLImageElement.height
-
HTML の
height
属性を反映した整数値です。画像のレンダリング時の高さを CSS ピクセル数で表します。 HTMLImageElement.isMap
-
HTML の
ismap
属性を反映した論理値で、画像がサーバーサイドイメージマップの一部であることを示します。これは、<img>
要素とそれに対応する<map>
を用いて指定され、画像内のクリック可能な領域を示す<area>
要素を含むクライアントサイドイメージマップと異なるものです。画像は<a>
要素の中に含まれていなければなりません。詳細はismap
のページを参照してください。 HTMLImageElement.loading
-
文書の読み込みを最適化するために使用するブラウザーへのヒントを提供する文字列で、画像をすぐに読み込むか (
eager
) それとも必要に応じて読み込むか (lazy
) を決定します。 HTMLImageElement.naturalHeight
読取専用-
利用できる場合は、画像の本来の高さを CSS ピクセル数で表した整数値を返します。そうでない場合は
0
を示します。これは、画像が自然な大きさでレンダリングされた場合の高さです。 HTMLImageElement.naturalWidth
読取専用-
利用できる場合は、画像の本来の幅を CSS ピクセル数で表した整数値を返します。そうでない場合は
0
を示します。これは、画像が自然な大きさでレンダリングされた場合の幅です。 HTMLImageElement.referrerPolicy
-
HTML の
referrerpolicy
属性を反映した文字列です。画像を取得するためにどのリファラーを使用するかを決定する方法をユーザーエージェントに伝えます。この文字列が取り得る値の詳細については、この記事をお読みください。 HTMLImageElement.sizes
-
HTML の
sizes
属性を反映した文字列です。この文字列は、画像の条件付きサイズのリストをカンマ区切りで指定します。すなわち、与えられたビューポートの大きさに対して、特定の画像サイズが使用されることになります。この文字列の形式の詳細については、sizes
ページにあるドキュメントを参照してください。 HTMLImageElement.src
-
HTML の
src
属性を反映した文字列です。これには、ベース URI を含む画像の完全な URL を指定します。src
属性の URL を変更することで、要素に別の画像を読み込むことができます。 HTMLImageElement.srcset
-
HTML の
srcset
属性を反映した文字列です。これは、画像候補のリストをカンマ (',', U+002C COMMA
) 区切りで指定します。それぞれの候補画像は、 URL の後にスペースが続き、その後に画像のサイズを示す特別な形式の文字列が続きます。サイズは、幅またはサイズの倍数で指定することができます。サイズの部分文字列の形式については、srcset
ページをお読みください。 HTMLImageElement.useMap
-
HTML の
usemap
属性を反映した文字列です。これは、使用するイメージマップを記述した<map>
要素のページローカルな URL を含みます。ページローカルの URL は、ポンド (ハッシュ) 記号 (#
) の後に<map>
要素の ID を続けたもの、例えば#my-map-element
のようになります。<map>
には、画像内のクリック可能な領域を示す<area>
要素が順番に入ります。 HTMLImageElement.width
-
HTML の
width
属性を反映した整数値で、画像のレンダリング幅を CSS ピクセルで表します。 HTMLImageElement.x
読取専用-
<html>
要素を含むブロックの原点に対する、画像の CSS レイアウトボックスの左境界線の水平オフセットを示す整数です。 HTMLImageElement.y
読取専用-
<html>
要素を含むブロックの原点に対する、画像の CSS レイアウトボックスの上境界線の垂直オフセットを示す整数です。
廃止されたプロパティ
HTMLImageElement.align
非推奨-
周囲のコンテキストに対する画像の配置を示す文字列。指定可能な値は
"left"
,"right"
,"justify"
, そして"center"
です。これは時代遅れです。代わりに、 CSS (text-align
など、名前に反して画像で動作するもの)を使って整列を指定する必要があります。 HTMLImageElement.border
非推奨-
画像を囲む境界の幅を定義する文字列。これは非推奨です。代わりに CSS の
border
プロパティを使用してください。 HTMLImageElement.hspace
非推奨-
画像の左右に空ける空間の量を(ピクセル数で)指定する整数値です。
HTMLImageElement.longDesc
非推奨-
画像の内容に関する長い説明文が掲載されている URL を指定する文字列です。これは、画像を自動的にハイパーリンクにするために使用されます。現代的なHTMLでは、ハイパーリンクを定義する
<a>
要素の中に<img>
を代わりに配置します。 HTMLImageElement.name
非推奨-
要素の名前を表す文字列です。
HTMLImageElement.vspace
非推奨-
画像の上下に空ける空間をピクセル単位で指定する整数値です。
インスタンスメソッド
親である HTMLElement
から継承したメソッドがあります。
HTMLImageElement.decode()
-
画像がデコードされ、 DOM に画像を追加しても安全になったときに解決されるプロミス (
Promise
) を返します。これにより、デコードされていない画像が DOM に追加された場合のように、画像をデコードするために次のフレームのレンダリングが中断されることを防ぐことができます。
エラー
画像の読み込みやレンダリング中にエラーが発生し、onerror
イベントハンドラーが error
イベントを処理するために設定されていた場合、そのイベントハンドラーが呼ばれることになります。これは、以下のような様々な状況で起こり得ます。
src
属性がないかnull
である。- 指定された
src
の URL が、ユーザーが現在いるページの URL と同じである。 - 指定された画像が何らかの原因で破損しており、読み込むことができない。
- 指定された画像のメタデータが寸法を取得できない状態に破損しており、
<img>
要素の属性に寸法が指定されていない。 - 指定された画像がユーザーエージェントが対応していない形式である。
例
const img1 = new Image(); // Image コンストラクター
img1.src = "image1.png";
img1.alt = "alt";
document.body.appendChild(img1);
const img2 = document.createElement("img"); // DOM の HTMLImageElement を使う
img2.src = "image2.jpg";
img2.alt = "alt text";
document.body.appendChild(img2);
// 文書内の最初の画像を使用
alert(document.images[0].src);
仕様書
Specification |
---|
HTML Standard # htmlimageelement |
ブラウザーの互換性
BCD tables only load in the browser
関連情報
- このインターフェイスを実装している HTML 要素:
<img>