canvas
elementwidth
height
interface HTMLCanvasElement : HTMLElement { attribute unsigned long width; attribute unsigned long height; DOMString toDataURL(optional DOMString type, any... args); void toBlob(FileCallback? _callback, optional DOMString type, any... args); object? getContext(DOMString contextId, any... args); };
The canvas
element provides scripts with a
resolution-dependent bitmap canvas, which can be used for rendering
graphs, game graphics, or other visual images on the fly.
Authors should not use the canvas
element in a
document when a more suitable element is available. For example, it
is inappropriate to use a canvas
element to render a
page heading: if the desired presentation of the heading is
graphically intense, it should be marked up using appropriate
elements (typically h1
) and then styled using CSS and
supporting technologies such as XBL.
When authors use the canvas
element, they must also
provide content that, when presented to the user, conveys
essentially the same function or purpose as the bitmap canvas. This
content may be placed as content of the canvas
element. The contents of the canvas
element, if any,
are the element's fallback content.
In interactive visual media, if scripting is enabled for the
canvas
element, and if support for canvas
elements has been enabled, the canvas
element
represents embedded content consisting of
a dynamically created image.
In non-interactive, static, visual media, if the
canvas
element has been previously painted on (e.g. if
the page was viewed in an interactive visual medium and is now being
printed, or if some script that ran during the page layout process
painted on the element), then the canvas
element
represents embedded content with the
current image and size. Otherwise, the element represents its
fallback content instead.
In non-visual media, and in visual media if scripting is disabled for the
canvas
element or if support for canvas
elements has been disabled, the canvas
element
represents its fallback content
instead.
When a canvas
element represents
embedded content, the user can still focus descendants
of the canvas
element (in the fallback
content). When an element is focused, it is the target of
keyboard interaction events (even though the element itself is not
visible). This allows authors to make an interactive canvas
keyboard-accessible: authors should have a one-to-one mapping of
interactive regions to focusable elements in the fallback
content. (Focus has no effect on mouse interaction
events.) [DOMEVENTS]
The canvas
element has two attributes to control the
size of the coordinate space: width
and height
. These
attributes, when specified, must have values that are valid non-negative
integers. The
width
attribute defaults to
300, and the height
attribute defaults to 150.
The intrinsic dimensions of the canvas
element equal
the size of the coordinate space, with the numbers interpreted in
CSS pixels. However, the element can be sized arbitrarily by a
style sheet. During rendering, the image is scaled to fit this layout
size.
The width
and
height
IDL
attributes must reflect the respective content
attributes of the same name, with the same defaults.
Only one square appears to be drawn in the following example:
// canvas is a reference to a <canvas> element var context = canvas.getContext('2d'); context.fillRect(0,0,50,50); canvas.setAttribute('width', '300'); // clears the canvas context.fillRect(0,100,50,50); canvas.width = canvas.width; // clears the canvas context.fillRect(100,0,50,50); // only this square remains
getContext
(contextId [, ... ])Returns an object that exposes an API for drawing on the canvas. The first argument specifies the desired API. Subsequent arguments are handled by that API.
The list of defined contexts is given on the WHATWG Wiki CanvasContexts page. [WHATWGWIKI]
Returns null if the given context ID is not supported or if the
canvas has already been initialized with some other (incompatible)
context type (e.g. trying to get a "2d
" context after getting a
"webgl
" context).
toDataURL
( [ type, ... ])Returns a data:
URL for the image in the canvas.
The first argument, if provided, controls the type of the image
to be returned (e.g. PNG or JPEG). The default is image/png
; that type is also used if the given
type isn't supported. The other arguments are specific to the
type, and control the way that the image is generated, as given in
the table below.
When trying to use types other than "image/png
",
authors can check if the image was really returned in the
requested format by checking to see if the returned string starts
with one of the exact strings "data:image/png,
" or "data:image/png;
". If it does, the image is PNG,
and thus the requested type was not supported. (The one exception
to this is if the canvas has either no height or no width, in
which case the result might simply be "data:,
".)
toBlob
(callback [, type, ... ])Creates a Blob
object representing a file
containing the image in the canvas, and invokes a callback with a
handle to that object.
The second argument, if provided, controls the type of the
image to be returned (e.g. PNG or JPEG). The default is image/png
; that type is also used if the given
type isn't supported. The other arguments are specific to the
type, and control the way that the image is generated, as given in
the table below.
Type | Other arguments | Reference |
---|---|---|
image/jpeg
| The second argument is a number in the range 0.0 to 1.0 inclusive treated as the desired quality level. | [JPEG] |