canvas
elementwidth
height
interface HTMLCanvasElement : HTMLElement {
attribute unsigned long width;
attribute unsigned long height;
DOMString toDataURL(in optional DOMString type, in any... args);
void toBlob(in FileCallback, in optional DOMString type, in any... args);
object getContext(in DOMString contextId, in 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 initialised 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] |