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()：设置全局画布属性，像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 注意