原生HTML5 Canvas 参考API文档

说明

本篇内容可以看做是一篇关于canvas的API文档，由于全文的篇幅较长，通常用于作为API文档查看，可通过目录查找。本篇也可做为想详细了解canvas所有操作的学习文章。Canvas 对象表示一个 HTML 画布元素<canvas>。它没有自己的行为，但是定义了一个 API 支持脚本化绘图操作。我们可以直接在该对象上指定宽度和高度，但是，其大多数功能都可以通过 CanvasRenderingContext2D 对象获得。例如：

<canvas id="myCanvas" width="400" height="400"></canvas><script>var c = document.getElementById("myCanvas");var ctx = c.getContext("2d");console.log(ctx); // CanvasRenderingContext2D对象console.log(c.width); // 400console.log(c.height); // 400</script>

<canvas> 标记和 SVG 以及 VML 之间的一个重要的不同是，<canvas> 有一个基于 JavaScript 的绘图 API，而 SVG 和 VML 使用一个 XML 文档来描述绘图。这两种方式在功能上是等同的，任何一种都可以用另一种来模拟。从表面上看，它们很不相同，可是，每一种都有强项和弱点。例如，SVG 绘图很容易编辑，只要从其描述中移除元素就行。要从同一图形的一个 <canvas> 标记中移除元素，往往需要擦掉绘图重新绘制它。

Canvas对象的API详解

1.样式设置 fillStyle | strokeStyle 

指设置将要绘制图案的填充或边的样式

属性描述fillStyle设置或返回用于填充绘画的颜色、渐变或模式strokeStyle设置或返回用于笔触的颜色、渐变或模式

fillStyle、strokeStyle 属性设置或返回用于填充绘画的颜色、渐变或模式。

默认值：#000000JavaScript 语法：context.fillStyle=color|gradient|pattern;

默认值：#000000JavaScript 语法：context.strokeStyle=color|gradient|pattern;属性值：
值描述color指示绘图笔触颜色的 CSS 颜色值。默认值是 #000000。gradient用于填充绘图的渐变对象（线性或放射性）pattern用于创建 pattern 笔触的 pattern 对象

CSS颜色的表示方式有：

——直接用颜色名称:"red" "green" "blue"；

——十六进制颜色值: "#EEEEFF"；

——rgb(1-255,1-255,1-255)；

——rgba(1-255,1-255,1-255,透明度)；

常与设置样式配合使用的方法是：填充绘制和边绘制。

方法描述fill()填充当前绘图（路径）stroke()绘制已定义的路径如绘制一个蓝色的矩形，如：

ctx.fillStyle = "#0000ff";ctx.rect(20, 20, 150, 100);ctx.fill();

半透明的蓝色矩形，如：

ctx.fillStyle = "rgba(0, 0, 255, 0.5)";

2.形状设置

形状设置包括了矩形、圆形和贝塞尔曲线。

方法描述rect()创建矩形fillRect()绘制“被填充”的矩形strokeRect()绘制矩形（无填充）clearRect()在给定的矩形内清除指定的像素quadraticCurveTo()创建二次贝塞尔曲线bezierCurveTo()创建三次方贝塞尔曲线arc()创建弧/曲线（用于创建圆形或部分圆）arcTo()创建两切线之间的弧/曲线

矩形 rect（） | fillRect（） | strokeRect（） | clearRect（）

相关JavaScript语法：

context.rect(x,y,width,height);

context.fillRect(x,y,width,height);

context.strokeRect(x,y,width,height);

context.clearRect(x,y,width,height);

属性值：

参数描述x矩形左上角的 x 坐标y矩形左上角的 y 坐标width矩形的宽度，以像素计height矩形的高度，以像素计通过 rect() 方法来创建三个矩形，

源码：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");// 红色矩形ctx.beginPath();ctx.lineWidth="6";ctx.strokeStyle="red";ctx.rect(5,5,290,140);ctx.stroke();// 绿色矩形ctx.beginPath();ctx.lineWidth="4";ctx.strokeStyle="green";ctx.rect(30,30,50,50);ctx.stroke();// 蓝色矩形ctx.beginPath();ctx.lineWidth="10";ctx.strokeStyle="blue";ctx.rect(50,50,150,80);ctx.stroke();

（注）方法beginPath（）的作用在于从新的路径（或新起点）开始绘制图案，简单来说新图案的绘制过程不受画布已有图案影响。

圆形 arc（）

JavaScript语法：

context.arc(x,y,r,sAngle,eAngle,counterclockwise);

属性值：

参数描述x圆的中心的 x 坐标。y圆的中心的 y 坐标。r圆的半径。sAngle起始角，以弧度计。（弧的圆形的三点钟位置是 0 度）。eAngle结束角，以弧度计。counterclockwise可选。规定应该逆时针还是顺时针绘图。False = 顺时针(默认)，true = 逆时针。（提示）：如需通过 arc() 来创建圆，请把起始角设置为 0，结束角设置为 2*Math.PI。
（提示）：请使用 stroke() 或 fill() 方法在画布上绘制实际的弧。

绘制一个圆形：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.beginPath();ctx.arc(100,75,50,0,2*Math.PI);ctx.stroke();

弧 arcTo（）

在画布上创建介于两个切线之间的弧的JavaScript语法：

context.arcTo(x1,y1,x2,y2,r);

属性值：

参数描述x1弧的起点的 x 坐标y1弧的起点的 y 坐标x2弧的终点的 x 坐标y2弧的终点的 y 坐标r弧的半径绘制一道两切线间的弧：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.beginPath();ctx.beginPath();ctx.moveTo(20,20);           // 创建开始点ctx.lineTo(100,20);          // 创建水平线ctx.arcTo(150,20,150,70,50); // 创建弧ctx.lineTo(150,120);         // 创建垂直线ctx.stroke();                // 进行绘制

二次贝塞尔曲线 quadraticCurveTo（）

JavaScript语法：

context.quadraticCurveTo(cpx,cpy,x,y);

属性值：

参数描述cpx贝塞尔控制点的 x 坐标cpy贝塞尔控制点的 y 坐标x结束点的 x 坐标y结束点的 y 坐标（提示）：二次贝塞尔曲线需要两个点。第一个点是用于二次贝塞尔计算中的控制点，第二个点是曲线的结束点。曲线的开始点是当前路径中最后一个点。如果路径不存在，那么请使用 beginPath() 和 moveTo() 方法来定义开始点。

绘制一条二次贝塞尔曲线：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.beginPath();ctx.moveTo(20,20);ctx.quadraticCurveTo(20,100,200,20);ctx.stroke();

三次贝塞尔曲线 bezierCurveTo（）

JavaScript语法：

context.bezierCurveTo(cp1x,cp1y,cp2x,cp2y,x,y);

属性值：

cp1x第一个贝塞尔控制点的 x 坐标cp1y第一个贝塞尔控制点的 y 坐标cp2x第二个贝塞尔控制点的 x 坐标cp2y第二个贝塞尔控制点的 y 坐标x结束点的 x 坐标y结束点的 y 坐标（提示）：三次贝塞尔曲线需要三个点。前两个点是用于三次贝塞尔计算中的控制点，第三个点是曲线的结束点。曲线的开始点是当前路径中最后一个点。如果路径不存在，那么请使用 beginPath() 和 moveTo() 方法来定义开始点。

绘制一条三次贝塞尔曲线：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.beginPath();ctx.moveTo(20,20);ctx.bezierCurveTo(20,100,200,100,200,20);ctx.stroke();

3.线条和路径设置

方法描述lineCap设置或返回线条的结束端点样式lineJoin设置或返回两条线相交时，所创建的拐角类型lineWidth设置或返回当前的线条宽度miterLimit设置或返回最大斜接长度beginPath()起始一条路径，或重置当前路径closePath()创建从当前点回到起始点的路径moveTo()把路径移动到画布中的指定点，不创建线条lineTo()添加一个新点，然后在画布中创建从该点到最后指定点的线条

结束线帽lineCap

指设置绘制圆形的结束线帽：
默认值：buttJavaScript 语法：context.lineCap="butt|round|square"; // 平直边缘 | 圆形线帽 | 方形线帽绘制一条结束点为圆形线帽的直线：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.beginPath();ctx.lineCap="round";ctx.moveTo(20,20);ctx.lineTo(20,200);ctx.stroke();

拐角类型lineJoin

两线相交点拐角的类型。当类型值为miter时，常与miterLimit一起使用。因为当两线夹角越小时，miter尖角会越长，miterLimit用于控制尖角的长度。

默认值：miterJavaScript 语法：context.lineJoin="bevel|round|miter"; // 斜角 | 圆角 | 尖角以最大斜接长度 5 绘制线条：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.lineWidth=10;ctx.lineJoin="miter";ctx.miterLimit=5;ctx.moveTo(20,20);ctx.lineTo(50,27);ctx.lineTo(20,34);ctx.stroke();

（提示）：只有当 lineJoin 属性为 "miter" 时，miterLimit 才有效。如果斜接长度超过 miterLimit 的值，边角会以 lineJoin 的 "bevel" 类型来显示（图解 3）：

beginPath( ) | closePath( )

beginPath（）可以理解为从新的路径（或新起点）开始绘制图案，简单来说新图案的绘制过程不受画布已有图案影响。如不设置beginPath（），多次绘制时，已有图案会受到新图案的绘制样式影响。closePath( )是指闭合路径，即从当前笔触点至最开始的笔触起始点创建连接直线，形成闭合。

绘制闭合三角形：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.beginPath();ctx.moveTo(20,20);ctx.lineTo(20,100);ctx.lineTo(70,100);ctx.closePath();ctx.stroke();ctx.fillStyle="green";ctx.fill();

moveTo( ) | lineTo( )

 moveTo（）是指将笔触移动到指定坐标点，lineTo是指从当前笔触坐标点往指定坐标点绘制一条直线。

开始一条路径，移动到位置 0,0。创建到达位置 300,150 的一条线：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.beginPath();ctx.moveTo(0,0);ctx.lineTo(300,150);ctx.stroke();

4.文本设置

包括文本样式设置和创建。

属性描述font设置或返回文本内容的当前字体属性textAlign设置或返回文本内容的当前对齐方式textBaseline设置或返回在绘制文本时使用的当前文本基线方法描述fillText()在画布上绘制“被填充的”文本strokeText()在画布上绘制文本（无填充）measureText()返回包含指定文本宽度的对象

文本样式font

默认值：10px sans-serifJavaScript 语法：context.font="italic small-caps bold 12px arial";属性值：

值描述font-style

规定字体样式。可能的值：

• normal
• italic
• oblique

font-variant

规定字体变体。可能的值：

• normal
• small-caps

font-weight

规定字体的粗细。可能的值：

• normal
• bold
• bolder
• lighter
• 100
• 200
• 300
• 400
• 500
• 600
• 700
• 800
• 900

font-size / line-height规定字号和行高，以像素计。font-family规定字体系列。在画布上写一段 40 像素的文本，使用的字体是 "Arial"：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.font="40px Arial";ctx.fillText("Hello World",10,50);

文本对齐textAlign

默认值：startJavaScript 语法：context.textAlign="center|end|left|right|start";属性值：

值描述start默认。文本在指定的位置开始。end文本在指定的位置结束。center文本的中心被放置在指定的位置。left文本左对齐。right文本右对齐。在位置 150 创建一条红线。位置 150 是下面例子中定义的所有文本的锚点。请研究每种 textAlign 属性值的效果：

var c = document.getElementById("myCanvas");var ctx = c.getContext("2d");// 在位置 150 创建蓝线ctx.strokeStyle = "blue";ctx.moveTo(150, 0);ctx.lineTo(150, 170);ctx.stroke();ctx.font = "15px Arial";// 显示不同的 textAlign 值ctx.textAlign = "start";ctx.fillText("textAlign=start", 150, 15); //起始位置为注册坐标ctx.textAlign = "end";ctx.fillText("textAlign=end", 150, 30); //结束位置为注册坐标ctx.textAlign = "left";ctx.fillText("textAlign=left", 150, 45); //居中对齐ctx.textAlign = "center";ctx.fillText("textAlign=center", 150, 60); //左对齐ctx.textAlign = "right";ctx.fillText("textAlign=right", 150, 75); //右对齐

文本基线textBaseLine

默认值：alphabeticJavaScript 语法：context.textBaseline="alphabetic|top|hanging|middle|ideographic|bottom";属性值：

值描述alphabetic默认。文本基线是普通的字母基线。top文本基线是 em 方框的顶端。。hanging文本基线是悬挂基线。middle文本基线是 em 方框的正中。ideographic文本基线是表意基线。bottom文本基线是 em 方框的底端。实例：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");//在位置 y=100 绘制蓝色线条ctx.strokeStyle="blue";ctx.moveTo(5,100);ctx.lineTo(395,100);ctx.stroke();ctx.font="20px Arial"//在 y=200 以不同的 textBaseline 值放置每个单词ctx.textBaseline="top";ctx.fillText("Top",5,100);ctx.textBaseline="bottom";ctx.fillText("Bottom",50,100);ctx.textBaseline="middle";ctx.fillText("Middle",120,100);ctx.textBaseline="alphabetic";ctx.fillText("Alphabetic",190,100);ctx.textBaseline="hanging";ctx.fillText("Hanging",290,100);

绘制文本fillText（） | strokeText（）

JavaScript 语法：

context.fillText(text,x,y,maxWidth);

context.strokeText(text,x,y,maxWidth);

属性值：

参数描述text规定在画布上输出的文本。x开始绘制文本的 x 坐标位置（相对于画布）。y开始绘制文本的 y 坐标位置（相对于画布）。maxWidth可选。允许的最大文本宽度，以像素计。使用 fillText()，在画布上写文本 "Hello world!" 和 "w3school.com.cn"：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.font="20px Georgia";ctx.fillText("Hello World!",10,50);ctx.font="30px Verdana";// 创建渐变var gradient=ctx.createLinearGradient(0,0,c.width,0);gradient.addColorStop("0","magenta");gradient.addColorStop("0.5","blue");gradient.addColorStop("1.0","red");// 用渐变填色ctx.fillStyle=gradient;ctx.fillText("w3school.com.cn",10,90);

测量文本宽度measureText()

JavaScript语法：

context.measureText(text).width;

5.变换设置

方法描述scale()缩放当前绘图至更大或更小rotate()旋转当前绘图translate()重新映射画布上的 (0,0) 位置transform()替换绘图的当前转换矩阵setTransform()将当前转换重置为单位矩阵。然后运行 transform()

缩放scale（） | 旋转rotate（） | 位移translate（）

JavaScript语法：

context.scale(scalewidth,scaleheight); //缩放

参数描述scalewidth缩放当前绘图的宽度 (1=100%, 0.5=50%, 2=200%, 依次类推)scaleheight缩放当前绘图的高度 (1=100%, 0.5=50%, 2=200%, etc.)

context.rotate(angle); //旋转

参数描述angle

旋转角度，以弧度计。

如需将角度转换为弧度，请使用 degrees*Math.PI/180 公式进行计算。

举例：如需旋转 5 度，可规定下面的公式：5*Math.PI/180。

context.translate(x,y); //位移

参数描述x添加到水平坐标（x）上的值y添加到垂直坐标（y）上的值

矩阵设置transform() | setTransform()

两者JavaScript语法相同，以transform为例：

context.transform(a,b,c,d,e,f);

属性值：

参数描述a水平缩放绘图b水平倾斜绘图c垂直倾斜绘图d垂直缩放绘图e水平移动绘图f垂直移动绘图区别：transform()变换是指在上一次变换的状态基础上再次变换；setTransform()变换是指先重置到最初始的状态再开始变换。

绘制一个矩形；通过 transform() 添加一个新的变换矩阵，再次绘制矩形；添加一个新的变换矩阵，然后再次绘制矩形。请注意，每当您调用 transform() 时，它都会在前一个变换矩阵上构建：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.fillStyle="yellow";ctx.fillRect(0,0,250,100)ctx.transform(1,0.5,-0.5,1,30,10);ctx.fillStyle="red";ctx.fillRect(0,0,250,100);ctx.transform(1,0.5,-0.5,1,30,10);ctx.fillStyle="blue";ctx.fillRect(0,0,250,100);

绘制一个矩形，通过 setTransform() 重置并创建新的变换矩阵，再次绘制矩形，重置并创建新的变换矩阵，然后再次绘制矩形。请注意，每当您调用 setTransform() 时，它都会重置前一个变换矩阵然后构建新的矩阵，因此在下面的例子中，不会显示红色矩形，因为它在蓝色矩形下面：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.fillStyle="yellow";ctx.fillRect(0,0,250,100)ctx.setTransform(1,0.5,-0.5,1,30,10);ctx.fillStyle="red";ctx.fillRect(0,0,250,100);ctx.setTransform(1,0.5,-0.5,1,30,10);ctx.fillStyle="blue";ctx.fillRect(0,0,250,100);

6.阴影设置

属性描述shadowColor设置或返回用于阴影的颜色shadowBlur设置或返回用于阴影的模糊级别shadowOffsetX设置或返回阴影距形状的水平距离shadowOffsetY设置或返回阴影距形状的垂直距离

阴影颜色shadowColor | 阴影模糊级别shadowBlur

默认值：#000000JavaScript 语法：context.shadowColor=color;默认值：0JavaScript 语法：context.shadowBlur=number;绘制一个带有黑色阴影的蓝色矩形，模糊级数是 20：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.shadowBlur=20;ctx.shadowColor="black";ctx.fillStyle="blue";ctx.fillRect(20,20,100,80);

阴影水平坐标shadowOffsetX | 阴影垂直坐标shadowOffsetY

默认值：0JavaScript 语法：context.shadowOffsetX=number;默认值：0JavaScript 语法：context.shadowOffsetY=number;绘制一个矩形，带有向右偏移 20 像素的阴影（从矩形的 left 位置），带有向下偏移 20 像素的阴影（从矩形的 top 位置）：

var c = document.getElementById("myCanvas");var ctx = c.getContext("2d");ctx.shadowBlur = 10;ctx.shadowOffsetX = 20;ctx.shadowOffsetY = 20;ctx.shadowColor = "black";ctx.fillStyle = "blue";ctx.fillRect(20, 20, 100, 80);

7.色彩渐变设置

方法描述createLinearGradient()创建线性渐变（用在画布内容上）createRadialGradient()创建放射状/环形的渐变（用在画布内容上）addColorStop()规定渐变对象中的颜色和停止位置

渐变色彩和停止位置addColorStop()

JavaScrip语法

gradient.addColorStop(stop,color);

属性值：

参数描述stop介于 0.0 与 1.0 之间的值，表示渐变中开始与结束之间的位置。color在结束位置显示的 CSS 颜色值

线性渐变createLinearGradient()

语法：

context.createLinearGradient(x0,y0,x1,y1);

属性值：

参数描述x0渐变开始点的 x 坐标y0渐变开始点的 y 坐标x1渐变结束点的 x 坐标y1渐变结束点的 y 坐标(提示)：请使用该对象作为 strokeStyle 或 fillStyle 属性的值。

定义从黑到白的渐变（从左向右），作为矩形的填充样式：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");var grd=ctx.createLinearGradient(0,0,170,0);grd.addColorStop(0,"black");grd.addColorStop(1,"white");ctx.fillStyle=grd;ctx.fillRect(20,20,150,100);

放射性渐变createRadialGradient()

语法：

context.createRadialGradient(x0,y0,r0,x1,y1,r1);

属性值：

参数描述x0渐变的开始圆的 x 坐标y0渐变的开始圆的 y 坐标r0开始圆的半径x1渐变的结束圆的 x 坐标y1渐变的结束圆的 y 坐标r1结束圆的半径绘制一个矩形，并用放射状/圆形渐变进行填充：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");var grd=ctx.createRadialGradient(75,50,5,75,50,40);grd.addColorStop(0,"red");grd.addColorStop(1,"white");ctx.fillStyle=grd;ctx.fillRect(10,10,150,100);

8.其它设置

图像重复createPattern()

JavaScript语法：

context.createPattern(image,"repeat|repeat-x|repeat-y|no-repeat");

属性值：

参数描述image规定要使用的图片、画布或视频元素。repeat默认。该模式在水平和垂直方向重复。repeat-x该模式只在水平方向重复。repeat-y该模式只在垂直方向重复。no-repeat该模式只显示一次（不重复）。

用到的图像：

在水平和垂直方向重复图像：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");var img=document.getElementById("lamp");var pat=ctx.createPattern(img,"repeat");ctx.rect(0,0,150,100);ctx.fillStyle=pat;ctx.fill();

点是否位于当前路径中isPointInPath()

JavaScript语法：

context.isPointInPath(x,y);

属性性：

参数描述x测试的 x 坐标y测试的 y 坐标绘制一个矩形，如果点 20,50 位于当前路径中：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");ctx.rect(20,20,150,100);if (ctx.isPointInPath(20,50)){   ctx.stroke();};

绘制图像视频drawImage()

JavaScript 语法 1
在画布上定位图像：

context.drawImage(img,x,y);

JavaScript 语法 2
在画布上定位图像，并规定图像的宽度和高度：

context.drawImage(img,x,y,width,height);

JavaScript 语法 3
剪切图像，并在画布上定位被剪切的部分：

context.drawImage(img,sx,sy,swidth,sheight,x,y,width,height);

属性值：

参数描述img规定要使用的图像、画布或视频。sx可选。开始剪切的 x 坐标位置。sy可选。开始剪切的 y 坐标位置。swidth可选。被剪切图像的宽度。sheight可选。被剪切图像的高度。x在画布上放置图像的 x 坐标位置。y在画布上放置图像的 y 坐标位置。width可选。要使用的图像的宽度。（伸展或缩小图像）height可选。要使用的图像的高度。（伸展或缩小图像）剪切图片，并在画布上对被剪切的部分进行定位：

var c=document.getElementById("myCanvas");var ctx=c.getContext("2d");var img=document.getElementById("scream");ctx.drawImage(img,90,130,90,80,20,20,90,80);

像素操作createImageData | getImageData() | putImageData()

方法描述createImageData()创建新的、空白的 ImageData 对象getImageData()返回 ImageData 对象，该对象为画布上指定的矩形复制像素数据putImageData()把图像数据（从指定的 ImageData 对象）放回画布上

合成操作globalAlpha() | globalCompositeOperation()

属性描述globalAlpha设置或返回绘图的当前 alpha 或透明值globalCompositeOperation设置或返回新图像如何绘制到已有的图像上

（注）globalCompositeOperation可用于遮罩截图功能。

更多

方法描述save()保存当前环境的状态restore()返回之前保存过的路径状态和属性createEvent() getContext() toDataURL()