关于本书

DrJs 帮助文档
关于本书

本书是DrJs的官方帮助文档，旨在帮助广大JavaScript爱好者快速了解DrJs，同时也是为各位研究或使用DrJs的朋友提供一个速查手册。

本书对应的DrJs版本为 0.2.1 版，在编写此帮助文档后，DrJs可能已经更新，请留意网站上的其它信息。

DrJs的主页为：http://www.sansi.org/drjs/index.html。

Copyright (c) 2008, DrJs, sansi.org


关于DrJs

关于DrJs

DrJs是一个轻量级的JavaScript类库，它的主要功能为提供网页上基于DOM和CSS的绘图支持，在适当的地方使用它可以简化问题，提高开发效率。

DrJs适用于那些需要在网页上绘制一些简单的函数图形（如正弦函数图、指数走势图等）或者简单的统计图形（如柱状图、折线图、饼图等）的情形，尤其适用于当相关的数据会频繁更新的情形，此时，你可以使用Ajax等方式从服务器取得数据，并实时地使用DrJs反应到图像上来。事实上，DrJs最初也即为这个目标设计的。

当然，你也可以使用DrJs干更多的事，比如在网页上绘制一个象棋棋盘，或者制作一个小型的WebGame，不过需要注意的是，DrJs并非在网页上绘图的最佳解决方案，DOM本身不是被设计来绘图的，因此，当绘制的图形过于复杂时，DrJs可能会耗费较多的内存，甚至可能引起浏览器的假死或崩溃。

DrJs适用于IE 6+以及Firefox，事实上，除了预置绘图函数中的方框(box)函数外，DrJs适用于IE 5.5+。

最后，DrJs是免费的，下载和使用它都不需要向任何人或组织支付费用。


工作原理

工作原理

DrJs的早期版本参考了WZ_JSGraphics，不过自从0.2版开始，DrJs采用了全新的思路及设计。

无论是DrJs还是WZ_JSGraphics，最基本的原理都是生成若干个绝对定位（position: absolute）的DOM元素（例如DIV）并对它们设置不同的位置来实现绘图，这与以前的像素图有一些类似。同时，DrJs和WZ_JSGraphics都秉承一个基本原则，即尽可能少生成DOM元素。

例如，要画一段圆弧，可以有如右图所示的三种方式，其中每一个格子代表一个DOM元素（如DIV）。最差的是左边的一种，它不但在边角处拖泥带水（这样图像会显得有明显的锯齿），而且使用了最多的DOM元素；中间一种则将边角处不必要的格子去掉了，但仍用了很多DOM元素；最好的是右边一种，它不但去掉了边角处不必要的格子，而且将格子进行了尽可能多的合并。

尽可能少生成DOM的好处是明显的，这样可以节约资源，同时加快显示速度。

关于图像填充，则是另外一种实现方法。例如左图是一个a = 100，b = 50的椭圆，从图中可以看到，它实际上是由若干矩形拼接而成的，类似的，其它填充图形，如实心多边形、实心扇形等都是由若干大小不能的矩形逼近拼接而成。这个思路来自于数学上的微积分思想。

另外，关于图形在画布上的定位，DrJs采用了类似于直角坐标系的方法。实际上它就是直角坐标系，但因为考虑到网页布局的特点，它的y轴是由上指向下方的。因此，画布中一个点(2, 3)的意思是它距离容器左上角的横向距离为2（像素），纵向距离为3（像素）。


入门指南

入门指南

DrJs的使用非常简单。

要在页面中使用DrJs，首先要将其包含到页面中，比如：

<script type="text/javascript" src="js/drjs.js"></script>

接下来，需要先生成一个画布（Canvas）对象：

var canvas = new drjs.Canvas({}, "canvasParentNode");

有了画布对象，就可以使用draw方法在这个画布对象上开始画图了，比如：

//画一条直线，这条直线的两个端点坐标为(5, 35)、(200, 300)
canvas.draw("line", [[5, 35], [200, 300]]);

//画一个椭圆，这个椭圆的x半径为40，y半径为20，椭圆距容器左上角距离为(5, 190)
canvas.draw("oval", [40, 20], 5, 190);

画好图像之后，需要调用show方法才能将画布对象添加到相应的DOM节点：

canvas.show();

当然，在调用过show方法后，你还可以继续使用draw方法在这个画布上添加新的图形。

最后，如果你需要清除画布，可以调用clear方法：

canvas.clear();

这样，画布上所有的图像都将被清除，您可以在上面重新画新的图像。


drjs对象

drjs对象

这一部分介绍DrJs内置的类及对象。


画布类(Canvas)

画布类(Canvas)

DrJs的绘图都是在画布（Canvas）对象上进行的，生成一个画布对象可以说是使用DrJs绘图的第一步。

用法：

var canvas = new drjs.Canvas([parameter[, parent]]);

参数：

parameter:

可选，一个类似于CSS的对象。
各项值都是可选：
width: 画布宽度，number类型，单位为像素，默认值480
height: 画布高度，number类型，单位为像素，默认值360
backgroundColor: 画布背景色，默认为"#fff"
backgroundImage: 画布背景图片，默认为 "none"
borderWidth: 画布边框宽度，默认为0
borderStyle: 画布边框样式，默认为 "solid"
borderColor: 画布边框颜色，默认为 "#000"

parent:

可选，字符串或HTML文档对象
表示画布将要添加到的元素
如为字符串，则DrJs将查找id为parent的元素作为父元素
如未指定则为body元素

返回值：

一个Canvas对象。

示例：

var canvas = new drjs.Canvas({
  width: 480,
  height: 360,
  borderWidth: 1
}, "test");


属性: container

属性: container

这个属性指向当前画布的容器对象，即一个Div元素。


属性: groups

属性: groups

对象类型。功能暂未实现。


属性: items

属性: items

对象类型，包含了当前画布的items。


属性: parent

属性: parent

包含当前画布的HTML元素的引用。


属性: shapes

属性: shapes

数组类型，包含了页面中的各个形状的引用。


方法: chart()

方法: chart()

在当前Canvas上画一个图表。

canvas.chart(chartName, chartType, width, height, values[, labels[, colors[, stroke]]]);

参数：

chartName

必填，字符串，此图表的名字。

chartType

必填，字符串，此图表的类型。
目前支持三种类型：
bar - 直方图
pie - 饼图
polyline - 折线图

width

必填，数值，表示图表的宽度，单位为px。

height

必填，数值，表示图表的高度，单位为px。

values

必填，数组，图表数据，每一项都应该是非负数。图表将根据此项中的内容生成。（目前版本此项暂时没有效果。）

labels

选填，数组，表示图表每一项的文字。可以与values的长度不同。

colors

选填，数组，表示图像的默认颜色，与CSS定义颜色的方式相同。如未指定，将依次从预置的颜色中读取，如预置的颜色已被读完将随机生成一个新的颜色。以下都是合法的颜色：
"red", "#ff0000", "#f00"

stroke

选填，数值，表示线条宽度。仅当chartType为"polyline"时有效。

返回值：

一个项目（Item）对象。

参考：预置绘图函数


方法: clear()

方法: clear()

将画布上的内容全部清除。

canvas.clear();

参数：

无。

返回值：

undefiend。


方法: count()

方法: count()

这个方法返回当前画布一共使用了多少DOM元素，有助于开发者了解和控制图像规模，以免内存占用过大引发浏览器崩溃。

var n = canvas.count();

参数：

无。

返回值：

数值。


方法: draw()

方法: draw()

生成一个新画布对象（canvas）后，可以调用其draw方法在画布上绘制相应图形，方法如下：

canvas.draw(drawType, parameter[, left[, top[, color[, fill[, stroke]]]]]);

参数：

drawType

必填，表示绘图的类型，值可以为字符串、对象或数组。
如果值为字符串，则表示根据内置的绘图函数绘画，内置的绘图函数包括预置绘图函数和自定义绘图函数，例如"line"表示画直线的函数。如果输入的字符串在预置绘图函数中找不到，将抛出错误，错误消息为"drawType Error!"。

如果值为对象，表示传入一个方程，draw方法将根据这个方程绘图。方程的格式为：
{f: function(x) { ... return y}, interval: [x0, x1]}
相当于方程：
y = f(x), x∈[x0, x1]

如果值为数组，表示传入一个方程组，或者表示传入一个点阵。
方程组中每个方程的定义见上面方程的格式，点阵的格式如下：
[[x0, y0, width0, height0, color0], [x1, y1, width1, height1, color1], ..., [xn, yn, widthn, heightn, colorn]]
其中参数color可选，如果省略，将使用默认的颜色。

parameter

必填，表示给绘图方法传入的参数，具体格式因绘图方法的不同而不同。

left

选填，数值，表示图像距离画布左边的距离。默认为0。

top

选填，数值，表示图像距离画布顶部的距离。默认为0。

color

选填，表示图像的默认颜色，与CSS定义颜色的方式相同。如未指定，将依次从预置的颜色中读取，如预置的颜色已被读完将随机生成一个新的颜色。以下都是合法的颜色：
"red", "#ff0000", "#f00"

fill

选填，布尔型变量，表示图像是否填充。默认为不填充。
需要注意的是，并非所有形状都能填充成功，比如一个正弦函数的图形就无法填充。一般来说，封闭的形状（比如多边形、扇形等）可以填充。

stroke

选填，数值，表示画笔的粗细。默认为1。当参数fill设为true时，此项无效。

返回值：

一个形状（Shape）对象。

参考：预置绘图函数


方法: newColor()

方法: newColor()

返回一个新的颜色。

var color = canvas.newColor();

参数：

无。

返回值：

一个新颜色对象。

说明：

本方法将依次从DrJs内置的颜色中寻找颜色，如内置颜色已全部使用过则随机生成一个新的颜色。

当前版本DrJs内置了25种颜色，分别为：

"#FF0000", "#FF9900", "#FFFF00", "#00FF00", "#0000FF",
"#840084", "#FF00FF", "#008200", "#FF0066", "#CEDF39",
"#D5FF00", "#848200", "#00FF84", "#0082FF", "#84FFFF",
"#004184", "#8482FF", "#8400FF", "#FF0084", "#844100",
"#FF8242","#848242", "#FF8500","#BEB05A", "#BEB0E1"


方法: newItem()

方法: newItem()

在当前画布上生成一个新的Item对象。

var item = canvas.newItem(itemName);

参数：

itemName

生成的Item对象的名字。

返回值：

一个Item对象。


方法: show()

方法: show()

将画布显示到父节点中，父节点即在创建Canvas对象时指定的parent，如未指定父节点则将画布添加到body节点最后。

canvas.show();

参数：

无。

返回值：

undefiend。


方法: style()

方法: style()

为当前画布设定CSS属性。

canvas.style(cssObj);

参数：

cssObj

一个CSS对象。

返回值：

undefiend。


形状类(Shape)

形状类(Shape)

每次调用画布（Canvas）对象的draw方法都将生成一个新的形状（Shape）对象，形状对象是绘画组成的基础，也是绘画中可以通过DrJs接口操作的最基本的元素。

有一些不常用的内部属性或函数在帮助文档中没有给出。

形状对象一般由DrJs管理，不需要手动创建。如果的确需要手动创建DrJs对象，可用如下代码：

var shape = new drjs.Shape(canvas, dots, name);


属性: canvas

属性: canvas

指向当前形状所属的画布。


属性: dots

属性: dots

数组类型，包含当前形状的点的数组表示。


属性: name

属性: name

字符串类型，当前形状的名字。


属性: container

属性: container

HTML文档对象，指向当前形状容器（一个div元素）。


方法: addDots()

方法: addDots()

在当前形状中添加点。

shape.addDots(dots);

参数：

dots

必填，数组，代表要添加的点，形如[dot1, dot2, dot3, ..., dotn]。
点的格式为：[x, y, width, height, color]。

返回值：

当前形状对象。


方法: paint()

方法: paint()

将形状显示到画布。

shape.paint();

参数：

无。

返回值：

当前形状对象。


方法: remove()

方法: remove()

删除当前形状。

shape.remove();

参数：

无。

返回值：

null。


方法: setLeft()

方法: setLeft()

设置形状靠容器左边的距离。

shape.setLeft(v);

参数：

v

必填，数值，单位为像素。

返回值：

当前形状对象。


方法: setImg()

方法: setImg()

设置图片。

shape.setImg(src[, cssObj]);

参数：

src

必填，字符串，图表的路径。

cssObj

选填，对该图片要应用的样式。

返回值：

当前形状对象。


方法: setText()

方法: setText()

设置文字。

shape.setText(str[, cssObj]);

参数：

str

必填，字符串，要显示的文字。

cssObj

选填，对该字符串要应用的样式。

返回值：

当前形状对象。


方法: setTop()

方法: setTop()

设置形状靠容器顶部的距离。

shape.setTop(v);

参数：

v

必填，数值，单位为像素。

返回值：

当前形状对象。


项目类(Item)

项目类(Item)

若干个形状（Shape）可以组成一个项目（Item），比如杯盖 + 杯身 + 把手可以组成一个杯子，其中杯盖、杯身、把手相当于形状，最后组成的杯子则相当于项目。

组成项目后，该组形状可被视为一个整体，并且可以应用Item的方法。

生成一个新Item有两种方法，一种为默认方法：

var item = new drjs.Item(canvas, name);

另一种为DrJs画布对象方法：

var item = canvas.newItem(name);

两种方法的效果完全相同。


属性: canvas

属性: canvas

指向当前Item所属的画布对象。


属性: name

属性: name

当前项目的名字，字符串形式。


属性: shapes

属性: shapes

当前Item包含的形状，数组形式，数组的每一个元素为一个Shape对象的引用。


属性: container

属性: container

HTML文档对象，指向当前Item容器（一个div元素）。


方法: addShape()

方法: addShape()

在当前item对象中添加一个形状（Shape）。

item.addShape(shapes);

参数：

shapes

必填，一个Shape对象或一个包含多个Shape对象的数组。

返回值：

当前项目（Item）对象。


方法: locate()

方法: locate()

设定当前item对象的位置。

item.locate(left, top);

参数：

left

必填，数值，当前item距画布左边的距离，单位为像素。

top

必填，数值，当前item距画布顶部的距离，单位为像素。

返回值：

当前项目（Item）对象。


方法: remove()

方法: remove()

删除当前item。

item.remove();

返回值：

null。


组类(Group)

组类(Group)

尙未实现。


方法: addFunc()

方法: addFunc()

添加一个绘图方法。

drjs.addFunc(name, func);

参数：

name

字符串，必填。
表示添加的绘图方法的名字。

func

函数，必填。
表示该绘图方法的函数。

返回值：

undefined

说明：

添加一个绘图方法后，就可以在画布类的draw方法中直接使用，例如：

drjs.addFunc("myshape", function (canvas, p) { ... });
canvas.draw("myshape", parameters);

你还可以参考预置的绘图函数，使用addFunc()方法添加的函数与预置绘图函数具备同等地位。


预置绘图函数

预置绘图函数

DrJs预置了一些绘图函数，包括点、直线、椭圆等常用基本几何图形，适当地组合使用这些函数理论上来说能实现几乎所有图形的绘制。

你还可以通过addFunc方法添加自定义的绘图函数。


点(dot)

点(dot)

在画布对象canvas上画一个点。

canvas.draw("dot", parameter[, left[, top[, color[, fill[, stroke]]]]]);

参数：

parameter 为一个数组，形式如下：

[x, y]

代表这个点离容器（一般为形状对象 shape）左边和顶部的距离。

其它参数（left, top, color, fill, stroke）请参考Canvas类draw方法。

返回值：

一个形状（Shape）对象。


直线(line)

直线(line)

在画布对象canvas上画一条直线。

canvas.draw("line", parameter[, left[, top[, color[, fill[, stroke]]]]]);

参数：

parameter 为一个数组，形式如下：

[[x1, y2], [x2, y2]]

表示所需要绘制的直线的起点和终点的坐标。

其它参数（left, top, color, fill, stroke）请参考Canvas类draw方法。

返回值：

一个形状（Shape）对象。


折线(polyline)

折线(polyline)

在画布对象canvas上画一条折线。

canvas.draw("polyline", parameter[, left[, top[, color[, fill[, stroke]]]]]);

参数：

parameter 为一个数组，形式如下：

[[x1, y2], [x2, y2], [x3, y3], ..., [xn, yn]]

表示所需要绘制的折线的各个顶点。

其它参数（left, top, color, fill, stroke）请参考Canvas类draw方法。

返回值：

一个形状（Shape）对象。


多边形(polygon)

多边形(polygon)

在画布对象canvas上画一个多边形。

canvas.draw("polygon", parameter[, left[, top[, color[, fill[, stroke]]]]]);

参数：

parameter 为一个数组，形式如下：

[[x1, y2], [x2, y2], [x3, y3], ..., [xn, yn]]

表示所需要绘制的多边形的各个顶点。

其它参数（left, top, color, fill, stroke）请参考Canvas类draw方法。

返回值：

一个形状（Shape）对象。


矩形(rectangle)

矩形(rectangle)

在画布对象canvas上画一个多边形。

canvas.draw("rectangle", parameter[, left[, top[, color[, fill[, stroke]]]]]);

参数：

parameter 为一个数组，形式如下：

[x, y, width, height]

表示所需要绘制的矩形的左上顶点及宽和长。

其它参数（left, top, color, fill, stroke）请参考Canvas类draw方法。

返回值：

一个形状（Shape）对象。

说明：

矩形（rectangle）和方框（box）都是在页面上画一个矩形的方法，但它们的实现原理不同，前者基于直线（line），而后者直接基于DOM的Div元素及CSS控制。相对来说，box更节省资源，但box在IE5.5-环境下会有一些怪异，因此，应根据需要选择不同的实现方式。


椭圆(oval)

椭圆(oval)

在画布对象canvas上画一个椭圆。

canvas.draw("oval", parameter[, left[, top[, color[, fill[, stroke]]]]]);

参数：

parameter 为一个数组，形式如下：

[a, b]

表示所需要绘制的椭圆的x轴半径和y轴半径。
我们知道，在直角坐标系下，椭圆的方程可以写为：
(x / a) ^ 2 + (y / b) ^ 2 = 1
参数parameter中的a、b即对应方程中的a、b。

其它参数（left, top, color, fill, stroke）请参考Canvas类draw方法。

返回值：

一个形状（Shape）对象。


扇形(arc)

扇形(arc)

在画布对象canvas上画一个扇形。

canvas.draw("arc", parameter[, left[, top[, color[, fill[, stroke]]]]]);

参数：

parameter 为一个数组，形式如下：

[a, b, angle1, angle2, noborder]

a

必填，数值，表示所需绘制的扇形（所属的椭圆）的长轴。

b

必填，数值，表示所需绘制的扇形（所属的椭圆）的短轴。

angle1

必填，数值，表示所需绘制的扇形的起始角度，360度制。

angle2

必填，数值，表示所需绘制的扇形的终止角度，360度制。

noBorder

选填，布尔值，表示是否画边框。默认为有边框，如果指定此项为true，则将只绘制扇形的弧。

其它参数（left, top, color, fill, stroke）请参考Canvas类draw方法。

返回值：

一个形状（Shape）对象。


字符串(string)

字符串(string)

在画布对象canvas上画一个字符串。

canvas.draw("string", parameter[, left[, top[, color[, fill[, stroke]]]]]);

参数：

parameter 为一个数组，形式如下：

[str[, cssStyleObject]]

str

必填，字符串，要显示的字符。

cssStyleObject

选填，对象。代表要对这个字符串应用的CSS样式，可以在这里定义字体、背景色等，如未指定将使用默认值。

其它参数（left, top, color, fill, stroke）请参考Canvas类draw方法。

返回值：

一个形状（Shape）对象。


图片(img)

图片(img)

在画布对象canvas上添加一个图片。

canvas.draw("img", parameter[, left[, top[, color[, fill[, stroke]]]]]);

参数：

parameter 为一个数组，形式如下：

[src[, cssStyleObject]]

src

必填，字符串，要显示的图片的地址。

cssStyleObject

选填，对象。代表要对这个图片应用的CSS样式，可以在这里定义宽度、高度、边框等，如未指定将使用默认值。

其它参数（left, top, color, fill, stroke）请参考Canvas类draw方法。

返回值：

一个形状（Shape）对象。


方框(box)

方框(box)

在画布对象canvas上画一个方框。

canvas.draw("box", parameter[, left[, top[, color[, fill[, stroke]]]]]);

参数：

parameter 为一个数组，形式如下：

[width, height[, cssStyleObject]]

width

必填，数字类型。代表方框的宽度。

height

必填，数字类型。代表方框的高度。

cssStyleObject

选填，对象。代表要对这个方框应用的CSS样式，可以在这里定义边框、背景色等，如未指定将使用默认值。
如果在这个参数里也指定了方框的width或height，则这个值将覆盖原来的值。

其它参数（left, top, color, fill, stroke）请参考Canvas类draw方法。

返回值：

一个形状（Shape）对象。

说明：

box方法是一个特殊的方法，是直接生成一个div并设置相应CSS实现的，由于对CSS盒模型支持不足，此方法在 IE 5.5- 中的表现会有一些问题。


更新历史

更新历史

0.2.1版 - 2008年8月15日

修正了线条连接上的几处bug，使线条更加平滑；
修正了画扇形方法中的一处bug，弥补了在某些角度下填充不连续的问题；
添加了直方图、折线图、饼图三个统计图表方法。

0.2版 - 2008年6月21日

使用新的思路，重新设计了DrJs，使之可以根据传入的函数及区间绘制线条，并采用了全新的填充机制，使绘制任何实心形状成为可能。

0.1.5版 - 2008年1月15日

调整了DrJs的代码结构。

0.1.1版 - 2007年11月7日

修正了若干bug，优化了一些算法。

0.1版 - 2007年10月

实现了基本几何图形的绘制功能。