jmgraph 3.2.26 → 3.2.28

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

package/src/core/jmUtils.js

@@ -1,6 +1,33 @@
 
+/**
+ * @fileoverview jmGraph 工具类
+ * 
+ * jmUtils 是 jmGraph 库的核心工具类，提供了一系列静态工具方法：
+ * - 对象克隆与深拷贝
+ * - 事件绑定与解绑
+ * - DOM 元素位置计算
+ * - 几何计算（点在多边形内判断、旋转等）
+ * - 颜色解析与转换
+ * - 字符串处理
+ * 
+ * 所有方法都是静态的，可以直接通过 jmUtils.methodName() 调用。
+ * 
+ * @module jmUtils
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import { jmList } from './jmList.js';
 
+/**
+ * CSS 颜色关键字映射表
+ * 
+ * 包含所有 CSS 标准颜色名称到十六进制值的映射。
+ * 支持 147 种命名颜色 + CSS 系统颜色。
+ * 
+ * @constant {Object.<string, string>}
+ * @private
+ */
 const colorKeywords = {
     aliceblue:            "#f0f8ff",
     antiquewhite:         "#faebd7",
@@ -38,11 +65,13 @@ const colorKeywords = {
     darkseagreen:         "#8fbc8f",
     darkslateblue:        "#483d8b",
     darkslategray:        "#2f4f4f",
+    darkslategrey:        "#2f4f4f",
     darkturquoise:        "#00ced1",
     darkviolet:           "#9400d3",
     deeppink:             "#ff1493",
     deepskyblue:          "#00bfff",
     dimgray:              "#696969",
+    dimgrey:              "#696969",
     dodgerblue:           "#1e90ff",
     firebrick:            "#b22222",
     floralwhite:          "#fffaf0",
@@ -77,6 +106,7 @@ const colorKeywords = {
     lightseagreen:        "#20b2aa",
     lightskyblue:         "#87cefa",
     lightslategray:       "#778899",
+    lightslategrey:       "#778899",
     lightsteelblue:       "#b0c4de",
     lightyellow:          "#ffffe0",
     lime:                 "#00ff00",
@@ -117,6 +147,7 @@ const colorKeywords = {
     powderblue:           "#b0e0e6",
     purple:               "#800080",
     red:                  "#ff0000",
+    rebeccapurple:        "#663399",
     rosybrown:            "#bc8f8f",
     royalblue:            "#4169e1",
     saddlebrown:          "#8b4513",
@@ -129,6 +160,7 @@ const colorKeywords = {
     skyblue:              "#87ceeb",
     slateblue:            "#6a5acd",
     slategray:            "#708090",
+    slategrey:            "#708090",
     snow:                 "#fffafa",
     springgreen:          "#00ff7f",
     steelblue:            "#4682b4",
@@ -143,15 +175,56 @@ const colorKeywords = {
     whitesmoke:           "#f5f5f5",
     yellow:               "#ffff00",
     yellowgreen:          "#9acd32",
-    transparent:          "rgba(0,0,0,0)"
+    transparent:          "rgba(0,0,0,0)",
+    // grey 别名（已有 darkslategrey/lightslategrey/slategrey/dimgrey）
+    // 以下为 CSS 系统颜色
+    activeborder:         "#bfcaca",
+    activecaption:        "#000080",
+    appworkspace:         "#ababab",
+    background:           "#636363",
+    buttonface:           "#c0c0c0",
+    buttonhighlight:      "#dedede",
+    buttonshadow:         "#808080",
+    buttontext:           "#000000",
+    captiontext:          "#000000",
+    graytext:             "#808080",
+    highlight:            "#b3d4fc",
+    highlighttext:        "#000000",
+    inactiveborder:       "#d4d0c8",
+    inactivecaption:      "#bfbbb0",
+    inactivecaptiontext:  "#545454",
+    infobackground:       "#fbfcc5",
+    infotext:             "#000000",
+    menu:                 "#c0c0c0",
+    menutext:             "#000000",
+    scrollbar:            "#c0c0c0",
+    threeddarkshadow:     "#696969",
+    threedface:           "#c0c0c0",
+    threedhighlight:      "#dfdfdf",
+    threedlightshadow:    "#dcdcdc",
+    threedshadow:         "#808080",
+    window:               "#ffffff",
+    windowframe:          "#646464",
+    windowtext:           "#000000"
   };
 
 /**
- * 画图基础对象
- * 当前库的工具类
+ * jmGraph 工具类
+ * 
+ * 提供常用的静态工具方法，包括对象操作、事件处理、几何计算、颜色转换等。
  * 
  * @class jmUtils
  * @static
+ * 
+ * @example
+ * // 克隆对象
+ * const newObj = jmUtils.clone({ a: 1, b: 2 });
+ * 
+ * // 绑定事件
+ * jmUtils.bindEvent(element, 'click', handler);
+ * 
+ * // 检查点是否在多边形内
+ * const inside = jmUtils.pointInPolygon({x: 10, y: 10}, polygonPoints);
  */
 export default class jmUtils {
     /**
@@ -307,12 +380,12 @@ export default class jmUtils {
                 el = el.offsetParent;
             }
         }
-        else if(el.x) {
-            pos.left += el.x;
-        }
-        else if(el.x){
-            pos.top += el.y;
-        } 
+		else if(el.x) {
+			pos.left += el.x;
+		}
+		else if(el.y){
+			pos.top += el.y;
+		}
         return pos;
     }
     /**
@@ -436,6 +509,30 @@ export default class jmUtils {
         return this.rayCasting(pt, polygon, offset);
     }
 
+    /**
+     * 判断点是否在线段上
+     * 
+     * 通过计算点到线段的垂直距离来判断点是否在线段上。
+     * 同时检查点是否在线段的范围内（不仅仅是直线上）。
+     * 
+     * @method pointOnLine
+     * @static
+     * @private
+     * @param {Object} pt 待检测的点 {x, y}
+     * @param {Object} p1 线段起点 {x, y}
+     * @param {Object} p2 线段终点 {x, y}
+     * @param {number} offset 允许的偏差值（像素）
+     * @returns {number} 0=不在线段上, 1=在线段上
+     * 
+     * @example
+     * const onLine = jmUtils.pointOnLine(
+     *     {x: 5, y: 5},      // 待检测点
+     *     {x: 0, y: 0},      // 起点
+     *     {x: 10, y: 10},    // 终点
+     *     2                  // 允许偏差
+     * );
+     * // 返回 1，点在对角线上
+     */
     static pointOnLine(pt, p1, p2, offset) {
         const minX = Math.min(p1.x, p2.x);
         const maxX = Math.max(p1.x, p2.x);
@@ -476,6 +573,25 @@ export default class jmUtils {
         return 0;
     }
 
+    /**
+     * 射线法判断点是否在多边形内部
+     * 
+     * 从待测点向右发射一条水平射线，计算与多边形边界的交点数量。
+     * - 交点数为奇数：点在多边形内部
+     * - 交点数为偶数：点在多边形外部
+     * 
+     * 这是判断点是否在任意多边形内的经典算法，时间复杂度 O(n)。
+     * 
+     * @method rayCasting
+     * @static
+     * @private
+     * @param {Object} pt 待检测的点 {x, y}
+     * @param {Array<Object>} polygon 多边形顶点数组 [{x, y}, ...]
+     * @param {number} offset 允许的偏差值（未使用）
+     * @returns {number} 0=在多边形外部, 2=在多边形内部
+     * 
+     * @see {@link https://en.wikipedia.org/wiki/Point_in_polygon Point in polygon - Wikipedia}
+     */
     static rayCasting(pt, polygon, offset) {
         const n = polygon.length;
         let inside = false;
@@ -849,8 +965,19 @@ export default class jmUtils {
     }
 
     /**
-     * 把255的rgb值转为0-1的值
-     * @param {rgba} color 颜色
+     * 将 RGB 颜色值从 0-255 范围转换为 0-1 范围
+     * 
+     * WebGL 中的颜色值通常使用 0-1 的浮点数表示，
+     * 此方法用于将标准 RGB 值转换为 WebGL 兼容格式。
+     * 
+     * @method rgbToDecimal
+     * @static
+     * @param {Object} color 颜色对象 {r, g, b, a?}
+     * @returns {Object} 转换后的颜色对象 {r, g, b, a?}，其中 r/g/b 为 0-1 范围
+     * 
+     * @example
+     * const color = jmUtils.rgbToDecimal({ r: 255, g: 128, b: 64 });
+     * // 返回 { r: 1, g: 0.502, b: 0.251 }
      */
     static rgbToDecimal(color) {
         color = this.clone(color);
@@ -860,7 +987,15 @@ export default class jmUtils {
         return color;
     }
 
-    //255值转为0-1的小数
+    /**
+     * 将字节值（0-255）转换为小数（0-1）
+     * 
+     * @method byteToDecimal
+     * @static
+     * @private
+     * @param {number} b 字节值（0-255）
+     * @returns {number} 小数值（0-1）
+     */
     static byteToDecimal(b) {
         return b / 255;
     }
@@ -903,14 +1038,52 @@ export default class jmUtils {
         }
         return r;
     }
-    // window.requestAnimationFrame() 告诉浏览器——你希望执行一个动画，并且要求浏览器在下次重绘之前调用指定的回调函数更新动画。该方法需要传入一个回调函数作为参数，该回调函数会在浏览器下一次重绘之前执行
+    /**
+     * 请求动画帧
+     * 
+     * 封装浏览器原生的 requestAnimationFrame 方法，提供跨浏览器兼容性。
+     * 在不支持 requestAnimationFrame 的环境中降级为 setTimeout。
+     * 
+     * @method requestAnimationFrame
+     * @static
+     * @param {Function} callback 动画帧回调函数，接收时间戳参数
+     * @param {Window} [win] 可选的窗口对象（用于多窗口环境）
+     * @returns {number} 动画帧请求ID，用于取消
+     * 
+     * @example
+     * let animationId;
+     * function animate(timestamp) {
+     *     // 更新动画
+     *     animationId = jmUtils.requestAnimationFrame(animate);
+     * }
+     * animationId = jmUtils.requestAnimationFrame(animate);
+     * 
+     * // 取消动画
+     * jmUtils.cancelAnimationFrame(animationId);
+     */
     static requestAnimationFrame(callback, win) {
         let fun = win && win.requestAnimationFrame? win.requestAnimationFrame: (typeof window !== 'undefined' && window.requestAnimationFrame? window.requestAnimationFrame: setTimeout);        
 		return fun(callback, 20);
     }
+    /**
+     * 取消动画帧请求
+     * 
+     * 取消之前通过 requestAnimationFrame 注册的回调。
+     * 在不支持 cancelAnimationFrame 的环境中降级为 clearTimeout。
+     * 
+     * @method cancelAnimationFrame
+     * @static
+     * @param {number} handler requestAnimationFrame 返回的请求ID
+     * @param {Window} [win] 可选的窗口对象（用于多窗口环境）
+     * 
+     * @example
+     * const animationId = jmUtils.requestAnimationFrame(animate);
+     * jmUtils.cancelAnimationFrame(animationId);
+     */
     static cancelAnimationFrame(handler, win) {
         let fun = win && win.cancelAnimationFrame? win.cancelAnimationFrame: (typeof window !== 'undefined' && window.cancelAnimationFrame? window.cancelAnimationFrame: clearTimeout);        
 		return fun(handler);
     }	
 }
-export { jmUtils };
+export { jmUtils };
+export { colorKeywords };