jmgraph 3.2.26 → 3.2.28

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

package/src/core/jmObject.js

@@ -1,78 +1,198 @@
 
+/**
+ * @fileoverview jmGraph 基础对象类
+ * 
+ * jmObject 是 jmGraph 库中所有对象的基类，提供了：
+ * - 唯一ID生成机制
+ * - 类型检查方法
+ * - 动画帧调度系统
+ * 
+ * @module jmObject
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmList} from "./jmList.js";
 
+/**
+ * 控件ID计数器
+ * 用于为每个新创建的对象生成唯一标识符
+ * @type {number}
+ * @private
+ */
 let control_id_counter = 0;
 
+/**
+ * jmGraph 基础对象类
+ * 
+ * 所有图形控件、属性对象、工具类的基类。
+ * 提供了对象标识、类型检查和动画调度等核心功能。
+ * 
+ * @class jmObject
+ * @example
+ * // 创建一个基础对象
+ * const obj = new jmObject();
+ * console.log(obj.id); // 输出唯一ID
+ * 
+ * // 类型检查
+ * obj.is('jmObject'); // true
+ * obj.is(jmObject);  // true
+ */
 export default class jmObject {
+	/**
+	 * 构造函数
+	 * 
+	 * 创建一个新的基础对象实例，自动分配唯一ID。
+	 * 如果传入的是 jmGraph 实例，则建立关联关系。
+	 * 
+	 * @constructor
+	 * @param {jmGraph} [g] - 可选的 jmGraph 实例，用于建立对象与画布的关联
+	 * 
+	 * @example
+	 * // 创建独立对象
+	 * const obj = new jmObject();
+	 * 
+	 * // 创建关联画布的对象
+	 * const graph = new jmGraph(canvas);
+	 * const objWithGraph = new jmObject(graph);
+	 */
 	constructor(g) {
+		// 如果传入的是 jmGraph 实例，则建立引用关系
 		if(g && g.type == 'jmGraph') {
 			this.graph = g;
 		}
+		// 生成唯一ID
 		this.id = ++control_id_counter;
 	}
 	
 	/**
-	 * 检 查对象是否为指定类型
+	 * 检查对象是否为指定类型
+	 * 
+	 * 支持两种类型检查方式：
+	 * 1. 字符串方式：检查对象的 type 属性是否匹配
+	 * 2. 类构造函数方式：使用 instanceof 检查原型链
 	 * 
 	 * @method is
-	 * @param {class} type 判断的类型
-	 * @for jmObject
-	 * @return {boolean} true=表示当前对象为指定的类型type,false=表示不是
+	 * @param {string|Function} type - 要检查的类型名称（字符串）或类构造函数
+	 * @returns {boolean} 如果对象是指定类型则返回 true，否则返回 false
+	 * 
+	 * @example
+	 * // 使用字符串检查
+	 * control.is('jmRect'); // 检查是否为矩形
+	 * 
+	 * // 使用类构造函数检查
+	 * control.is(jmControl); // 检查是否为 jmControl 实例
+	 * control.is(jmPath);   // 检查是否继承自 jmPath
 	 */
 	is(type) {
+		// 字符串类型：检查 type 属性
 		if(typeof type == 'string') {
 			return this.type == type;
 		}
+		// 类构造函数：使用 instanceof 检查原型链
 		return this instanceof type;
 	}
 
+	/**
+	 * 注册并执行动画帧回调
+	 * 
+	 * 提供动画帧调度功能，支持：
+	 * - 按指定时间间隔执行回调
+	 * - 多个动画句柄并行执行
+	 * - 自动清理返回 false 的动画
+	 * - 错误自动移除异常动画
+	 * 
+	 * 此方法通常由 jmGraph 实例调用，子控件会委托给所属的 graph 处理。
+	 * 
+	 * @method animate
+	 * @param {Function} handle - 动画回调函数，返回 false 时自动移除
+	 * @param {number} [millisec=20] - 执行间隔（毫秒），默认 20ms
+	 * @param {...*} [params] - 传递给回调函数的额外参数
+	 * 
+	 * @example
+	 * // 创建一个简单的动画
+	 * let x = 0;
+	 * graph.animate(function() {
+	 *     x += 1;
+	 *     rect.position.x = x;
+	 *     graph.redraw();
+	 *     
+	 *     // 动画结束条件
+	 *     if(x > 100) return false;
+	 * }, 16); // 约60fps
+	 * 
+	 * // 带参数的动画
+	 * graph.animate(function(speed) {
+	 *     x += speed;
+	 *     // ...
+	 * }, 16, 5); // speed = 5
+	 */
 	animate(...args) {
+		// 只有 jmGraph 实例才真正处理动画调度
 		if(this.is('jmGraph')) {
+			// 注册新的动画句柄
 			if(args.length > 1) {
 				if(!this.animateHandles) this.animateHandles = new jmList();
 				
+				// 收集额外参数
 				const params = [];
 				if(args.length > 2) {
 					for(let i=2;i<args.length;i++) {
 						params.push(args[i]);
 					}
 				}
+				// 添加动画句柄到列表
 				this.animateHandles.add({
-					millisec: args[1] || 20, 
-					handle: args[0], 
-					params: params
+					millisec: args[1] || 20,    // 执行间隔
+					handle: args[0],             // 回调函数
+					params: params               // 额外参数
 				});
 			}
+			
+			// 如果有动画句柄，启动调度循环
 			if(this.animateHandles) {
 				if(this.animateHandles.count() > 0) {
 					const self = this;
+					// 使用 setTimeout 进行调度（避免 requestAnimationFrame 的固定帧率限制）
 					this.dispatcher = setTimeout(function(_this) {
 						_this = _this || self;
-						const overduehandles = [];
+						const overduehandles = [];  // 需要移除的句柄
 						const curTimes = Date.now();
+						
+						// 遍历执行所有动画句柄
 						_this.animateHandles.each(function(i,ani) {
 							try {
+								// 检查是否到达执行时间
 								if(ani && ani.handle && (!ani.times || curTimes - ani.times >= ani.millisec)) {
+									// 执行回调
 									const r = ani.handle.apply(_this, ani.params);
+									// 返回 false 表示动画结束
 									if(r === false) {
 										overduehandles.push(ani);
 									}
+									// 更新最后执行时间
 									ani.times = curTimes;
 								}
 							}
 							catch(e) {
+								// 出错的句柄自动移除
 								if(ani) overduehandles.push(ani);
 							}
 						});
+						
+						// 移除已完成的动画句柄
 						for(const i in overduehandles) {
 							_this.animateHandles.remove(overduehandles[i]);
 						}
+						
+						// 继续下一轮调度
 						_this.animate();
 					},10,this);
 				}
 			}
 		}
 		else {
+			// 非 jmGraph 对象委托给所属的 graph 处理
 			const graph = this.graph;
 			if(graph) {
 				graph.animate(...args);

package/src/core/jmPath.js

@@ -1,13 +1,51 @@
+/**
+ * @fileoverview jmPath 路径基类
+ * 
+ * jmPath 是大部分图形的基类，提供了基于点序列的路径绘制能力。
+ * 所有需要通过点序列定义形状的图形（如多边形、线条、贝塞尔曲线等）
+ * 都可以继承此类。
+ * 
+ * 主要功能：
+ * - 点序列管理（points 属性）
+ * - SVG 导出支持（toSVG 方法）
+ * - 路径闭合控制
+ * 
+ * @module jmPath
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmControl} from "./jmControl.js";
+
 /**
- * 基础路径,大部分图型的基类
- * 指定一系列点，画出图形
- *
+ * 基础路径类
+ * 
+ * 大部分图形的基类，通过指定一系列点来画出图形。
+ * 支持开放路径和闭合路径，支持 SVG 导出。
+ * 
  * @class jmPath
  * @extends jmControl
- * @param {object} params 路径参数 points=所有描点
+ * 
+ * @param {Object} params 路径参数
+ * @param {Array<Object>} [params.points] 点序列，每个点格式：{x:0, y:0, m:false}
+ * @param {string} [t='jmPath'] 类型标识
+ * 
+ * @example
+ * // 创建自定义路径
+ * const path = new jmPath({
+ *     points: [
+ *         {x: 0, y: 0},
+ *         {x: 100, y: 0},
+ *         {x: 100, y: 100},
+ *         {x: 0, y: 100}
+ *     ],
+ *     style: {
+ *         fill: '#ff0000',
+ *         stroke: '#000000',
+ *         close: true  // 闭合路径
+ *     }
+ * });
  */
-
 export default class jmPath extends jmControl {	
 
 	constructor(params, t='jmPath') {