jmgraph 3.2.27 → 3.2.28

package/src/lib/webgl/index.js

@@ -1,12 +1,39 @@
 
 
 /**
- * 采用webgl基础绘图
+ * @fileoverview WebGL 渲染上下文适配器
+ * 
+ * 本模块提供了与 Canvas 2D API 兼容的 WebGL 接口，
+ * 使 jmGraph 能够无缝切换使用 Canvas 2D 或 WebGL 进行渲染。
+ * 
+ * 主要功能：
+ * - 提供与 Canvas 2D Context 兼容的方法签名
+ * - 管理变换矩阵（平移、缩放、旋转）
+ * - 支持渐变创建
+ * - 文本测量支持
+ * 
+ * @module lib/webgl
+ * @author jmGraph Team
  */
 import WebglBase from './base.js';
 import WebglPath from './path.js';
 
+/**
+ * WebGL 渲染上下文适配器类
+ * 提供与 Canvas 2D Context 兼容的 API 接口
+ * 
+ * @class webgl
+ * @example
+ * // 在 jmGraph 中使用
+ * const graph = new jmGraph(canvas, { mode: 'webgl' });
+ * // 内部会自动创建 webgl 实例作为 context
+ */
 class webgl {
+    /**
+     * 构造函数
+     * @param {WebGLRenderingContext} context WebGL 渲染上下文
+     * @param {Object} option 配置选项
+     */
     constructor(context, option) {
         this.option = option || {};
         this.context = context;
@@ -14,98 +41,187 @@ class webgl {
         this.base.context = context;
     }
 
-    // 保存当前状态
+    /**
+     * 保存当前状态到状态栈
+     * @method save
+     */
     save() {
         this.base.save();
     }
 
-    // 恢复上一个状态
+    /**
+     * 从状态栈恢复上一个状态
+     * @method restore
+     */
     restore() {
         this.base.restore();
     }
 
-    // 平移变换
+    /**
+     * 平移变换
+     * @method translate
+     * @param {number} x X 轴平移量
+     * @param {number} y Y 轴平移量
+     */
     translate(x, y) {
         this.base.translate(x, y);
     }
 
-    // 缩放变换
+    /**
+     * 缩放变换
+     * @method scale
+     * @param {number} sx X 轴缩放比例
+     * @param {number} sy Y 轴缩放比例
+     */
     scale(sx, sy) {
         this.base.scale(sx, sy);
     }
 
-    // 旋转变换
+    /**
+     * 旋转变换
+     * @method rotate
+     * @param {number} angle 旋转角度（弧度）
+     */
     rotate(angle) {
         this.base.rotate(angle);
     }
 
-    // 矩阵变换
+    /**
+     * 矩阵变换
+     * @method transform
+     * @param {number} a 水平缩放
+     * @param {number} b 垂直倾斜
+     * @param {number} c 水平倾斜
+     * @param {number} d 垂直缩放
+     * @param {number} e 水平移动
+     * @param {number} f 垂直移动
+     */
     transform(a, b, c, d, e, f) {
         this.base.transform(a, b, c, d, e, f);
     }
 
-    // 开始路径
+    /**
+     * 开始路径（WebGL 中由具体绘制方法处理，此方法为空实现）
+     * @method beginPath
+     */
     beginPath() {
         // WebGL 中不需要 beginPath，由具体的绘制方法处理
     }
 
-    // 关闭路径
+    /**
+     * 关闭路径（WebGL 中由具体绘制方法处理，此方法为空实现）
+     * @method closePath
+     */
     closePath() {
         // WebGL 中不需要 closePath，由具体的绘制方法处理
     }
 
-    // 移动到指定点
+    /**
+     * 移动到指定点（WebGL 中由具体绘制方法处理，此方法为空实现）
+     * @method moveTo
+     * @param {number} x 目标点 X 坐标
+     * @param {number} y 目标点 Y 坐标
+     */
     moveTo(x, y) {
         // WebGL 中不需要 moveTo，由具体的绘制方法处理
     }
 
-    // 绘制直线
+    /**
+     * 绘制直线到指定点（WebGL 中由具体绘制方法处理，此方法为空实现）
+     * @method lineTo
+     * @param {number} x 目标点 X 坐标
+     * @param {number} y 目标点 Y 坐标
+     */
     lineTo(x, y) {
         // WebGL 中不需要 lineTo，由具体的绘制方法处理
     }
 
-    // 填充路径
+    /**
+     * 填充路径（WebGL 中由具体绘制方法处理，此方法为空实现）
+     * @method fill
+     */
     fill() {
         // WebGL 中不需要 fill，由具体的绘制方法处理
     }
 
-    // 描边路径
+    /**
+     * 描边路径（WebGL 中由具体绘制方法处理，此方法为空实现）
+     * @method stroke
+     */
     stroke() {
         // WebGL 中不需要 stroke，由具体的绘制方法处理
     }
 
-    // 清除矩形区域
+    /**
+     * 清除矩形区域
+     * @method clearRect
+     * @param {number} x 矩形左上角 X 坐标
+     * @param {number} y 矩形左上角 Y 坐标
+     * @param {number} width 矩形宽度
+     * @param {number} height 矩形高度
+     */
     clearRect(x, y, width, height) {
         this.context.clearColor(0, 0, 0, 0);
         this.context.clear(this.context.COLOR_BUFFER_BIT);
     }
 
-    // 设置线条宽度
+    /**
+     * 设置线条宽度（由具体绘制方法处理）
+     * @method lineWidth
+     * @param {number} width 线条宽度
+     */
     lineWidth(width) {
         // 由具体的绘制方法处理
     }
 
-    // 设置填充样式
+    /**
+     * 设置填充样式（由具体绘制方法处理）
+     * @method fillStyle
+     * @param {string|Object} style 填充样式
+     */
     fillStyle(style) {
         // 由具体的绘制方法处理
     }
 
-    // 设置描边样式
+    /**
+     * 设置描边样式（由具体绘制方法处理）
+     * @method strokeStyle
+     * @param {string|Object} style 描边样式
+     */
     strokeStyle(style) {
         // 由具体的绘制方法处理
     }
 
-    // 绘制文本
+    /**
+     * 绘制填充文本（由具体绘制方法处理）
+     * @method fillText
+     * @param {string} text 要绘制的文本
+     * @param {number} x 文本起始 X 坐标
+     * @param {number} y 文本起始 Y 坐标
+     * @param {number} [maxWidth] 最大宽度
+     */
     fillText(text, x, y, maxWidth) {
         // 由具体的绘制方法处理
     }
 
-    // 描边文本
+    /**
+     * 绘制描边文本（由具体绘制方法处理）
+     * @method strokeText
+     * @param {string} text 要绘制的文本
+     * @param {number} x 文本起始 X 坐标
+     * @param {number} y 文本起始 Y 坐标
+     * @param {number} [maxWidth] 最大宽度
+     */
     strokeText(text, x, y, maxWidth) {
         // 由具体的绘制方法处理
     }
 
-    // 测量文本宽度
+    /**
+     * 测量文本宽度
+     * @method measureText
+     * @param {string} text 要测量的文本
+     * @returns {TextMetrics} 文本测量结果，包含 width 属性
+     */
     measureText(text) {
         if(this.base && this.base._measureCtx) {
             return this.base._measureCtx.measureText(text);
@@ -113,22 +229,55 @@ class webgl {
         return { width: 15 };
     }
 
-    // 创建线性渐变
+    /**
+     * 创建线性渐变
+     * @method createLinearGradient
+     * @param {number} x1 起点X坐标
+     * @param {number} y1 起点Y坐标
+     * @param {number} x2 终点X坐标
+     * @param {number} y2 终点Y坐标
+     * @param {Object} bounds 渐变边界 {left, top, width, height}
+     * @returns {WebglGradient} WebGL 渐变对象
+     */
     createLinearGradient(x1, y1, x2, y2, bounds) {
         return this.base.createLinearGradient(x1, y1, x2, y2, bounds);
     }
 
-    // 创建径向渐变
+    /**
+     * 创建径向渐变
+     * @method createRadialGradient
+     * @param {number} x1 内圆中心X坐标
+     * @param {number} y1 内圆中心Y坐标
+     * @param {number} r1 内圆半径
+     * @param {number} x2 外圆中心X坐标
+     * @param {number} y2 外圆中心Y坐标
+     * @param {number} r2 外圆半径
+     * @param {Object} bounds 渐变边界 {left, top, width, height}
+     * @returns {WebglGradient} WebGL 渐变对象
+     */
     createRadialGradient(x1, y1, r1, x2, y2, r2, bounds) {
         return this.base.createRadialGradient(x1, y1, r1, x2, y2, r2, bounds);
     }
 
-    // 绘制图像
+    /**
+     * 绘制图像（由具体绘制方法处理）
+     * @method drawImage
+     * @param {Image|HTMLImageElement} img 图像对象
+     * @param {number} dx 目标 X 坐标
+     * @param {number} dy 目标 Y 坐标
+     * @param {number} [dWidth] 目标宽度
+     * @param {number} [dHeight] 目标高度
+     */
     drawImage(img, dx, dy, dWidth, dHeight) {
         // 由具体的绘制方法处理
     }
 
-    // 创建 WebglPath 实例
+    /**
+     * 创建 WebglPath 实例
+     * @method createPath
+     * @param {Object} option 路径配置选项
+     * @returns {WebglPath} WebGL 路径对象
+     */
     createPath(option) {
         return new WebglPath(null, option);
     }

package/src/lib/webgl/path.js

@@ -1,22 +1,58 @@
+/**
+ * @fileoverview WebGL 路径绘制类
+ * 
+ * 本模块提供了 WebGL 路径绘制功能，包括：
+ * - 线条绘制（stroke）
+ * - 填充绘制（fill）
+ * - 纹理填充
+ * - 渐变填充
+ * - 文本绘制
+ * - 多边形三角化
+ * 
+ * @module lib/webgl/path
+ * @author jmGraph Team
+ */
 import WebglBase, { MAX_STOPS } from './base.js';
 import earcut from '../earcut.js';
 
-// path 绘制类
+/**
+ * WebGL 路径绘制类
+ * 继承自 WeblBase，提供路径绘制功能
+ * 
+ * @class WebglPath
+ * @extends WeblBase
+ * @example
+ * const path = new WebglPath(graph, { isRegular: false, needCut: true });
+ * path.draw(points);
+ * path.stroke(points, '#ff0000', 2);
+ */
 class WebglPath extends WebglBase {
+    /**
+     * 构造函数
+     * @param {jmGraph} graph jmGraph 实例
+     * @param {Object} option 配置选项
+     * @param {boolean} [option.isRegular=false] 是否为规则图形（凸多边形）
+     * @param {boolean} [option.needCut=false] 是否需要切割处理
+     * @param {Object} [option.control] 控制器对象
+     */
     constructor(graph, option) {
         super(graph, option);
-        // 是否是规则的，不规则的处理方式更为复杂和耗性能
+        /** @type {boolean} 是否为规则图形（凸多边形），规则图形处理更高效 */
         this.isRegular = option.isRegular || false;
+        /** @type {boolean} 是否需要切割处理 */
         this.needCut = option.needCut || false;
         this.control = option.control;
+        /** @type {Array<Object>} 路径点数组 */
         this.points = [];
-        // 缓存 buffer 和纹理，避免每帧创建/销毁
+        /** @type {Array} 缓存的缓冲区，避免每帧创建/销毁 */
         this.__cachedBuffers = [];
+        /** @type {Object} 缓存的纹理 */
         this.__cachedTexture = null;
+        /** @type {string} 缓存纹理的 key */
         this.__cachedTextureKey = null;
     }
 
-    // 释放缓存的 WebGL 资源
+    /** 释放缓存的 WebGL 资源 */
     dispose() {
         for(const buf of this.__cachedBuffers) {
             this.deleteBuffer(buf);
@@ -29,7 +65,12 @@ class WebglPath extends WebglBase {
         }
     }
 
-    // 获取或创建 buffer，优先复用缓存
+    /**
+     * 获取或创建缓冲区，优先复用缓存
+     * @param {Array} data 数据数组
+     * @param {Object} attr 属性对象
+     * @returns {Object} 缓冲区对象
+     */
     getOrCreateBuffer(data, attr) {
         let buffer = this.__cachedBuffers.find(b => b.attr === attr);
         if(buffer) {
@@ -46,11 +87,19 @@ class WebglPath extends WebglBase {
         return buffer;
     }
 
-    // 应用变换到点
+    /**
+     * 应用变换到点
+     * @param {Object} point 点坐标 {x, y}
+     * @returns {Object} 变换后的点坐标
+     */
     applyTransform(point) {
         return super.applyTransform(point);
     }
 
+    /**
+     * 设置父级边界
+     * @param {Object} [parentBounds] 父级边界 {left, top, width, height}
+     */
     setParentBounds(parentBounds = this.parentAbsoluteBounds) {
 
         //this.useProgram();
@@ -104,16 +153,16 @@ class WebglPath extends WebglBase {
     endDraw() {
         if(this.points) delete this.points;
         if(this.pathPoints) delete this.pathPoints;
+        this.needClose = false;
         // 缓存的纹理保留到下次绘制（渐变可能不变）
     }
 
-    // 图形封闭
+    /**
+     * 标记路径需要闭合（不修改原始 points 数组）
+     * 闭合逻辑由 stroke/fill 绘制方法自行处理
+     */
     closePath() {
-        if(this.points && this.points.length > 2 && this.points[0] !== this.points[this.points.length-1]) {
-            const start = this.points[0];
-            const end = this.points[this.points.length-1];
-            if(start != end && !(start.x === end.x && start.y === end.y)) this.points.push(start);
-        }
+        this.needClose = true;
     }
 
     // 绘制点数组（使用 DYNAMIC_DRAW 复用 buffer，避免每帧 create/delete）

package/src/shapes/jmArc.js

@@ -1,11 +1,57 @@
+/**
+ * @fileoverview jmArc 圆弧类
+ * 
+ * jmArc 提供了圆弧图形的绘制功能。
+ * 可以绘制完整的圆、部分圆弧或扇形。
+ * 
+ * 主要功能：
+ * - 圆弧绘制
+ * - 扇形绘制（isFan=true）
+ * - 顺时针/逆时针绘制
+ * - 支持 WebGL 和 Canvas 2D 模式
+ * 
+ * @module jmArc
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmPath} from "../core/jmPath.js";
 
 /**
- * 圆弧图型 继承自jmPath
+ * 圆弧类
+ * 
+ * 绘制圆弧或扇形图形，继承自 jmPath。
+ * 支持设置圆心、半径、起始角度和结束角度。
  *
  * @class jmArc
  * @extends jmPath
- * @param {object} params center=当前圆弧中心,radius=圆弧半径,start=圆弧起始角度,end=圆弧结束角度,anticlockwise=  false  顺时针，true 逆时针
+ * @param {object} params 圆弧参数
+ * @param {object} [params.center] 圆弧中心点 {x, y}
+ * @param {number} [params.radius] 圆弧半径
+ * @param {number} [params.start=0] 圆弧起始角度（弧度）
+ * @param {number} [params.end=Math.PI*2] 圆弧结束角度（弧度）
+ * @param {boolean} [params.anticlockwise=false] 绘制方向：false=顺时针，true=逆时针
+ * @param {boolean} [params.isFan=false] 是否绘制为扇形
+ * 
+ * @example
+ * // 创建圆弧
+ * const arc = graph.createShape('arc', {
+ *     center: {x: 200, y: 200},
+ *     radius: 50,
+ *     start: 0,
+ *     end: Math.PI,
+ *     style: { stroke: '#000' }
+ * });
+ * 
+ * // 创建扇形
+ * const fan = graph.createShape('arc', {
+ *     center: {x: 200, y: 200},
+ *     radius: 50,
+ *     start: 0,
+ *     end: Math.PI / 2,
+ *     isFan: true,
+ *     style: { fill: '#ff0000' }
+ * });
  */
 export default class jmArc extends jmPath {
 

package/src/shapes/jmArrow.js

@@ -1,11 +1,44 @@
+/**
+ * @fileoverview jmArrow 箭头类
+ * 
+ * jmArrow 提供了箭头图形的绘制功能。
+ * 可以单独使用，也可以与直线组合使用。
+ * 
+ * 主要功能：
+ * - 箭头绘制
+ * - 支持空心和实心箭头
+ * - 自定义箭头大小和角度
+ * 
+ * @module jmArrow
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmPath} from "../core/jmPath.js";
 import {jmUtils} from "../core/jmUtils.js";
+
 /**
- * 画箭头,继承自jmPath
+ * 箭头类
+ * 
+ * 绘制箭头图形，支持空心和实心两种样式。
+ * 箭头方向由起点和终点决定。
  *
  * @class jmArrow
  * @extends jmPath
- * @param {object} 生成箭头所需的参数
+ * @param {object} params 箭头参数
+ * @param {object} [params.start] 箭头起始点 {x, y}
+ * @param {object} [params.end] 箭头终点（箭头尖端）{x, y}
+ * @param {number} [params.angle] 箭头角度（弧度），不指定则自动计算
+ * @param {number} [params.offsetX=5] 箭头X方向偏移量
+ * @param {number} [params.offsetY=8] 箭头Y方向偏移量
+ * 
+ * @example
+ * // 创建箭头
+ * const arrow = graph.createShape('arrow', {
+ *     start: {x: 100, y: 100},
+ *     end: {x: 200, y: 100},
+ *     style: { fill: '#ff0000', stroke: '#000' }
+ * });
  */
 export default class jmArrow extends jmPath {	
 

package/src/shapes/jmArrowLine.js

@@ -1,11 +1,42 @@
+/**
+ * @fileoverview jmArrowLine 带箭头的直线类
+ * 
+ * jmArrowLine 提供了带箭头直线的绘制功能。
+ * 继承自 jmLine，在直线末端添加箭头。
+ * 
+ * 主要功能：
+ * - 带箭头的直线绘制
+ * - 支持虚线模式
+ * - 可控制箭头显示
+ * 
+ * @module jmArrowLine
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmLine} from "./jmLine.js";
 import {jmArrow} from "./jmArrow.js";
+
 /**
- * 带箭头的直线,继承jmPath
+ * 带箭头的直线类
+ * 
+ * 绘制带箭头的直线，继承自 jmLine。
+ * 箭头位于直线的末端。
  *
  * @class jmArrowLine
  * @extends jmLine
- * @param {object} params 生成当前直线的参数对象，(style=当前线条样式,start=直线起始点,end=直线终结点)
+ * @param {object} params 直线参数
+ * @param {object} [params.start] 直线起始点 {x, y}
+ * @param {object} [params.end] 直线终结点 {x, y}
+ * @param {boolean} [params.arrowVisible=true] 是否显示箭头
+ * 
+ * @example
+ * // 创建带箭头的直线
+ * const arrowLine = graph.createShape('arrowLine', {
+ *     start: {x: 100, y: 100},
+ *     end: {x: 200, y: 100},
+ *     style: { stroke: '#000', lineWidth: 2 }
+ * });
  */	
 export default class jmArrowLine extends jmLine {	
 

package/src/shapes/jmBezier.js

@@ -1,17 +1,63 @@
+/**
+ * @fileoverview jmBezier 贝塞尔曲线类
+ * 
+ * jmBezier 提供了 N 阶贝塞尔曲线的绘制功能。
+ * 通过控制点定义曲线形状，支持任意阶数的贝塞尔曲线。
+ * 
+ * 主要功能：
+ * - N 阶贝塞尔曲线
+ * - 控制点管理
+ * - 曲线平移
+ * 
+ * @module jmBezier
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmPath} from "../core/jmPath.js";
+
 /**
- * 贝塞尔曲线,继承jmPath
- * N阶，参数points中为控制点
+ * 贝塞尔曲线类
+ * 
+ * 绘制 N 阶贝塞尔曲线，参数 points 中为控制点。
+ * 支持 2 阶（二次贝塞尔）、3 阶（三次贝塞尔）及更高阶曲线。
  *
  * @class jmBezier
  * @extends jmPath
  * @param {object} params 参数
+ * @param {array} [params.points] 控制点数组 [{x, y}, ...]
+ * 
+ * @example
+ * // 创建二次贝塞尔曲线（3个控制点）
+ * const quadBezier = graph.createShape('bezier', {
+ *     points: [
+ *         {x: 100, y: 100},  // 起点
+ *         {x: 200, y: 50},   // 控制点
+ *         {x: 300, y: 100}   // 终点
+ *     ],
+ *     style: { stroke: '#000', lineWidth: 2 }
+ * });
+ * 
+ * // 创建三次贝塞尔曲线（4个控制点）
+ * const cubicBezier = graph.createShape('bezier', {
+ *     points: [
+ *         {x: 100, y: 100},  // 起点
+ *         {x: 150, y: 50},   // 控制点1
+ *         {x: 250, y: 50},   // 控制点2
+ *         {x: 300, y: 100}   // 终点
+ *     ],
+ *     style: { stroke: '#ff0000' }
+ * });
  */ 
 export default class jmBezier extends jmPath {	
 	
 	constructor(params, t='jmBezier') {
-		// 典线默认不封闭
-		if(params.style && typeof params.style.close !== true) {
+		// 参数初始化
+		params = params || {};
+		
+		// 曲线默认不封闭
+		if(!params.style) params.style = {};
+		if(typeof params.style.close !== true) {
 			params.style.close = false;
 		}
 

package/src/shapes/jmCircle.js

@@ -1,10 +1,43 @@
+/**
+ * @fileoverview jmCircle 圆形类
+ * 
+ * jmCircle 提供了圆形图形的绘制功能。
+ * 继承自 jmArc，可以绘制完整的圆或部分圆弧。
+ * 
+ * 主要功能：
+ * - 圆形绘制
+ * - 支持填充和描边
+ * - 支持 WebGL 和 Canvas 2D 模式
+ * 
+ * @module jmCircle
+ * @author jmGraph Team
+ * @license MIT
+ */
+
 import {jmArc} from "./jmArc.js";
+
 /**
- * 画规则的圆弧
+ * 圆形类
+ * 
+ * 绘制圆形图形，继承自 jmArc。
+ * 可以通过 center 和 radius 指定圆心和半径，
+ * 也可以通过 width 和 height 指定圆的尺寸。
  *
  * @class jmCircle
  * @extends jmArc
- * @param {object} params 圆的参数:center=圆中心,radius=圆半径,优先取此属性，如果没有则取宽和高,width=圆宽,height=圆高
+ * @param {object} params 圆的参数
+ * @param {object} [params.center] 圆心坐标 {x, y}
+ * @param {number} [params.radius] 圆半径（优先使用）
+ * @param {number} [params.width] 圆宽度（无 radius 时使用）
+ * @param {number} [params.height] 圆高度（无 radius 时使用）
+ * 
+ * @example
+ * // 创建圆形
+ * const circle = graph.createShape('circle', {
+ *     center: {x: 200, y: 200},
+ *     radius: 50,
+ *     style: { fill: '#ff0000', stroke: '#000' }
+ * });
  */
 export default class jmCircle extends jmArc {