jmgraph 3.2.27 → 3.2.29

package/src/core/jmEvents.js

@@ -1,14 +1,75 @@
+/**
+ * @fileoverview jmEvents 事件处理系统
+ * 
+ * jmEvents 是 jmGraph 库的事件处理模块，负责管理所有用户交互事件。
+ * 包括鼠标事件、触摸事件和键盘事件的绑定、分发和销毁。
+ * 
+ * 主要功能：
+ * - 鼠标事件：mousedown, mousemove, mouseup, click, dblclick 等
+ * - 触摸事件：touchstart, touchmove, touchend, touchcancel, tap
+ * - 键盘事件：keydown, keyup, keypress
+ * - 事件冒泡和委托机制
+ * 
+ * @module jmEvents
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmUtils} from "./jmUtils.js";
 
+/**
+ * jmEvents 事件处理类
+ * 
+ * 统一管理画布上的所有交互事件，包括鼠标、触摸和键盘事件。
+ * 支持事件冒泡机制，可以将事件传递给子控件处理。
+ * 
+ * @class jmEvents
+ * 
+ * @param {jmGraph} container jmGraph 实例
+ * @param {HTMLElement} target 事件目标元素（通常是 canvas 元素）
+ * 
+ * @example
+ * // 通常由 jmGraph 内部创建，不需要手动实例化
+ * const events = new jmEvents(graph, canvasElement);
+ */
 export default class jmEvents {
 
+	/**
+	 * 构造函数
+	 * 
+	 * @param {jmGraph} container jmGraph 实例
+	 * @param {HTMLElement} target 事件目标元素
+	 */
 	constructor(container, target) {
+		/**
+		 * jmGraph 实例
+		 * @type {jmGraph}
+		 */
 		this.container = container;
+		/**
+		 * 事件目标元素
+		 * @type {HTMLElement}
+		 */
 		this.target = target || container;
+		/**
+		 * 鼠标事件处理器
+		 * @type {jmMouseEvent}
+		 */
 		this.mouseHandler = new jmMouseEvent(this, container, target);
+		/**
+		 * 键盘事件处理器
+		 * @type {jmKeyEvent}
+		 */
 		this.keyHandler = new jmKeyEvent(this, container, target);
 	}
 
+	/**
+	 * 触摸开始事件处理
+	 * 
+	 * @method touchStart
+	 * @param {TouchEvent} evt 触摸事件对象
+	 * @return {boolean} 如果事件目标为画布本身则返回 false
+	 */
 	touchStart(evt) {
 		evt = evt || window.event;
 		evt.eventName = 'touchstart';
@@ -19,6 +80,13 @@ export default class jmEvents {
 		}
 	};
 
+	/**
+	 * 触摸移动事件处理
+	 * 
+	 * @method touchMove
+	 * @param {TouchEvent} evt 触摸事件对象
+	 * @return {boolean} 如果事件目标为画布本身则返回 false
+	 */
 	touchMove(evt) {
 		evt = evt || window.event;
 		evt.eventName = 'touchmove';
@@ -29,6 +97,13 @@ export default class jmEvents {
 		}
 	};
 
+	/**
+	 * 触摸结束事件处理
+	 * 
+	 * @method touchEnd
+	 * @param {TouchEvent} evt 触摸事件对象
+	 * @return {boolean} 如果事件目标为画布本身则返回 false
+	 */
 	touchEnd(evt) {
 		evt = evt || window.event;
 		evt.eventName = 'touchend';
@@ -40,6 +115,13 @@ export default class jmEvents {
 		}
 	};
 
+	/**
+	 * 触摸取消事件处理
+	 * 
+	 * @method touchCancel
+	 * @param {TouchEvent} evt 触摸事件对象
+	 * @return {boolean} 如果事件目标为画布本身则返回 false
+	 */
 	touchCancel(evt) {
 		evt = evt || window.event;
 		evt.eventName = 'touchcancel';
@@ -51,6 +133,13 @@ export default class jmEvents {
 		}
 	};
 
+	/**
+	 * 轻触事件处理
+	 * 
+	 * @method tap
+	 * @param {Event} evt 事件对象
+	 * @return {boolean} 如果事件目标为画布本身则返回 false
+	 */
 	tap(evt) {
 		evt = evt || window.event;
 		evt.eventName = 'tap';
@@ -62,23 +151,56 @@ export default class jmEvents {
 		}
 	};
 
+	/**
+	 * 销毁事件处理器
+	 * 
+	 * 移除所有绑定的事件监听器，释放资源。
+	 * 
+	 * @method destroy
+	 */
 	destroy() {
 		this.mouseHandler.destroy();
 		this.keyHandler.destroy();
 	}
 }
 
+/**
+ * 鼠标事件处理器
+ * 
+ * @class jmMouseEvent
+ * @private
+ */
 class jmMouseEvent {
+	/**
+	 * 构造函数
+	 * 
+	 * @param {jmEvents} instance jmEvents 实例
+	 * @param {jmGraph} container jmGraph 实例
+	 * @param {HTMLElement} target 事件目标元素
+	 */
 	constructor(instance, container, target) {
 		this.instance = instance;
 		this.container = container;
 		this.target = target || container;
 
+		/**
+		 * 已绑定的事件映射表
+		 * @type {Object}
+		 */
 		this.eventEvents = {};
 
 		this.init(instance, container, target);
 	}
 	
+	/**
+	 * 初始化鼠标事件绑定
+	 * 
+	 * @method init
+	 * @private
+	 * @param {jmEvents} instance jmEvents 实例
+	 * @param {jmGraph} container jmGraph 实例
+	 * @param {HTMLElement} target 事件目标元素
+	 */
 	init(instance, container, target) {
 		const canvas = this.target;
 		const doc = typeof document != 'undefined'? document: null;
@@ -163,6 +285,13 @@ class jmMouseEvent {
 		},{ passive: false }));
 	}
 
+	/**
+	 * 销毁鼠标事件处理器
+	 * 
+	 * 移除所有绑定的鼠标事件监听器。
+	 * 
+	 * @method destroy
+	 */
 	destroy() {
 		for(const name in this.eventEvents) {
 			const event = this.eventEvents[name];
@@ -172,17 +301,42 @@ class jmMouseEvent {
 	}
 }
 
+/**
+ * 键盘事件处理器
+ * 
+ * @class jmKeyEvent
+ * @private
+ */
 class jmKeyEvent {
+	/**
+	 * 构造函数
+	 * 
+	 * @param {jmEvents} instance jmEvents 实例
+	 * @param {jmGraph} container jmGraph 实例
+	 * @param {HTMLElement} target 事件目标元素
+	 */
 	constructor(instance, container,target) {
 		this.instance = instance;
 		this.container = container;
 		this.target = target || container;
 
+		/**
+		 * 已绑定的事件映射表
+		 * @type {Object}
+		 */
 		this.eventEvents = {};
 
 		this.init(container, target);
 	}
 
+	/**
+	 * 初始化键盘事件绑定
+	 * 
+	 * @method init
+	 * @private
+	 * @param {jmGraph} container jmGraph 实例
+	 * @param {HTMLElement} target 事件目标元素
+	 */
 	init(container, target) {
 		const doc = typeof document != 'undefined'? document: null;
 

package/src/core/jmFilter.js

@@ -1,13 +1,50 @@
+/**
+ * @fileoverview jmFilter 滤镜类
+ * 
+ * jmFilter 提供了 CSS 滤镜效果的管理和应用功能。
+ * 支持多种滤镜效果，可以组合使用。
+ * 
+ * 支持的滤镜：
+ * - blur: 模糊效果
+ * - grayscale: 灰度效果
+ * - sepia: 复古效果
+ * - brightness: 亮度调节
+ * - contrast: 对比度调节
+ * - saturate: 饱和度调节
+ * - hue-rotate: 色相旋转
+ * - invert: 反色效果
+ * - opacity: 透明度调节
+ * 
+ * @module jmFilter
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmUtils} from "./jmUtils.js";
 
 /**
- * CSS滤镜效果类
+ * CSS 滤镜效果类
+ * 
  * 支持的滤镜: blur, grayscale, sepia, brightness, contrast, saturate, hue-rotate, invert, opacity
  *
  * @class jmFilter
  * @param {string|object} opt 滤镜参数
  *   字符串格式: "blur(2px) grayscale(50%) brightness(1.2)"
  *   对象格式: { blur: 2, grayscale: 0.5, brightness: 1.2 }
+ * 
+ * @example
+ * // 从字符串创建
+ * const filter = new jmFilter('blur(2px) grayscale(50%)');
+ * 
+ * // 从对象创建
+ * const filter = new jmFilter({
+ *     blur: 2,
+ *     grayscale: 0.5,
+ *     brightness: 1.2
+ * });
+ * 
+ * // 应用到图形
+ * shape.style.filter = filter;
  */
 export default class jmFilter {
 	constructor(opt) {

package/src/core/jmGradient.js

@@ -1,11 +1,56 @@
+/**
+ * @fileoverview jmGradient 渐变类
+ * 
+ * jmGradient 提供了线性渐变和径向渐变的创建和管理功能。
+ * 支持从 CSS 渐变字符串解析，以及转换为 Canvas 渐变对象。
+ * 
+ * 主要功能：
+ * - 线性渐变（linear-gradient）
+ * - 径向渐变（radial-gradient）
+ * - CSS 渐变字符串解析
+ * - Canvas 渐变对象生成
+ * - WebGL 渐变支持
+ * 
+ * @module jmGradient
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmUtils, colorKeywords} from "./jmUtils.js";
 import {jmList} from "./jmList.js";
 
 /**
  * 渐变类
- *
+ * 
+ * 用于创建和管理线性渐变或径向渐变效果。
+ * 支持 CSS 渐变字符串格式解析，可以转换为 Canvas 或 WebGL 兼容的渐变对象。
+ * 
  * @class jmGradient
- * @param {object} op 渐变参数,type:[linear= 线性渐变,radial=放射性渐变] 
+ * 
+ * @param {Object|string} opt 渐变参数对象或 CSS 渐变字符串
+ * @param {string} [opt.type='linear'] 渐变类型：'linear' 或 'radial'
+ * @param {number|string} [opt.x1] 起点X坐标（支持百分比）
+ * @param {number|string} [opt.y1] 起点Y坐标（支持百分比）
+ * @param {number|string} [opt.x2] 终点X坐标（支持百分比）
+ * @param {number|string} [opt.y2] 终点Y坐标（支持百分比）
+ * @param {number|string} [opt.r1] 内圆半径（径向渐变）
+ * @param {number|string} [opt.r2] 外圆半径（径向渐变）
+ * @param {Array} [opt.stops] 颜色停止点数组 [{offset, color}, ...]
+ * 
+ * @example
+ * // 创建线性渐变
+ * const gradient = new jmGradient({
+ *     type: 'linear',
+ *     x1: 0, y1: 0,
+ *     x2: '100%', y2: '100%',
+ *     stops: [
+ *         { offset: 0, color: '#ff0000' },
+ *         { offset: 1, color: '#0000ff' }
+ *     ]
+ * });
+ * 
+ * // 从 CSS 字符串创建
+ * const gradient = new jmGradient('linear-gradient(180deg, #ff0000, #0000ff)');
  */
 export default class jmGradient {
 	constructor(opt) {

package/src/core/jmGraph.js

@@ -1,3 +1,23 @@
+/**
+ * @fileoverview jmGraph 主画布类
+ * 
+ * jmGraph 是 jmGraph 库的核心类，代表一个完整的画布实例。
+ * 它继承自 jmControl，提供了完整的图形渲染、事件处理、缩放平移等功能。
+ * 
+ * 主要功能：
+ * - Canvas/WebGL 双渲染模式支持
+ * - 图形创建与管理（createShape, createLine, createPath 等）
+ * - 渐变和阴影效果（createLinearGradient, createRadialGradient, createShadow）
+ * - 缩放和平移（setZoom, pan, resetTransform）
+ * - 导出功能（toDataURL, exportToPNG, exportToJPEG, exportToSVG）
+ * - 自动刷新动画循环（autoRefresh）
+ * - 微信小程序支持
+ * 
+ * @module jmGraph
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmUtils} from "./jmUtils.js";
 import {jmList} from "./jmList.js";
 import {jmProperty} from './jmProperty.js';
@@ -9,15 +29,39 @@ import {jmControl} from "./jmControl.js";
 import {jmPath} from "./jmPath.js";
 
 /**
- * jmGraph画图类库
- * 对canvas画图api进行二次封装，使其更易调用，省去很多重复的工作。
- *
- * @module jmGraph
+ * jmGraph 画图类
+ * 
+ * 对 Canvas 画图 API 进行二次封装，使其更易调用，省去很多重复的工作。
+ * 支持多种图形的创建、渲染、交互和导出。
+ * 
  * @class jmGraph
  * @extends jmControl
- * @param {element} canvas 标签canvas
- * @param {object} option 参数：{width:宽,height:高}
- * @param {function} callback 初始化后的回调
+ * 
+ * @param {HTMLElement|string} canvas Canvas 元素或元素 ID
+ * @param {Object} [option] 配置选项
+ * @param {number} [option.width] 画布宽度
+ * @param {number} [option.height] 画布高度
+ * @param {string} [option.mode='2d'] 渲染模式：'2d' 或 'webgl'
+ * @param {boolean} [option.autoRefresh=false] 是否自动刷新
+ * @param {Object} [option.shapes] 自定义图形类型映射
+ * @param {function} [callback] 初始化完成后的回调函数
+ * 
+ * @example
+ * // 创建画布实例
+ * const graph = new jmGraph('canvasId', {
+ *     width: 800,
+ *     height: 600,
+ *     mode: '2d'
+ * });
+ * 
+ * // 创建一个矩形
+ * const rect = graph.createShape('rect', {
+ *     x: 100, y: 100,
+ *     width: 200, height: 150,
+ *     style: { fill: '#ff0000' }
+ * });
+ * graph.children.add(rect);
+ * graph.refresh();
  */
 export default class jmGraph extends jmControl {
 

package/src/core/jmLayer.js

@@ -1,9 +1,27 @@
+/**
+ * @fileoverview jmLayer 图层类
+ * 
+ * jmLayer 提供了图层管理功能，用于组织和控制图形对象的显示和交互。
+ * 图层可以包含多个图形对象，支持可见性和锁定控制。
+ * 
+ * 主要功能：
+ * - 图层可见性控制
+ * - 图层锁定（防止交互）
+ * - 图形对象组织和管理
+ * - 批量操作支持
+ * 
+ * @module jmLayer
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmControl} from "./jmControl.js";
 
 /**
  * 图层类
- * 用于组织和管理图形对象，支持可见性和锁定控制
- * 图层可以包含多个图形对象，并控制它们的显示和交互
+ * 
+ * 用于组织和管理图形对象，支持可见性和锁定控制。
+ * 图层可以包含多个图形对象，并控制它们的显示和交互。
  *
  * @class jmLayer
  * @extends jmControl
@@ -12,6 +30,20 @@ import {jmControl} from "./jmControl.js";
  * @param {boolean} [params.visible=true] 图层是否可见
  * @param {boolean} [params.locked=false] 图层是否锁定（锁定后不可交互）
  * @param {jmGraph} [params.graph] 所属的画布对象
+ * 
+ * @example
+ * // 创建图层
+ * const layer = new jmLayer({
+ *     name: 'background',
+ *     visible: true,
+ *     locked: false
+ * });
+ * 
+ * // 添加图形到图层
+ * layer.children.add(rect);
+ * 
+ * // 锁定图层
+ * layer.locked = true;
  */
 export default class jmLayer extends jmControl {
 	

package/src/core/jmList.js

@@ -1,4 +1,54 @@
+/**
+ * @fileoverview jmList 列表类
+ * 
+ * jmList 是 jmGraph 库的集合类，继承自原生 Array。
+ * 提供了增强的列表操作方法，包括去重添加、条件查找、遍历等。
+ * 
+ * 主要功能：
+ * - 去重添加元素（add）
+ * - 条件查找（get）
+ * - 正向/反向遍历（each）
+ * - 元素计数（count）
+ * - 移除回调支持
+ * 
+ * @module jmList
+ * @author jmGraph Team
+ * @license MIT
+ */
+
+/**
+ * jmList 列表类
+ * 
+ * 继承自 Array 的增强列表类，提供去重、遍历、查找等功能。
+ * 主要用于管理图形对象的子元素集合。
+ * 
+ * @class jmList
+ * @extends Array
+ * 
+ * @param {...*} arg 初始元素或数组
+ * 
+ * @example
+ * // 创建列表
+ * const list = new jmList([1, 2, 3]);
+ * 
+ * // 添加元素（自动去重）
+ * list.add(4);
+ * list.add([5, 6]);
+ * 
+ * // 遍历
+ * list.each((index, item) => {
+ *     console.log(index, item);
+ * });
+ * 
+ * // 条件查找
+ * const found = list.get(item => item > 3);
+ */
 export default class jmList extends Array {
+    /**
+     * 构造函数
+     * 
+     * @param {...*} arg 初始元素或数组
+     */
     constructor(...arg) {
         const ps = [];
         if(arg && arg.length && Array.isArray(arg[0])) {
@@ -8,10 +58,33 @@ export default class jmList extends Array {
         else {
             super();
         }
+        /**
+         * 配置选项
+         * @type {Object}
+         * @property {function} removeHandler 元素移除时的回调函数
+         */
         this.option = {};
+        /**
+         * 类型标识
+         * @type {string}
+         */
         this.type = 'jmList';
     }
 
+    /**
+     * 添加元素到列表
+     * 
+     * 自动去重，如果元素已存在则不会重复添加。
+     * 支持添加单个元素或数组。
+     * 
+     * @method add
+     * @param {*} obj 要添加的元素或数组
+     * @returns {*} 添加的元素
+     * 
+     * @example
+     * list.add(1);           // 添加单个元素
+     * list.add([2, 3, 4]);   // 添加数组
+     */
     add(obj) {
         if(obj && Array.isArray(obj)) {
             for(let i=0; i < obj.length; i++) {
@@ -24,6 +97,17 @@ export default class jmList extends Array {
         return obj;
     }
 
+    /**
+     * 从列表中移除元素
+     * 
+     * 移除所有匹配的元素，并触发移除回调。
+     * 
+     * @method remove
+     * @param {*} obj 要移除的元素
+     * 
+     * @example
+     * list.remove(item);
+     */
     remove(obj) {
         for(let i = this.length -1; i>=0; i--) {
             if(this[i] == obj) {
@@ -32,6 +116,15 @@ export default class jmList extends Array {
         }
     }
 
+    /**
+     * 移除指定索引位置的元素
+     * 
+     * @method removeAt
+     * @param {number} index 要移除的元素索引
+     * 
+     * @example
+     * list.removeAt(0);  // 移除第一个元素
+     */
     removeAt(index) {
         if(this.length > index) {
             const obj = this[index];
@@ -40,10 +133,39 @@ export default class jmList extends Array {
         }
     }
 
+    /**
+     * 检查列表是否包含指定元素
+     * 
+     * @method contain
+     * @param {*} obj 要检查的元素
+     * @returns {boolean} 如果包含返回 true，否则返回 false
+     * 
+     * @example
+     * if (list.contain(item)) {
+     *     console.log('元素存在');
+     * }
+     */
     contain(obj) {
         return this.includes(obj);
     }
 
+    /**
+     * 获取元素
+     * 
+     * 如果参数是函数，则返回第一个满足条件的元素；
+     * 如果参数是数字，则返回指定索引的元素。
+     * 
+     * @method get
+     * @param {number|function} index 索引或条件函数
+     * @returns {*} 找到的元素，如果未找到返回 undefined
+     * 
+     * @example
+     * // 按索引获取
+     * const item = list.get(0);
+     * 
+     * // 按条件查找
+     * const found = list.get(item => item.id === 5);
+     */
     get(index) {
         if(typeof index == 'function') {
             return this.find(index);
@@ -53,6 +175,27 @@ export default class jmList extends Array {
         }
     }
 
+    /**
+     * 遍历列表
+     * 
+     * 支持正向和反向遍历。在回调中返回 false 可以中断遍历。
+     * 
+     * @method each
+     * @param {function} cb 回调函数，参数为 (index, item)
+     * @param {boolean} [inverse=false] 是否反向遍历
+     * 
+     * @example
+     * // 正向遍历
+     * list.each((index, item) => {
+     *     console.log(index, item);
+     *     if (item.id === 3) return false;  // 中断遍历
+     * });
+     * 
+     * // 反向遍历
+     * list.each((index, item) => {
+     *     console.log(index, item);
+     * }, true);
+     */
     each(cb, inverse) {
         if(cb && typeof cb == 'function') {
             if(inverse) {
@@ -71,6 +214,20 @@ export default class jmList extends Array {
         }
     }
 
+    /**
+     * 统计元素数量
+     * 
+     * 如果提供了条件函数，返回满足条件的元素数量；
+     * 否则返回列表总长度。
+     * 
+     * @method count
+     * @param {function} [handler] 条件函数
+     * @returns {number} 元素数量
+     * 
+     * @example
+     * const total = list.count();  // 总数量
+     * const matched = list.count(item => item.active);  // 满足条件的数量
+     */
     count(handler) {
         if(handler && typeof handler == 'function') {
             let count = 0;
@@ -85,6 +242,16 @@ export default class jmList extends Array {
         return this.length;
     }
 
+    /**
+     * 清空列表
+     * 
+     * 移除列表中的所有元素。
+     * 
+     * @method clear
+     * 
+     * @example
+     * list.clear();
+     */
     clear() {
         this.splice(0, this.length);
     }