Copyright © 2020 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This document defines the concept of an "image resource" and a
corresponding WebIDL
dictionary. Web APIs can use the
ImageResource
dictionary to represent an image resource in contexts
where an ImageResource
HTMLImageElement
is not suitable or available (e.g., in a
Worker).
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This specification is not stable. Implementors who are not taking part in the discussions will find the specification changing out from under them in incompatible ways.
This document was published by the Web Applications Working Group as a Working Draft. This document is intended to become a W3C Recommendation.
GitHub Issues are preferred for discussion of this specification.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2019 W3C Process Document.
Web applications often accept developer-provided image resources to be displayed outside of a HTML document (e.g., in the OS, in the browser UI, etc.). This specification defines a WebIDL dictionary that describes an image, and where that image resource can be fetched from. The user agent can then use this extra information to choose an image that is best suited to display on the end-user's device or most closely matches the end-user's preferences or environment.
An image resource consists of:
link
's sizes
attribute.
In an API, this is represented as an
dictionary.
ImageResource
ImageResource
dictionary
WebIDLdictionaryImageResource
{ required USVStringsrc
; DOMStringsizes
; DOMStringtype
; };
src
member
The
of an src
is a URL from
which a user agent can fetch image data.
ImageResource
sizes
member
The
member is equivalent to a sizes
link
element's sizes
attribute, and is processed in the same
manner.
When multiple
dictionaries are available, a user
agent MAY use the ImageResource
value to decide which image
is most suitable for a display context (and ignore any that are
inappropriate).
sizes
sizes
member allows for multiple
space-separated size values in order to accommodate image formats
(such as ICO) that can act as a container for multiple images of
varying dimensions.
const image = {
src: "path/to/image.ico",
sizes: "16x16 32x32 64x64",
type: "image/vnd.microsoft.icon",
};
some.api.doSomething(image);
type
member
The
member represents an image MIME Type
for the image resource. A user agent MAY ignore media types it does
not support.
type
There is no default MIME type for an
. The
ImageResource
is purely advisory. User agents MUST use the
rules for sniffing images specifically to determine the
computed MIME type of an image resource.
type
ImageResource
from an API
The steps to process an ImageResource
from an
API are given by the following algorithm. The algorithm takes an
input. It returns an image
resource.
ImageResource
src
and base URL. If
parsing the URL fails, throw a TypeError
.
sizes
member is present:
type
member is present and not the
empty string:
type
is not an image MIME Type, throw
a TypeError
.
type
.
The steps to process an image resource from JSON are given by the following algorithm. The algorithm takes a JSON Object input and a URL base URL. It returns an image resource.
The steps for fetching an image resource are given by the following algorithm. The algorithm takes an image resource image, and an optional Request request. It returns a Response.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY and MUST in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.