jmgraph 3.2.27 → 3.2.28

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') {

package/src/core/jmProperty.js

@@ -1,45 +1,170 @@
 
+/**
+ * @fileoverview jmGraph 属性管理基类
+ * 
+ * jmProperty 是 jmGraph 库中属性管理的核心类，继承自 jmObject。
+ * 提供了：
+ * - 基于 Symbol 的私有属性存储
+ * - 属性变更事件通知机制
+ * - 渲染模式管理（2D/WebGL）
+ * - 动画帧请求封装
+ * 
+ * @module jmProperty
+ * @extends jmObject
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmUtils} from "./jmUtils.js";
 import { jmObject } from "./jmObject.js";
 
+/**
+ * 属性存储的 Symbol 键
+ * 使用 Symbol 确保属性存储的私有性和唯一性
+ * @type {Symbol}
+ * @private
+ */
 const PROPERTY_KEY = Symbol("properties");
 
+/**
+ * jmGraph 属性管理基类
+ * 
+ * jmProperty 是 jmControl 的父类，为所有图形控件提供属性管理功能。
+ * 采用 Symbol + WeakMap 模式实现真正的私有属性存储，避免属性名冲突。
+ * 
+ * 核心特性：
+ * 1. **私有属性存储**：使用 Symbol 键确保属性不被外部直接访问
+ * 2. **属性变更通知**：设置属性时自动触发 'propertyChange' 事件
+ * 3. **渲染模式继承**：子控件自动继承所属 graph 的渲染模式
+ * 4. **脏标记传播**：子控件 needUpdate 会自动传播到 graph
+ * 
+ * @class jmProperty
+ * @extends jmObject
+ * 
+ * @example
+ * // 创建属性对象
+ * const prop = new jmProperty({ mode: 'webgl' });
+ * 
+ * // 设置和获取属性
+ * prop.property('customValue', 100);
+ * console.log(prop.property('customValue')); // 100
+ * 
+ * // 监听属性变更
+ * prop.on('propertyChange', (name, args) => {
+ *     console.log(`${name} changed from ${args.oldValue} to ${args.newValue}`);
+ * });
+ */
 export default class jmProperty extends jmObject {
+	/**
+	 * 构造函数
+	 * 
+	 * 初始化属性存储对象，并设置初始渲染模式。
+	 * 
+	 * @constructor
+	 * @param {Object} [params] - 初始化参数
+	 * @param {'2d'|'webgl'} [params.mode] - 渲染模式，默认 '2d'
+	 * 
+	 * @example
+	 * // 创建使用 WebGL 渲染的属性对象
+	 * const prop = new jmProperty({ mode: 'webgl' });
+	 */
 	constructor(params) {
 		super();
+		// 初始化私有属性存储对象
 		this[PROPERTY_KEY] = {};
+		// 设置渲染模式
 		if(params && params.mode) this.mode = params.mode;
 	}
 
+	/**
+	 * 获取或设置属性值
+	 * 
+	 * 这是属性系统的核心方法，所有属性的存取都通过此方法。
+	 * 设置属性时会自动触发 'propertyChange' 事件，便于实现响应式更新。
+	 * 
+	 * @method property
+	 * @param {string} name - 属性名称
+	 * @param {*} [value] - 属性值（设置时提供）
+	 * @returns {*} 获取时返回属性值，设置时返回设置的值
+	 * 
+	 * @example
+	 * // 获取属性
+	 * const value = obj.property('myProp');
+	 * 
+	 * // 设置属性
+	 * obj.property('myProp', 'newValue');
+	 * 
+	 * // 链式调用
+	 * obj.property('a', 1).property('b', 2);
+	 */
 	property(...pars) {
 		if(pars) {
 			const pros = this[PROPERTY_KEY];
 			const name = pars[0];
+			
+			// 设置属性
 			if(pars.length > 1) {
 				const value = pars[1];
 				const args = {oldValue: pros[name], newValue: value};
 				pros[name] = pars[1];
+				// 触发属性变更事件（如果对象支持事件）
 				if(this.emit) this.emit('propertyChange', name, args);
 				return pars[1];
 			}
+			// 获取属性
 			else if(name) {
 				return pros[name];
 			}
 		}
 	}
 
+	/**
+	 * 是否需要重绘标记
+	 * 
+	 * 当属性变化导致需要重新渲染时设置此标记。
+	 * 设置为 true 时，会自动将所属 graph 的 needUpdate 设为 true，
+	 * 从而触发画布重绘。
+	 * 
+	 * @type {boolean}
+	 * 
+	 * @example
+	 * // 标记需要重绘
+	 * control.needUpdate = true;
+	 * 
+	 * // 检查是否需要重绘
+	 * if(control.needUpdate) {
+	 *     control.redraw();
+	 * }
+	 */
 	get needUpdate() {
 		return this.property('needUpdate');
 	}
 	set needUpdate(v) {
 		this.property('needUpdate', v);
+		// 传播脏标记到 graph（避免 jmGraph 自身循环）
 		if(v && !this.is('jmGraph') && this.graph) {
 			this.graph.needUpdate = true;
 		}
 	}
 
+	/**
+	 * 所属的画布实例
+	 * 
+	 * 获取或设置当前对象所属的 jmGraph 实例。
+	 * 如果未显式设置，会自动向上查找父级链中的 jmGraph。
+	 * 
+	 * @type {jmGraph}
+	 * 
+	 * @example
+	 * // 获取所属画布
+	 * const graph = control.graph;
+	 * 
+	 * // 设置所属画布（通常由框架内部调用）
+	 * control.graph = myGraph;
+	 */
 	get graph() {
 		let g = this.property('graph');
+		// 如果未设置，尝试从父级链查找
 		g = g || (this.property('graph', this.findParent('jmGraph')));
 		return g;
 	}
@@ -47,20 +172,74 @@ export default class jmProperty extends jmObject {
 		return this.property('graph', v);
 	}
 
+	/**
+	 * 渲染模式
+	 * 
+	 * 获取当前渲染模式，支持 '2d' 和 'webgl' 两种模式。
+	 * 渲染模式的查找优先级：
+	 * 1. 当前对象设置的 mode
+	 * 2. 如果是 jmGraph，默认 '2d'
+	 * 3. 从所属 graph 继承 mode
+	 * 
+	 * @type {'2d'|'webgl'}
+	 * @readonly
+	 * 
+	 * @example
+	 * // 检查渲染模式
+	 * if(control.mode === 'webgl') {
+	 *     // 使用 WebGL 特性
+	 * } else {
+	 *     // 使用 Canvas 2D API
+	 * }
+	 */
 	get mode() {
 		let m = this.property('mode');
 		if(m) return m;
-		else if(this.is('jmGraph')) return this.property('mode');
-		return this.graph.mode;
+		// 如果当前对象是jmGraph且没有设置mode，返回默认值
+		if(this.is('jmGraph')) return this.property('mode') || '2d';
+		// 否则从所属的graph获取mode
+		return this.graph?.mode || '2d';
 	}
 	set mode(v) {
 		return this.property('mode', v);
 	}
 
+	/**
+	 * 请求动画帧
+	 * 
+	 * 封装 requestAnimationFrame，支持在不同环境下工作。
+	 * 如果当前对象关联了 canvas，会使用 canvas 的 requestAnimationFrame。
+	 * 
+	 * @method requestAnimationFrame
+	 * @param {Function} handler - 动画帧回调函数
+	 * @returns {number} 动画帧请求ID，用于取消
+	 * 
+	 * @example
+	 * // 请求下一帧动画
+	 * const frameId = control.requestAnimationFrame(() => {
+	 *     // 更新动画状态
+	 *     control.redraw();
+	 * });
+	 * 
+	 * // 取消动画帧
+	 * control.cancelAnimationFrame(frameId);
+	 */
 	requestAnimationFrame(handler) {
 		return jmUtils.requestAnimationFrame(handler, this.graph? this.graph.canvas: null);
 	}
 
+	/**
+	 * 取消动画帧请求
+	 * 
+	 * 取消之前通过 requestAnimationFrame 注册的回调。
+	 * 
+	 * @method cancelAnimationFrame
+	 * @param {number} handler - 动画帧请求ID
+	 * 
+	 * @example
+	 * // 取消动画帧
+	 * control.cancelAnimationFrame(frameId);
+	 */
 	cancelAnimationFrame(handler) {
 		return jmUtils.cancelAnimationFrame(handler, this.graph? this.graph.canvas: null);
 	}

package/src/core/jmShadow.js

@@ -1,15 +1,44 @@
+/**
+ * @fileoverview jmShadow 阴影类
+ * 
+ * jmShadow 提供了图形阴影效果的创建和管理功能。
+ * 支持设置阴影的偏移、模糊程度和颜色。
+ * 
+ * 主要功能：
+ * - 阴影偏移设置（x, y）
+ * - 模糊程度设置（blur）
+ * - 阴影颜色设置（color）
+ * - 字符串解析和序列化
+ * 
+ * @module jmShadow
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmUtils} from "./jmUtils.js";
 
 /**
- * 画图阴影对象表示法
- *
+ * 阴影类
+ * 
+ * 用于创建图形的阴影效果。阴影可以应用于任何图形控件。
+ * 
  * @class jmShadow
- * @param {number} x 横坐标偏移量
- * @param {number} y 纵坐标编移量
- * @param {number} blur 模糊值
- * @param {string} color 阴影的颜色
+ * 
+ * @param {number|string} x 横坐标偏移量，或阴影字符串格式 'x,y,blur,color'
+ * @param {number} [y] 纵坐标偏移量
+ * @param {number} [blur] 模糊值
+ * @param {string} [color] 阴影颜色
+ * 
+ * @example
+ * // 创建阴影
+ * const shadow = new jmShadow(5, 5, 10, 'rgba(0,0,0,0.5)');
+ * 
+ * // 从字符串创建
+ * const shadow = new jmShadow('5, 5, 10, rgba(0,0,0,0.5)');
+ * 
+ * // 应用到图形
+ * rect.style.shadow = shadow;
  */
-
 export default class jmShadow {
 	constructor(x, y, blur, color) {
 		if(typeof x == 'string' && !y && !blur && !color) {