jmgraph 3.2.26 → 3.2.28

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 @@
-import {jmUtils} from "./jmUtils.js";
+/**
+ * @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) {
@@ -220,7 +265,8 @@ export default class jmGradient {
 			console.warn('jmGradient: 渐变字符串为空');
 			return;
 		}
-		const gradientMatch = s.match(/(linear|radial)-gradient\s*\(\s*(.+)\)/i);
+		// 使用 [\s\S] 匹配任意字符（包括换行符），支持多行渐变字符串
+		const gradientMatch = s.match(/(linear|radial)-gradient\s*\(\s*([\s\S]+)\)/i);
 		if(!gradientMatch || gradientMatch.length < 3) {
 			console.warn('jmGradient: 无效的渐变字符串格式: "' + s + '"');
 			return;
@@ -605,14 +651,19 @@ export default class jmGradient {
 		const hexPattern = /^#([a-fA-F0-9]{3,8})$/;
 		if(hexPattern.test(color)) return true;
 
-		const rgbPattern = /^rgba?\s*\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*(,\s*[\d.]+\s*)?\)$/i;
+		// 支持 rgba(r,g,b,a) 和 rgba(r, g, b, a) 等各种空格格式
+		const rgbPattern = /^rgba?\s*\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*(,\s*[\d.]+\s*)?\)$/i;
 		if(rgbPattern.test(color)) return true;
 
-		const hslPattern = /^hsla?\s*\(\s*(\d{1,3})\s*,\s*(\d{1,3})%?\s*,\s*(\d{1,3})%?\s*(,\s*[\d.]+\s*)?\)$/i;
+		const hslPattern = /^hsla?\s*\(\s*\d{1,3}\s*,\s*\d{1,3}%?\s*,\s*\d{1,3}%?\s*(,\s*[\d.]+\s*)?\)$/i;
 		if(hslPattern.test(color)) return true;
 
-		const namedColors = ['red', 'blue', 'green', 'yellow', 'orange', 'purple', 'pink', 'white', 'black', 'cyan', 'magenta', 'gray', 'grey', 'brown', 'navy', 'teal', 'olive', 'maroon', 'silver', 'lime', 'aqua', 'fuchsia', 'violet', 'indigo', 'gold', 'silver', 'transparent'];
-		if(namedColors.includes(color.toLowerCase())) return true;
+		// 使用 jmUtils 中的完整 CSS 颜色关键字表
+		if(colorKeywords && colorKeywords[color.toLowerCase()]) return true;
+
+		// 宽松处理：符合 CSS 关键字命名规则的字符串也视为有效颜色
+		// (纯字母，可能在运行时被浏览器或其他环境解析)
+		if(/^[a-zA-Z]+$/.test(color)) return true;
 
 		return false;
 	}

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 {