canvas
elementwidth
height
interface HTMLCanvasElement : HTMLElement { attribute unsigned long width; attribute unsigned long height; DOMString toDataURL(optional DOMString type, any... arguments); DOMString toDataURLHD(optional DOMString type, any... arguments); void toBlob(FileCallback? _callback, optional DOMString type, any... arguments); void toBlobHD(FileCallback? _callback, optional DOMString type, any... arguments); object? getContext(DOMString contextId, any... arguments); };
The canvas
element provides scripts with a resolution-dependent bitmap canvas,
which can be used for rendering graphs, game graphics, art, 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.
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] |