jCanvas Extending jCanvas 扩展jCanvas - caleb531/jcanvas-docs GitHub Wiki
Extending jCanvas 扩展jCanvas
jCanvas provides a plugin API so you can create methods which integrate with jCanvas. To do so, use the jCanvas.extend()
method.
jCanvas提供了一个插件接口,这样你就可以创建你自己的方法,整合到jCanvas中。为了做到这点,要使用jCanvas.extend()
方法。
The extend()
method accepts one object containing three properties:
extend()
方法接收一个对象,包含下边三个属性:
name
: The name of the method you are creating
name
:你要创建的方法的名称
type
: Optional; the type of drawing, which jCanvas will recognize as a valid value for the type
property.
type
:可选,绘制的类型,jCanvas会将其识别为type
属性的有效值。
props
: Optional; the custom properties your method uses (and their default values). These properties will be merged into the arguments object (mentioned below) for use in your method's code.
props
:可选,你方法使用的自定义属性(及它们的默认值)。这个属性会合并到参数对象当中(在下边会提到),然后使用到你方法的代码中。
fn
: The function providing the plugin's functionality. It accepts two arguments:
fn
:提供插件功能性的方法,它接收两个参数:
+ The context of the canvas 画布语境(画笔)
+ The parameters object the method will receive when called 方法被调用时接收到的参数
$.jCanvas.extend({
name: 'pluginName',
props: {
prop: true
},
fn: function(ctx, params) {
// Your code here
}
});
drawHeart()
举例:drawHeart
方法
Example: To demonstrate how this works, we'll be creating a method that draws a heart on the canvas.
为了展示它如何运行,我们会创建一个方法,用它来在画布上画心形。
// Create a drawHeart() method 创建drawHeart方法
$.jCanvas.extend({
name: 'drawHeart',
type: 'heart',
props: {},
fn: function(ctx, params) {
// Just to keep our lines short 只是为了保持代码行简短
var p = params;
// Enable layer transformations like scale and rotate 启用层转换,如缩放/旋转等
$.jCanvas.transformShape(this, ctx, p);
// Draw heart 画心
ctx.beginPath();
ctx.moveTo(p.x, p.y + p.radius);
// Left side of heart 心的左半边
ctx.quadraticCurveTo(
p.x - (p.radius * 2),
p.y - (p.radius * 2),
p.x,
p.y - (p.radius / 1.5)
);
// Right side of heart 心的右半边
ctx.quadraticCurveTo(
p.x + (p.radius * 2),
p.y - (p.radius * 2),
p.x,
p.y + p.radius
);
// Call the detectEvents() function to enable jCanvas events
// 调用detectEvents方法来启用jCanvas事件
// Be sure to pass it these arguments, too!
// 同时确保将这些参数传给这个方法
$.jCanvas.detectEvents(this, ctx, p);
// Call the closePath() functions to fill, stroke, and close the path
// 调用closePath方法来填充、描边、关闭路径
// This function also enables masking support and events
// 这个方法也启用了遮罩支持及事件
// It accepts the same arguments as detectEvents()
// 它允许与detectEvents方法相同的参数
$.jCanvas.closePath(this, ctx, p);
}
});
// Use the drawHeart() method 使用drawHeart方法
$('canvas').drawHeart({
layer: true,
draggable: true,
fillStyle: '#c33',
radius: 50,
x: 150, y: 130
});
API Methods 接口方法
The jCanvas object ($.jCanvas
) provides a few useful methods for integrating your methods with jCanvas. All of these methods accept the same three arguments: the canvas DOM element (this
), the canvas context (ctx
), and the parameters object (params
).
jCanvas对象($.jCanvas)提供了一些有用的方法,来将你的方法整合进jCanvas中。所有的这些方法都接收三个参数:画布的DOM元素(this),画布的语境(ctx)和参数对象(params)。
setGlobalProps()
:sets global canvas properties like fillStyle
, shadowColor
, etc.
setGlobalProps()
:设置全局画布属性,像fillStyle
,shadowColor
等等
transformShape()
: Enables shape transformation using the standard transformation properties (rotate, scale,translate). Note that the closePath()
method must be called later on to restore the layer transformations.
transformShape()
:启用形状转换,使用标准的转换属性(rotate
,scale
,translate
)。注意,必须接着调用closePath()
方法,用来恢复层的转换。
detectEvents()
: Enables and detects jCanvas events for your custom path. The method accepts three arguments: Note that this method should be called at the end of your path.
detectEvents()
:为你自定义的路径,启用并侦测jCanvas事件,方法接收三个参数:注意,这个方法应该在你路径的结尾才调用。
closePath()
: Closes the current path, and fills/strokes it if the respective properties have been set. The method also enables masking for the path through the use of the mask
property.
closePath()
:关闭当前路径,并给它填充/描边(如果属性各自被设置了的话)。这个方法也启用了路径遮罩,通过mask
属性来使用。
setCanvasFont()
: Sets the font of the canvas context based on the fontStyle
, fontSize
, and fontFamily
properties.
setCanvasFont()
:调用画布语境使用的字体,基于fontStyle
,fontSize
和fontFamily
属性。
measureText()
: Augments the given parameter object with the calculated width and height of the text. Accepts an array of strings (representing lines of text) as a fourth argument.
measureText()
:使用计算出来的文字的宽高,来增强给定的参数对象。接收字符串数组(代表文本的每一行)作为第四参数。
$.jCanvas.detectEvents(this, ctx, params);
$.jCanvas.closePath(this, ctx, params);
Notes 注意
When calling your method, jCanvas will automatically loop through selected canvas elements, so you don't need to.
当调用你的方法时,jCanvas会自动循环已选画布元素,所以你不用自己循环。