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
  }
});

Example: drawHeart() 举例:drawHeart方法

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():设置全局画布属性,像fillStyleshadowColor等等

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():启用形状转换,使用标准的转换属性(rotatescaletranslate)。注意,必须接着调用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():调用画布语境使用的字体,基于fontStylefontSizefontFamily属性。

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会自动循环已选画布元素,所以你不用自己循环。