CanvasRenderingContext2D - 为 <canvas> 元素的绘图表面提供 2D 渲染上下文

CanvasRenderingContext2D 接口是 Canvas API 的一部分，用于为 <canvas> 元素的绘图表面提供 2D 渲染上下文。它用于绘制形状，文本，图像和其他对象。

请参阅下方的接口属性和方法。 Canvas 教程也有更多的说明，实例和资源。

基本实例

<canvas id="my-house" width="300" height="300"></canvas>

要获取画布的 2D 渲染上下文，请在 <canvas> 元素，设置 '2d' 作为参数：

const canvas = document.getElementById('my-house');
const ctx = canvas.getContext('2d');

有了上下文，您就可以绘制任何喜欢的东西。此代码绘制了一个房子：

// 设定线宽
ctx.lineWidth = 10;

// 墙壁
ctx.strokeRect(75, 140, 150, 110);

// 门
ctx.fillRect(130, 190, 40, 60);

// 屋顶
ctx.beginPath();
ctx.moveTo(50, 140);
ctx.lineTo(150, 60);
ctx.lineTo(250, 140);
ctx.closePath();
ctx.stroke();

生成的图形如下所示：

<canvas id="my-house" width="300" height="300"></canvas>

<script>
const canvas = document.getElementById('my-house');
const ctx = canvas.getContext('2d');

// 设定线宽
ctx.lineWidth = 10;

// 墙壁
ctx.strokeRect(75, 140, 150, 110);

// 门
ctx.fillRect(130, 190, 40, 60);

// 屋顶
ctx.beginPath();
ctx.moveTo(50, 140);
ctx.lineTo(150, 60);
ctx.lineTo(250, 140);
ctx.closePath();
ctx.stroke();
</script>

尝试一下 »

参考

绘制矩形

有三种方法可以立即在画布上绘制矩形。

CanvasRenderingContext2D.clearRect()

将起始点 (x, y) 和尺寸 (width, height) 定义的矩形中的所有像素设置为透明黑色，从而擦除所有先前绘制的内容。

CanvasRenderingContext2D.fillRect()

在 (x, y) 位置绘制一个填充矩形，其大小由 width 和 height. 决定。

CanvasRenderingContext2D.strokeRect()

使用当前的笔触样式在画布上绘制一个矩形，该矩形的起点为 (x, y) ，宽度为 width，高度为 height。

绘图文字

以下方法绘制文本。另请参见 TextMetrics 对象以获取文本属性。

CanvasRenderingContext2D.fillText()

在给定的 (x, y) 位置绘制（填充）给定的文本。

CanvasRenderingContext2D.strokeText()

在给定的 (x, y) 位置绘制（描边）给定的文本。

CanvasRenderingContext2D.measureText()

返回一个 TextMetrics 对象。

线型

以下方法和属性控制线条的绘制方式。

CanvasRenderingContext2D.lineWidth

线宽。默认值为 1.0。

CanvasRenderingContext2D.lineCap

行尾的结尾类型。可能的值：butt（默认），round，square。

CanvasRenderingContext2D.lineJoin

定义两条线相交的角的类型。可能的值：round，bevel，miter（默认）。

CanvasRenderingContext2D.miterLimit

斜接极限比。默认值为 10。

CanvasRenderingContext2D.getLineDash()

返回包含偶数个非负数的当前行虚线图案数组。

CanvasRenderingContext2D.setLineDash()

设置当前线的虚线图案。

CanvasRenderingContext2D.lineDashOffset

指定在一行上从何处开始画虚线。

文字样式

以下属性控制文本的布局方式。

CanvasRenderingContext2D.font

字体设置。默认值为 10px sans-serif。

CanvasRenderingContext2D.textAlign

文本对齐设置。可能的值：start（默认），end，left，right，center`。

CanvasRenderingContext2D.textBaseline

基线对齐设置。可能的值：top，hanging，middle，alphabetic（默认值），ideographic，bottom。

CanvasRenderingContext2D.direction

方向。可能的值：ltr，rtl，inherit（默认值）。

填充和描边样式

填充样式用于形状内部的颜色和样式，笔画样式用于形状周围的线条。

CanvasRenderingContext2D.fillStyle

用于内部形状的颜色或样式。默认值 #000（黑色）。

CanvasRenderingContext2D.strokeStyle

用于形状周围线条的颜色或样式。默认值 #000（黑色）。

渐变和图案

CanvasRenderingContext2D.createLinearGradient()

沿着由参数表示的坐标所给定的直线创建线性渐变。

CanvasRenderingContext2D.createRadialGradient()

创建由参数表示的两个圆的坐标给定的径向渐变。

CanvasRenderingContext2D.createPattern()

使用指定的图像（CanvasImageSource）创建图案。它按照重复参数指定的方向重复源。此方法返回一个 CanvasPattern。

阴影

CanvasRenderingContext2D.shadowBlur

指定模糊效果。默认值：0。

CanvasRenderingContext2D.shadowColor

阴影的颜色。默认值：全透明黑色。

CanvasRenderingContext2D.shadowOffsetX

阴影将偏移的水平距离。默认值：0。

CanvasRenderingContext2D.shadowOffsetY

阴影要被偏移的垂直距离。默认值：0。

路径

可以使用以下方法来操纵对象的路径。

CanvasRenderingContext2D.beginPath()

通过清空子路径列表来开始新路径。要创建新路径时，请调用此方法。

CanvasRenderingContext2D.closePath()

使笔尖移回当前子路径的起点。它试图从当前点到起点画一条直线。如果形状已经闭合或只有一个点，则此功能不执行任何操作。

CanvasRenderingContext2D.moveTo()

将新子路径的起点移动到 (x, y) 坐标。

CanvasRenderingContext2D.lineTo()

用一条直线将当前子路径中的最后一个点连接到指定的 (x, y) 坐标。

CanvasRenderingContext2D.bezierCurveTo()

将三次贝塞尔曲线添加到当前路径。

CanvasRenderingContext2D.quadraticCurveTo()

将二次贝塞尔曲线添加到当前路径。

CanvasRenderingContext2D.arc()

将圆弧添加到当前路径。

CanvasRenderingContext2D.arcTo()

将具有给定控制点和半径的圆弧添加到当前路径，并通过一条直线将其连接到上一个点。

CanvasRenderingContext2D.ellipse()

将椭圆弧添加到当前路径。

CanvasRenderingContext2D.rect()

为矩形位置 (x, y) 创建一个路径，该路径的大小由 width 和 height 确定。

绘制路径

CanvasRenderingContext2D.fill()

使用当前的填充样式填充当前的子路径。

CanvasRenderingContext2D.stroke()

使用当前笔触样式描边当前子路径。

CanvasRenderingContext2D.drawFocusIfNeeded()

如果给定的元素被聚焦，此方法将在当前路径周围绘制一个焦点环。

CanvasRenderingContext2D.scrollPathIntoView()

将当前路径或给定路径滚动到视图中。

CanvasRenderingContext2D.clip()

从当前子路径创建剪切路径。调用 clip() 之后绘制的所有内容仅出现在剪切路径内。有关实例，请参见 Canvas 教程中的剪切路径。

CanvasRenderingContext2D.isPointInPath()

报告指定的点是否包含在当前路径中。

CanvasRenderingContext2D.isPointInStroke()

报告指定点是否在笔触所包含的区域之内。

转换

CanvasRenderingContext2D 渲染上下文中的对象具有当前的转换矩阵和对其进行操作的方法。创建当前默认路径，绘制文本，形状和 Path2D 对象时，将应用转换矩阵。出于历史和兼容性的原因，下面列出的方法仍然保留，因为 SVGMatrix 对象如今在 API 的大多数部分中都已使用，并将在以后使用。

CanvasRenderingContext2D.currentTransform

当前转换矩阵（SVGMatrix 对象）。

CanvasRenderingContext2D.getTransform

检索应用于上下文的当前转换矩阵。

CanvasRenderingContext2D.rotate()

向变换矩阵添加旋转。角度自变量表示顺时针旋转角度，以弧度表示。

CanvasRenderingContext2D.scale()

通过水平 x 和垂直 y 向画布单位添加缩放变换。

CanvasRenderingContext2D.translate()

通过在画布上水平移动画布及其原点 x 和垂直 y 来添加平移变换。

CanvasRenderingContext2D.transform()

将当前变换矩阵与其参数描述的矩阵相乘。

CanvasRenderingContext2D.setTransform()

将当前转换重置为单位矩阵，然后使用相同的参数调用 transform() 方法。

CanvasRenderingContext2D.resetTransform()

通过单位矩阵重置当前变换。

合成

CanvasRenderingContext2D.globalAlpha

在将形状和图像合成到画布之前应用于其的 Alpha 值。默认值为 1.0（不透明）。

CanvasRenderingContext2D.globalCompositeOperation

应用 globalAlpha，可以设置如何在现有位图上绘制形状和图像。

绘图图像

CanvasRenderingContext2D.drawImage()

绘制指定的图像。该方法有多种格式，在使用中提供了很大的灵活性。

像素操控

另请参见 ImageData 对象。

CanvasRenderingContext2D.createImageData()

用指定的尺寸创建一个新的空白 ImageData 对象。新对象中的所有像素均为透明黑色。

CanvasRenderingContext2D.getImageData()

返回一个 ImageData 对象，该对象表示从 (sx，sy) 开始并且宽度为 sw，高度为 sh 的矩形表示的画布区域的基础像素数据。

CanvasRenderingContext2D.putImageData()

将给定的 ImageData 对象中的数据绘制到位图上。如果提供了脏矩形，则仅绘制该矩形中的像素。

图像平滑

CanvasRenderingContext2D.imageSmoothingEnabled

图像平滑模式；如果禁用，缩放后图像将不会平滑。

CanvasRenderingContext2D.imageSmoothingQuality

允许您设置图像平滑的质量。

画布状态

CanvasRenderingContext2D 渲染上下文包含各种绘图样式状态（线型，填充样式，阴影样式，文本样式的属性）。以下方法可帮助您使用该状态：

CanvasRenderingContext2D.save()

使用堆栈保存当前的图形样式状态，以便您可以使用 restore() 恢复对其所做的任何更改。

CanvasRenderingContext2D.restore()

将绘图样式状态恢复到由 save() 保存的 “状态堆栈” 中的最后一个元素。

CanvasRenderingContext2D.canvas

对 HTMLCanvasElement 的只读反向引用。如果它不与 <canvas> 元素相关联，则可能是 null。

点击区域

CanvasRenderingContext2D.addHitRegion()

向画布添加一个点击区域。

CanvasRenderingContext2D.removeHitRegion()

从画布中删除具有指定 id 的匹配区域。

CanvasRenderingContext2D.clearHitRegions()

从画布上删除所有点击区域。

滤镜

CanvasRenderingContext2D.filter

将 CSS 或 SVG 滤镜应用于画布，例如以更改其亮度或模糊度。

非标准 API

Blink 和 WebKit

这些 API 中的大多数都已不推荐使用，并在 Chrome 36 之后不久被删除。

CanvasRenderingContext2D.clearShadow()

删除所有阴影设置，例如 CanvasRenderingContext2D.shadowColor 和 CanvasRenderingContext2D.shadowBlur。

CanvasRenderingContext2D.drawImageFromRect()

它与 drawImage 相同。

CanvasRenderingContext2D.setAlpha()

请改用 CanvasRenderingContext2D.globalAlpha。

CanvasRenderingContext2D.setCompositeOperation()

请改用 CanvasRenderingContext2D.globalCompositeOperation。

CanvasRenderingContext2D.setLineWidth()

请改用 CanvasRenderingContext2D.lineWidth。

CanvasRenderingContext2D.setLineJoin()

请改用 CanvasRenderingContext2D.lineJoin。

CanvasRenderingContext2D.setLineCap()

请改用 CanvasRenderingContext2D.lineCap。

CanvasRenderingContext2D.setMiterLimit()

请改用 CanvasRenderingContext2D.miterLimit。

CanvasRenderingContext2D.setStrokeColor()

请改用 CanvasRenderingContext2D.strokeStyle。

CanvasRenderingContext2D.setFillColor()

请改用 CanvasRenderingContext2D.fillStyle。

CanvasRenderingContext2D.setShadow()

请改用 CanvasRenderingContext2D.shadowColor 和 CanvasRenderingContext2D.shadowBlur。

CanvasRenderingContext2D.webkitLineDash

请改用 CanvasRenderingContext2D.getLineDash() 和 CanvasRenderingContext2D.setLineDash()。

CanvasRenderingContext2D.webkitLineDashOffset

请改用 CanvasRenderingContext2D.lineDashOffset。

CanvasRenderingContext2D.webkitImageSmoothingEnabled

请改用 CanvasRenderingContext2D.imageSmoothingEnabled。

Blink 特有

CanvasRenderingContext2D.isContextLost()

受到相同的 WebGLRenderingContext 方法的启发。如果画布上下文丢失，则返回 true；否则返回 false。

WebKit 特有

CanvasRenderingContext2D.webkitBackingStorePixelRatio

与 canvas 元素相关的后备存储大小。请参阅高 DPI 画布。

CanvasRenderingContext2D.webkitGetImageDataHD

适用于 HD 后备存储，但已从画布规范中删除。

CanvasRenderingContext2D.webkitPutImageDataHD

适用于 HD 后备存储，但已从画布规范中删除。

Gecko 特有

包含前缀的 API

CanvasRenderingContext2D.mozCurrentTransform

设置或获取当前的转换矩阵，请参见 CanvasRenderingContext2D.currentTransform。

CanvasRenderingContext2D.mozCurrentTransformInverse

设置或获取当前逆变换矩阵。

CanvasRenderingContext2D.mozImageSmoothingEnabled

请参阅 CanvasRenderingContext2D.imageSmoothingEnabled。

CanvasRenderingContext2D.mozTextStyle

在 Gecko 1.9 中引入，已被弃用，取而代之的是 CanvasRenderingContext2D.font 属性。

CanvasRenderingContext2D.mozDrawText()

该方法在 Gecko 1.9 中引入，从 Gecko 7.0 开始被删除。请使用 CanvasRenderingContext2D.strokeText() 或 CanvasRenderingContext2D.fillText()。

CanvasRenderingContext2D.mozMeasureText()

该方法在 Gecko 1.9 中引入，从 Gecko 7.0 开始变为未实现。请使用 CanvasRenderingContext2D.measureText()。

CanvasRenderingContext2D.mozPathText()

该方法在 Gecko 1.9 中引入，从 Gecko 7.0 开始被删除。

CanvasRenderingContext2D.mozTextAlongPath()

该方法在 Gecko 1.9 中引入，从 Gecko 7.0 开始被删除。

内部 API（仅适用于 chrome-context）

CanvasRenderingContext2D.drawWindow()

将窗口的区域渲染到 canvas 中。呈现窗口视口的内容，而忽略视口剪辑和滚动。

CanvasRenderingContext2D.demote()

它将导致当前使用硬件加速后端的上下文回退到软件后端。所有状态都应保留。

Internet Explorer

CanvasRenderingContext2D.msFillRule

要使用的填充规则。它必须是 evenodd 或 nonzero（默认值）之一。

规范

规范	状态	备注
HTML Living Standard CanvasRenderingContext2D 的定义	现行的标准	-

桌面浏览器兼容性

移动浏览器兼容性

1. 参见 bug 928150。Firefox 还支持实验性属性和前缀属性 mozCurrentTransform 和 mozCurrentTransformInverse，用于设置或获取当前（逆向）转换矩阵。

2. 参见 webkitbug（174278）。

3. 通过 drawSystemFocusRing 支持。

4. 从 Firefox 5 开始， getImageData 现在可以正确地接受超出画布边界的矩形了。画布外部的像素将返回为透明黑色，如果指定了小于一个像素的矩形，则现在还将返回至少一个像素的图像数据。

5. 通过 mozDashOffset 支持。

相关链接

• HTMLCanvasElement
• <canvas>