[go: up one dir, main page]

    1. 4.8 Embedded content
      1. 4.8.1 The picture element
      2. 4.8.2 The source element
      3. 4.8.3 The img element

4.8 Embedded content

4.8.1 The picture element

HTML element contains zero or more elements and one element to offer alternative versions of an image for different display/device scenarios.">Element/picture

Support in all current engines.

Firefox38+Safari9.1+Chrome38+
Opera?Edge79+
Edge (Legacy)13+Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

HTML element. It doesn't implement specific properties or methods.">HTMLPictureElement

Support in all current engines.

Firefox38+Safari9.1+Chrome38+
Opera?Edge79+
Edge (Legacy)13+Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?
Categories:
Flow content.
Phrasing content.
Embedded content.
Palpable content.
Contexts in which this element can be used:
Where embedded content is expected.
Content model:
Zero or more source elements, followed by one img element, optionally intermixed with script-supporting elements.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
Accessibility considerations:
For authors.
For implementers.
DOM interface:
[Exposed=Window]
interface HTMLPictureElement : HTMLElement {
  [HTMLConstructor] constructor();
};

The picture element is a container which provides multiple sources to its contained img element to allow authors to declaratively control or give hints to the user agent about which image resource to use, based on the screen pixel density, viewport size, image format, and other factors. It represents its children.

The picture element is somewhat different from the similar-looking video and audio elements. While all of them contain source elements, the source element's src attribute has no meaning when the element is nested within a picture element, and the resource selection algorithm is different. Also, the picture element itself does not display anything; it merely provides a context for its contained img element that enables it to choose from multiple URLs.

4.8.2 The source element

HTML element specifies multiple media resources for the , the

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera?Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

elements.">HTMLSourceElement

Support in all current engines.

Firefox3.5+Safari3.1+Chrome3+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+
Categories:
None.
Contexts in which this element can be used:
As a child of a picture element, before the img element.
As a child of a media element, before any flow content or track elements.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
type — Type of embedded resource
media — Applicable media
src (in audio or video) — Address of the resource
srcset (in picture) — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.
sizes (in picture) — Image sizes for different page layouts
width (in picture) — Horizontal dimension
height (in picture) — Vertical dimension
Accessibility considerations:
For authors.
For implementers.
DOM interface:
[Exposed=Window]
interface HTMLSourceElement : HTMLElement {
  [HTMLConstructor] constructor();

  [CEReactions] attribute USVString src;
  [CEReactions] attribute DOMString type;
  [CEReactions] attribute USVString srcset;
  [CEReactions] attribute DOMString sizes;
  [CEReactions] attribute DOMString media;
  [CEReactions] attribute unsigned long width;
  [CEReactions] attribute unsigned long height;
};

The source element allows authors to specify multiple alternative source sets for img elements or multiple alternative media resources for media elements. It does not represent anything on its own.

The type attribute may be present. If present, the value must be a valid MIME type string.

The media attribute may also be present. If present, the value must contain a valid media query list. The user agent will skip to the next source element if the value does not match the environment.

The media attribute is only evaluated once during the resource selection algorithm for media elements. In contrast, when using the picture element, the user agent will react to changes in the environment.

The remainder of the requirements depend on whether the parent is a picture element or a media element:

The source element's parent is a picture element

The srcset attribute must be present, and is a srcset attribute.

The srcset attribute contributes the image sources to the source set, if the source element is selected.

If the srcset attribute has any image candidate strings using a width descriptor, the sizes attribute may also be present. If, additionally, the following sibling img element does not allow auto-sizes, the sizes attribute must be present. The sizes attribute is a sizes attribute, which contributes the source size to the source set, if the source element is selected.

If the img element allows auto-sizes, then the sizes attribute can be omitted on previous sibling source elements. In such cases, it is equivalent to specifying auto.

The source element supports dimension attributes. The img element can use the width and height attributes of a source element, instead of those on the img element itself, to determine its rendered dimensions and aspect-ratio, as defined in the Rendering section.

The type attribute gives the type of the images in the source set, to allow the user agent to skip to the next source element if it does not support the given type.

If the type attribute is not specified, the user agent will not select a different source element if it finds that it does not support the image format after fetching it.

When a source element has a following sibling source element or img element with a srcset attribute specified, it must have at least one of the following:

The src attribute must not be present.

The source element's parent is a media element

The src attribute gives the URL of the media resource. The value must be a valid non-empty URL potentially surrounded by spaces. This attribute must be present.

The type attribute gives the type of the media resource, to help the user agent determine if it can play this media resource before fetching it. The codecs parameter, which certain MIME types define, might be necessary to specify exactly how the resource is encoded. [RFC6381]

Dynamically modifying a source element's src or type attribute when the element is already inserted in a video or audio element will have no effect. To change what is playing, just use the src attribute on the media element directly, possibly making use of the canPlayType() method to pick from amongst available resources. Generally, manipulating source elements manually after the document has been parsed is an unnecessarily complicated approach.

The following list shows some examples of how to use the codecs= MIME parameter in the type attribute.

H.264 Constrained baseline profile video (main and extended video compatible) level 3 and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
H.264 Extended profile video (baseline-compatible) level 3 and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="avc1.58A01E, mp4a.40.2"'>
H.264 Main profile video level 3 and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="avc1.4D401E, mp4a.40.2"'>
H.264 'High' profile video (incompatible with main, baseline, or extended profiles) level 3 and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="avc1.64001E, mp4a.40.2"'>
MPEG-4 Visual Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="mp4v.20.8, mp4a.40.2"'>
MPEG-4 Advanced Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container
<source src='video.mp4' type='video/mp4; codecs="mp4v.20.240, mp4a.40.2"'>
MPEG-4 Visual Simple Profile Level 0 video and AMR audio in 3GPP container
<source src='video.3gp' type='video/3gpp; codecs="mp4v.20.8, samr"'>
Theora video and Vorbis audio in Ogg container
<source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'>
Theora video and Speex audio in Ogg container
<source src='video.ogv' type='video/ogg; codecs="theora, speex"'>
Vorbis audio alone in Ogg container
<source src='audio.ogg' type='audio/ogg; codecs=vorbis'>
Speex audio alone in Ogg container
<source src='audio.spx' type='audio/ogg; codecs=speex'>
FLAC audio alone in Ogg container
<source src='audio.oga' type='audio/ogg; codecs=flac'>
Dirac video and Vorbis audio in Ogg container
<source src='video.ogv' type='video/ogg; codecs="dirac, vorbis"'>

The srcset and sizes attributes must not be present.

The source HTML element insertion steps, given insertedNode, are:

  1. If insertedNode's parent is a media element that has no src attribute and whose networkState has the value NETWORK_EMPTY, then invoke that media element's resource selection algorithm.

  2. If insertedNode's next sibling is an img element and its parent is a picture element, then, count this as a relevant mutation for the img element.

The source HTML element removing steps, given removedNode and oldParent, are:

  1. If removedNode's next sibling was an img element and oldParent is a picture element, then, count this as a relevant mutation for the img element.

The IDL attributes src, type, srcset, sizes and media must reflect the respective content attributes of the same name.

If the author isn't sure if user agents will all be able to render the media resources provided, the author can listen to the error event on the last source element and trigger fallback behavior:

<script>
 function fallback(video) {
   // replace <video> with its contents
   while (video.hasChildNodes()) {
     if (video.firstChild instanceof HTMLSourceElement)
       video.removeChild(video.firstChild);
     else
       video.parentNode.insertBefore(video.firstChild, video);
   }
   video.parentNode.removeChild(video);
 }
</script>
<video controls autoplay>
 <source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
 <source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'
         onerror="fallback(parentNode)">
 ...
</video>

4.8.3 The img element

HTML element embeds an image into the document.">Element/img

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera?Edge79+
Edge (Legacy)12+Internet ExplorerYes
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

element, providing the properties and methods used to manipulate image elements.">HTMLImageElement

Support in all current engines.

Firefox1+Safari1+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+Internet Explorer5.5+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+
Categories:
Flow content.
Phrasing content.
Embedded content.
Form-associated element.
If the element has a usemap attribute: Interactive content.
Palpable content.
Contexts in which this element can be used:
Where embedded content is expected.
As a child of a picture element, after all source elements.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
alt — Replacement text for use when images are not available
src — Address of the resource
srcset — Images to use in different situations, e.g., high-resolution displays, small monitors, etc.
sizes — Image sizes for different page layouts
crossorigin — How the element handles crossorigin requests
usemap — Name of image map to use
ismap — Whether the image is a server-side image map
width — Horizontal dimension
height — Vertical dimension
referrerpolicyReferrer policy for fetches initiated by the element
decoding — Decoding hint to use when processing this image for presentation
loading — Used when determining loading deferral
fetchpriority — Sets the priority for fetches initiated by the element
Accessibility considerations:
If the element has a non-empty alt attribute: for authors; for implementers.
Otherwise: for authors; for implementers.
DOM interface:
[Exposed=Window,
 LegacyFactoryFunction=Image(optional unsigned long width, optional unsigned long height)]
interface HTMLImageElement : HTMLElement {
  [HTMLConstructor] constructor();

  [CEReactions] attribute DOMString alt;
  [CEReactions] attribute USVString src;
  [CEReactions] attribute USVString srcset;
  [CEReactions] attribute DOMString sizes;
  [CEReactions] attribute DOMString? crossOrigin;
  [CEReactions] attribute DOMString useMap;
  [CEReactions] attribute boolean isMap;
  [CEReactions] attribute unsigned long width;
  [CEReactions] attribute unsigned long height;
  readonly attribute unsigned long naturalWidth;
  readonly attribute unsigned long naturalHeight;
  readonly attribute boolean complete;
  readonly attribute USVString currentSrc;
  [CEReactions] attribute DOMString referrerPolicy;
  [CEReactions] attribute DOMString decoding;
  [CEReactions] attribute DOMString loading;
  [CEReactions] attribute DOMString fetchPriority;

  Promise<undefined> decode();

  // also has obsolete members
};

An img element represents an image.

An img element has a dimension attribute source, initially set to the element itself.

element.">HTMLImageElement/src

Support in all current engines.

Firefox1+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer5.5+
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+

HTML element embeds an image into the document.">Element/img#attr-srcset

Support in all current engines.

Firefox38+Safari8+Chrome34+
Opera?Edge79+
Edge (Legacy)≤18+Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?

The image given by the src and srcset attributes, and any previous sibling source elements' srcset attributes if the parent is a picture element, is the embedded content; the value of the alt attribute provides equivalent content for those who cannot process images or who have image loading disabled (i.e. it is the img element's fallback content).

The requirements on the alt attribute's value are described in a separate section.

The src attribute must be present, and must contain a valid non-empty URL potentially surrounded by spaces referencing a non-interactive, optionally animated, image resource that is neither paged nor scripted.

The requirements above imply that images can be static bitmaps (e.g. PNGs, GIFs, JPEGs), single-page vector documents (single-page PDFs, XML files with an SVG document element), animated bitmaps (APNGs, animated GIFs), animated vector graphics (XML files with an SVG document element that use declarative SMIL animation), and so forth. However, these definitions preclude SVG files with script, multipage PDF files, interactive MNG files, HTML documents, plain text documents, and the like. [PNG] [GIF] [JPEG] [PDF] [XML] [APNG] [SVG] [MNG]

The srcset attribute may also be present, and is a srcset attribute.

The srcset attribute and the src attribute (if width descriptors are not used) contribute the image sources to the source set (if no source element was selected).

If the srcset attribute is present and has any image candidate strings using a width descriptor, the sizes attribute must also be present. If the srcset attribute is not specified, and the loading attribute is in the Lazy state, the sizes attribute may be specified with the value "auto" (ASCII case-insensitive). The sizes attribute is a sizes attribute, which contributes the source size to the source set (if no source element was selected).

An img element allows auto-sizes if:

, , ,