1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
---
title: HTMLImageElement
slug: Web/API/HTMLImageElement
translation_of: Web/API/HTMLImageElement
---
<div>{{APIRef("HTML DOM")}}</div>
<p><strong><code>HTMLImageElement</code></strong> 介面提供了特殊的屬性及方法以用來操作 {{HTMLElement("img")}} 元素的畫面佈局與外觀呈現。</p>
<p>{{InheritanceDiagram(600,120)}}</p>
<h2 id="屬性">屬性</h2>
<p><em>Inherits properties from its parent, {{domxref("HTMLElement")}}.</em></p>
<dl>
<dt>{{domxref("HTMLImageElement.align")}} {{obsolete_inline}}</dt>
<dd>Is a {{domxref("DOMString")}} indicating the alignment of the image with respect to the surrounding context.</dd>
<dt>{{domxref("HTMLImageElement.alt")}}</dt>
<dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("alt", "img")}} HTML attribute, thus indicating fallback context for the image.</dd>
<dt>{{domxref("HTMLImageElement.border")}} {{obsolete_inline}}</dt>
<dd>Is a {{domxref("DOMString")}} that is responsible for the width of the border surrounding the image. This is now deprecated and the CSS {{cssxref("border")}} property should be used instead.</dd>
<dt>{{domxref("HTMLImageElement.complete")}} {{readonlyInline}}</dt>
<dd>Returns a {{domxref("Boolean")}} that is <code>true</code> if the browser has finished fetching the image, whether successful or not. It also shows true, if the image has no {{domxref("HTMLImageElement.src", "src")}} value.</dd>
<dt>{{domxref("HTMLImageElement.crossOrigin")}}</dt>
<dd>Is a {{domxref("DOMString")}} representing the CORS setting for this image element. See <a href="/en-US/docs/HTML/CORS_settings_attributes">CORS settings attributes</a> for further details.</dd>
<dt>{{domxref("HTMLImageElement.currentSrc")}} {{readonlyInline}}{{experimental_inline}}</dt>
<dd>Returns a {{domxref("DOMString")}} representing the URL to the currently displayed image (which may change, for example in response to media queries).</dd>
<dt>{{domxref("HTMLImageElement.height")}}</dt>
<dd>一個反映了 HTML <code>img</code> 元素之 {{htmlattrxref("height", "img")}} 屬性的無符號（<code>unsigned</code>）整數，表示圖片經渲染後的高度（CSS pixels）。</dd>
<dt>{{domxref("HTMLImageElement.hspace")}} {{obsolete_inline}}</dt>
<dd>Is a <code>long</code> representing the space on either side of the image.</dd>
<dt>{{domxref("HTMLImageElement.isMap")}}</dt>
<dd>Is a {{domxref("Boolean")}} that reflects the {{htmlattrxref("ismap", "img")}} HTML attribute, indicating that the image is part of a server-side image map.</dd>
<dt>{{domxref("HTMLImageElement.longDesc")}} {{obsolete_inline}}</dt>
<dd>Is a {{domxref("DOMString")}} representing the URI of a long description of the image.</dd>
<dt>{{domxref("HTMLImageElement.lowSrc")}} {{obsolete_inline}}</dt>
<dd>Is a {{domxref("DOMString")}} that refers to a low-quality (but faster to load) copy of the image.</dd>
<dt>{{domxref("HTMLImageElement.name")}} {{obsolete_inline}}</dt>
<dd>Is a {{domxref("DOMString")}} representing the name of the element.</dd>
<dt>{{domxref("HTMLImageElement.naturalHeight")}} {{readonlyInline}}</dt>
<dd>回傳一個代表圖片固有高度（CSS pixels）的無符號（<code>unsigned</code>）整數，如果無法取得則回傳 <code>0</code>。</dd>
<dt>{{domxref("HTMLImageElement.naturalWidth")}} {{readonlyInline}}</dt>
<dd>回傳一個代表圖片固有寬度（CSS pixels）的無符號（<code>unsigned</code>）整數，如果無法取得則回傳 <code>0</code>。</dd>
<dt>{{domxref("HTMLImageElement.referrerPolicy")}} {{experimental_inline}}</dt>
<dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("referrerpolicy", "img")}} HTML attribute indicating which referrer to use in order to fetch the image.</dd>
<dt>{{domxref("HTMLImageElement.src")}}</dt>
<dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("src", "img")}} HTML attribute, containing the full URL of the image including base URI.</dd>
<dt>{{domxref("HTMLImageElement.sizes")}} {{experimental_inline}}</dt>
<dd>Is a {{domxref("DOMString")}} reflecting the {{htmlattrxref("sizes", "img")}} HTML attribute.</dd>
<dt>{{domxref("HTMLImageElement.srcset")}} {{experimental_inline}}</dt>
<dd>Is a {{domxref("DOMString")}} reflecting the {{htmlattrxref("srcset", "img")}} HTML attribute, containing a list of candidate images, separated by a comma (<code>',', U+002C COMMA</code>). A candidate image is a URL followed by a <code>'w'</code> with the width of the images, or an <code>'x'</code> followed by the pixel density.</dd>
<dt>{{domxref("HTMLImageElement.useMap")}}</dt>
<dd>Is a {{domxref("DOMString")}} that reflects the {{htmlattrxref("usemap", "img")}} HTML attribute, containing a partial URL of a map element.</dd>
<dt>{{domxref("HTMLImageElement.vspace")}} {{obsolete_inline}}</dt>
<dd>Is a <code>long</code> representing the space above and below the image.</dd>
<dt>{{domxref("HTMLImageElement.width")}}</dt>
<dd>一個反映了 HTML <code>img</code> 元素之 {{htmlattrxref("width", "img")}} 屬性的無符號（<code>unsigned</code>）整數，表示圖片經渲染後的寬度（CSS pixels）。</dd>
<dt>{{domxref("HTMLImageElement.x")}} {{readonlyInline}}{{experimental_inline}}</dt>
<dd>Returns a <code>long</code> representing the horizontal offset from the nearest layer. This property mimics an old Netscape 4 behavior.</dd>
<dt>{{domxref("HTMLImageElement.y")}} {{readonlyInline}} {{experimental_inline}}</dt>
<dd>Returns a <code>long</code> representing the vertical offset from the nearest layer. This property is also similar to behavior of an old Netscape 4.</dd>
</dl>
<h2 id="方法">方法</h2>
<p><em>Inherits properties from its parent, {{domxref("HTMLElement")}}.</em></p>
<dl>
<dt>{{domxref("HTMLImageElement.Image()", "Image()")}}</dt>
<dd>The <code>Image()</code> constructor, taking two optional <code>unsigned</code> <code>long</code>, which are the width and the height of the resource, creates an instance of <code>HTMLImageElement</code> , not inserted in a DOM tree.</dd>
</dl>
<h2 id="Errors">Errors</h2>
<p>If an error occurs while trying to load or render the image, and an {{htmlattrxref("onerror")}} event handler has been configured to handle the {{event("error")}} event, that event handler will get called. This can happen in a number of situations, including:</p>
<ul>
<li>The {{htmlattrxref("src", "img")}} attribute is empty or <code>null</code>.</li>
<li>The specified <code>src</code> URL is the same as the URL of the page the user is currently on.</li>
<li>The specified image is corrupted in some way that prevents it from being loaded.</li>
<li>The specified image's metadata is corrupted in such a way that it's impossible to retrieve its dimensions, and no dimensions were specified in the <code><img></code> element's attributes.</li>
<li>The specified image is in a format not supported by the {{Glossary("user agent")}}.</li>
</ul>
<h2 id="範例">範例</h2>
<pre class="brush: js">var img1 = new Image(); // HTML5 Constructor
img1.src = 'image1.png';
img1.alt = 'alt';
document.body.appendChild(img1);
var img2 = document.createElement('img'); // use DOM <a href="http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/html/nsIDOMHTMLImageElement.idl">HTMLImageElement</a>
img2.src = 'image2.jpg';
img2.alt = 'alt text';
document.body.appendChild(img2);
// using first image in the document
alert(document.images[0].src);
</pre>
<h2 id="規範">規範</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
<tr>
<td>{{SpecName('Referrer Policy', '#referrer-policy-delivery-referrer-attribute', 'referrer attribute')}}</td>
<td>{{Spec2('Referrer Policy')}}</td>
<td>Added the <code>referrerPolicy</code> property.</td>
</tr>
<tr>
<td>{{SpecName("CSSOM View", "#excensions-to-the-htmlimageelement-interface", "Extensions to HTMLImageElement")}}</td>
<td>{{Spec2('CSSOM View')}}</td>
<td>Added the <code>x</code> and <code>y</code> properties.</td>
</tr>
<tr>
<td>{{SpecName('HTML WHATWG', "embedded-content.html#the-img-element", "HTMLImageElement")}}</td>
<td>{{Spec2('HTML WHATWG')}}</td>
<td>The following properties have been added: <code>srcset</code>, <code>currentSrc</code> and <code>sizes</code>.</td>
</tr>
<tr>
<td>{{SpecName('HTML5 W3C', "embedded-content-0.html#the-img-element", "HTMLImageElement")}}</td>
<td>{{Spec2('HTML5 W3C')}}</td>
<td>A constructor (with 2 optional parameters) has been added.<br>
The following properties are now obsolete: <code>name</code>, <code>border</code>, <code>align</code>, <code>hspace</code>, <code>vspace</code>, and <code>longdesc</code>.<br>
The following properties are now <code>unsigned long</code>, instead of <code>long</code>: <code>height</code>, and <code>width</code>.<br>
The following properties have been added: <code>crossorigin</code>, <code>naturalWidth</code>, <code>naturalHeight</code>, and <code>complete</code>.</td>
</tr>
<tr>
<td>{{SpecName('DOM2 HTML', 'html.html#ID-17701901', 'HTMLImgElement')}}</td>
<td>{{Spec2('DOM2 HTML')}}</td>
<td>The <code>lowSrc</code> property has been removed.<br>
The following properties are now <code>long</code>, instead of <code>DOMString</code>: <code>height</code>, <code>width</code>, <code>hspace</code>, and <code>vspace</code>.</td>
</tr>
<tr>
<td>{{SpecName('DOM1', 'level-one-html.html#ID-17701901', 'HTMLImgElement')}}</td>
<td>{{Spec2('DOM1')}}</td>
<td>Initial definition.</td>
</tr>
</tbody>
</table>
<h2 id="瀏覽器相容性">瀏覽器相容性</h2>
{{Compat("api.HTMLImageElement")}}
<h2 id="See_also">See also</h2>
<ul>
<li>The HTML element implementing this interface: {{HTMLElement("img")}}</li>
</ul>
|
