HTML5/the-canvas-element

canvas元素

分类：

流式内容。
段落式内容。
嵌入式内容

使用场景：

需要嵌入式内容处。

内容模型：

透明内容模型

允许的属性：

全局属性
width
height

DOM接口：

interface HTMLCanvasElement : HTMLElement { attribute DOMString width; attribute DOMString 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); };

canvas元素提供了一些与分辨率相关的位图画布处理脚本，可用于即时渲染图形、游戏图形或其他可视化图像。

如果有更适合使用的元素，创作者不应该在文档中使用canvas元素。例如，不适合使用canvas 元素来渲染一个页面标题：如果想要给标题增加图形化表现效果，那么应该先使用一些适合的元素（一般是h1），然后再使用CSS及支撑技术（如XBL）添加样式。

当创作者使用canvas 元素时，他们还必须提供一些内容，在向用户展示时它们与位图画布表达具有功能或用途。这些内容可能作为canvas 元素的内容。canvas 元素的内容（如果有）是指元素的回退内容（fallback content）。

在交互式可视化媒体中，如果启用了canvas 元素的脚本支持，而且还启用了canvas 元素的支持，那么canvas 元素表示由动态生成的图像构成的嵌入式内容。

在非交互式的静态可视化媒体中，如果canvas 元素之前已经绘制好（例如，如果页面已经在一个交互式可视化媒体中查看，现在已经打印，或者在页面布局过程中运行的脚本在该元素上绘图），那么canvas 元素会以当前图像和尺寸来表示嵌入的内容。否则，这个元素会转而显示它的回退内容。

在非可视化媒体以及禁用了canvas 元素脚本或者禁用canvas 元素支持的可视化媒体中，canvas 元素会转而显示它的回退内容。

当一个canvas元素展示嵌入的内容时，用户仍然可以聚焦（focus）canvas元素的起源内容（即回退内容）。当聚集于一个元素时，它就成为键盘交互事件的执行目标（即使元素本身是不可见的）。这使创作者能够实现利用键盘访问的交互canvas：创作者可以将交互式区域一一映射到回退内容中可聚焦的元素中。（聚集对鼠标交互事件没有影响。）[DOMEVENTS]

canvas 元素有两个控制坐标空间尺寸的属性：width 和height。这些属性的值必须是有效的非负整数。必须使用解析非负整数的规则的来获得它们的数字值。如果缺少一个属性，或者解析值时返回错误，那么它会使用默认值替代。width 属性的默认值是300，而height 属性默认值是150。

canvas 元素的实际尺寸与坐标空间尺寸相同，其数值是按CSS像素解析的。然而，元素的尺寸可以通过样式表进行任意设置。在渲染过程中，图像会进行缩放，以适应布局尺寸。

坐标空间的尺寸并不一定表示用户代理在内部或渲染时使用的实际位图尺寸。例如，在一些高清显示器中，用户代理可能在内部使用两个设备像素表示一个坐标空间单位的位图，这样渲染结果就会保证具有较高的质量。

在创建canvas 元素时，无论后面width 和height 属性被设置为什么值（修改为新值或者之前的值），位图及所有相关上下文都必须清除为初始状态，然后使用最新指定的坐标空间尺寸重新初始化。

当canvas初始化时，它的位图必须清除为透明黑色。

width 和height IDL属性必须反映具有相同名称的相应内容属性（具有相同默认值）。

下面的例子只画出一个正方形：

代码...

context = canvas.getContext(contextId [, ... ])

返回一个对象，它包含在canvas上绘图的API。第一个参数指定希望得到的API。后面是由该API处理的参数。

所定义的上下文清单请参见WHATWG Wiki CanvasContexts页面。[WHATWGWIKI]

如果指定的上下文ID不支持，或者canvas已经初始化为其他（不兼容）类型（例如，在获得一个“webgl”上下文之后再尝试获得一个“2d”上下文），那么它会返回null。

canvas 元素有一个主上下文（primary context），它是该元素获得的第一个上下文。在canvas 元素创建时，它不能拥有主上下文。

最常用的主上下文是HTML Canvas 2D Context。

canvas 元素的getContext(contextId, arg...)方法在调用必须执行以下步骤：

1. 方法是第一个参数必须是contextId 。
2. 如果contextId 不是用户代理提供的上下文名称，返回null，退出这些步骤。
   注：有一个例子是，用户代理在理论上是支持“webgl”3D上下文的，但是所在平台并没有OpenGL硬件支持，而且用户代理不包含OpenGL软件实现。尽管用户代理能够识别“webgl”名称，但是在这一步它会返回null，因为这个调用实际上不支持这种上下文。
3. 如果该元素拥有一个主上下文，而WHATWG Wiki CanvasContexts页面的上下文条目中不包含兼容上下文的contextId ，那么返回null，退出这些步骤。[WHATWGWIKI]
4. 如果这个元素没有主上下文，那么将该元素的主上下文指定为contextId。
5. 如果这个元素已经调用 getContext()方法处理过同一个contextId，那么返回上次调用得到的同一个对象，退出这些步骤。其他参数忽略。
6. 返回一个用contextId创建的新对象，具体类型按照 WHATWG Wiki CanvasContexts页面所列的contextId条目的规定。[WHATWGWIKI]

WHATWG Wiki CanvasContexts页面可能会注册新的上下文类型。[WHATWGWIKI]

任何人在任何时候都可以自由编辑WHATWG Wiki CanvasContexts页面，添加新的上下文类型。这些新的上下文类型必须指定以下信息：

关键词

返回新API定义的对象的contextID 值。

规范

指向上下文类型API正式规范的链接。它可能是Wiki上的另一个页面，或者一个外部页面的链接。如果这个类型没有正式的规范，那么可以先用一个非正式描述替代，直到正式的规范发布。

兼容性

兼容此上下文的上下文类型清单（例如，运行在相同的底层位图上）。这个清单必须是可传递且对称的；如果定义的一个上下文类型与其他类型兼容，那么它兼容的所有类型都必须与这个类型所兼容的全部类型相兼容。

供应商还可能使用“供应商名-上下文”的语法来定义实验性上下文，例如，moz-3d。这些上下文应该在WHATWG Wiki CanvasContexts页面注册。

url = canvas.toDataURL( [ type, ... ])

返回一个表示Canvas中图像的data: URL。

第一个参数（如果有），控制返回图像的类型（例如，PNG或JPEG）。默认值是image/png；如果指定类型不支持，那么也会使用这个默认类型。其他参数与这个具体类型相关，用来控制图像的生成方式，如下表所示。

如果要使用非“image/png”的类型，那么创作者可以通过检查返回的字符串是否由“data:image/png,”或“data:image/png;”开头，以此检查图像是否确定为所要求的格式。如果是，那么图像格式是PNG，因此请求的类型是不支持的。（唯一例外的情况是当canvas没有设置高度或宽度的时候，得到的应该只有“data:,”。）

canvas.toBlob(callback [, type, ... ])

创建一个Blob对象，表示一个包含Canvas图像的文件，并使用该对象的引用调用一个回调函数。

第二个参数（如果有），控制所返回图像的类型（例如，PNG或JPEG）。默认值是image/png；如果指定类型不支持，就使用默认值。其他参数与这个类型相关，用来控制图像的生成方式，如下表所示。

toDataURL()方法必须执行以下步骤：

1. 如果Canvas没有像素（例如，水平尺寸或垂直尺寸为0），那么返回字符串“data:,”，然后退出这些步骤。（这是最短的data: URL；它表示text/plain资源中的空字符串。）
2. 使file成为图像序列化的文件，使用方法的参数（如果有）作为参数。
3. 返回一个表示file的data: URL。[RFC2397]

toBlob()方法必须执行以下步骤：

1. 在第一个参数中传入回调函数（callback ）。
2. 在第二个参数中传入arguments ，如果它有参数，在后面添加它的参数。
3. 使用arguments传入表示图像序列化文件file 。
4. 返回，但是继续以异步方式执行这些步骤。
5. 如果callback 为null，那么退出这些步骤。
6. 将一个任务排队，使用一个表示文件的Blob对象作为参数，调用FileCallback回调函数。

当用户代理选择一些特定参数将图像序列化为文件，那么它会按第一个参数值指定的格式创建一个图像文件，或者在未指定参数的情况下使用PNG格式。[PNG]

如果 arguments 不为空，那么第一个值必须解释为一个MIME类型，以指定使用的格式。如果类型包含任何参数，那么它必须当作未提供进行处理。

例如，“image/png”表示要生成一个PNG图像，“image/jpeg”则表示要生成一个JPEG图像，而“image/svg+xml”表示要生成一个SVG图像（这很可能要求实现技术实际上保存足够的信息，才能够确保从canvas渲染一个SVG图像）。

用户代理必须支持PNG（“image/png”）。用户代理可能支持其他类型。如果用户代理不支持所请求的类型，那么它必须使用PNG格式创建这个文件。[PNG]

如果用户代理支持这种类型，那么它必须在创建之前将所提供的类型转换为ASCII小写字母。

对于不支持透明度通道的图像类型，序列化的图像必须使用source-over 操作将canvas图像组合到一个实黑色背景上。

如果arguments中的第一个参数指定的类型属于下表 width第一列所指定的类型之一，而且用户代理支持这种类型，那么后续参数（如果有）必须按照表中该行的第二列所述方式进行处理。

根据这些规则，如果一个参数可以按照在Web IDL规范中处理any类型参数的方式转换为一个IDL双精度浮点数，那么这个参数就是一个数字。[WEBIDL]

其他参数必须忽略，而且一定不能引起用户代理抛出异常。这个规范的后续版本将可能定义这些方法的其他参数，使创作者能够更小心地控制压缩设置、图像元数据等。

颜色空间和颜色校正

canvas元素安全性

如果一个原点的脚本可以访问另一个原点（不在同一个原点）的图像信息（例如，读取像素），那么就可能发生信息泄漏。

为了避免这个问题，canvas元素定义了一个标记，用来表示它们是否为干净原点（origin-clean）。所有canvas元素都必须先将它们的origin-clean 设置为true。如果发生以下情况，那么这个标记必须设置为false:

• 调用元素的2D上下文的drawImage()方法处理一个原点与canvas元素所在Document对象不同的HTMLImageElement 或HTMLVideoElement。
• 调用元素的2D上下文的drawImage()方法处理一个origin-clean 标记为false的HTMLCanvasElement。
• 元素的2D上下文的 fillStyle属性设置为一个 CanvasPattern对象，而它由一个在模式创建时原点与canvas元素所在Document对象不同的HTMLImageElement 或HTMLVideoElement 创建。
• 元素的2D上下文的fillStyle属性被设置为一个CanvasPattern对象，而它由一个在模式创建时origin-clean 标记为false的HTMLCanvasElement 创建。
• 元素的2D上下文的strokeStyle 属性被设置为一个CanvasPattern对象，而它由一个在模式创建时与canvas元素所在Document对象不同HTMLImageElement的HTMLVideoElement或创建。
• 元素的2D上下文的strokeStyle属性被设置为一个CanvasPattern对象，而它由一个在模式创建时origin-clean 标记为false的HTMLCanvasElement 创建。
• 使用一个原点与canvas元素所在Document对象不同的字体来调用元素的2D上下文的fillText()或strokeText()方法。（这种字体甚至不一定已经使用；问题关键在于这种字体是否被认为是一种字形图。）

如果canvas元素的origin-clean 标记为false，那么任何时候调用它的toDataURL()方法都会抛出一个SECURITY_ERR 异常。

如果canvas元素的origin-clean 标记为false，那么任何时候调用2D上下文getImageData()方法都会抛出一个SECURITY_ERR 异常。

如果canvas元素最终使用一种原点与canvas元素所在Document对象不同的字体，那么任何时候调用2D上下文的measureText()方法都会抛出一个SECURITY_ERR 异常。

注意：即使通过修改width 或height 属性来重置canvas，它的标记也不会重置。