vislite 1.9.1 → 1.10.0

package/types/Matrix4.d.ts

@@ -1,47 +1,79 @@
+/**
+ * 4x4矩阵类型定义
+ * 用于实现3D变换矩阵的各种操作，包括平移、旋转、缩放等
+ */
 export default interface Matrix4Type {
 
     /**
-     * 返回matrix4当前记录的内部矩阵
+     * 获取当前矩阵的内部数值表示
+     * @returns 返回4x4矩阵的16个元素，按列优先顺序排列
      */
     value(): number[]
 
     /**
-     * 两个矩阵相乘
-     * @param newMatrix4
-     * @param flag 可选，表示相乘位置，默认false，表示左乘
+     * 矩阵乘法运算
+     * @param newMatrix4 要相乘的矩阵
+     * @param flag 可选参数，表示相乘位置。默认为false，表示左乘（newMatrix4 * this）；为true时表示右乘（this * newMatrix4）
+     * @returns 返回当前实例，支持链式调用
      */
     multiply(newMatrix4: number[], flag?: boolean): this
 
     /**
-     * 把变换矩阵作用在具体的点上
+     * 将变换矩阵应用于指定坐标点
+     * @param x x坐标
+     * @param y y坐标
+     * @param z z坐标，可选，默认为0
+     * @param w w坐标，可选，默认为1
+     * @returns 变换后的四维坐标 [x', y', z', w']
      */
     use(x: number, y: number, z?: number, w?: number): [number, number, number, number]
 
     /**
-     * 设置内置矩阵
+     * 设置矩阵的初始值
+     * @param initMatrix4 可选的初始矩阵值，如果不提供则使用单位矩阵
+     * @returns 返回当前实例，支持链式调用
      */
     setValue(initMatrix4?: number[]): this
 
     /**
-     * 沿着向量(a, b, c)方向移动距离dis
-     * （其中c可以不传，默认0）
+     * 沿指定向量方向平移
+     * @param dis 平移距离
+     * @param a 向量x分量
+     * @param b 向量y分量
+     * @param c 向量z分量，可选，默认为0
+     * @returns 返回当前实例，支持链式调用
      */
     move(dis: number, a: number, b: number, c?: number): this
 
     /**
-     * 以点(cx, cy, cz)为中心，分别在x、y和z方向上缩放xTimes、yTimes和zTimes倍
-     * （其中cx、cy和cz都可以不传递，默认0）
+     * 以指定点为中心进行缩放
+     * @param xTimes x方向缩放倍数
+     * @param yTimes y方向缩放倍数
+     * @param zTimes z方向缩放倍数
+     * @param cx 中心点x坐标，可选，默认为0
+     * @param cy 中心点y坐标，可选，默认为0
+     * @param cz 中心点z坐标，可选，默认为0
+     * @returns 返回当前实例，支持链式调用
      */
     scale(xTimes: number, yTimes: number, zTimes: number, cx?: number, cy?: number, cz?: number): this
 
     /**
-     * 围绕射线(a1, b1, c1) -> (a2, b2, c2)旋转deg度
-     * （方向由右手法则确定）
+     * 围绕指定射线旋转
+     * @param deg 旋转角度（度）
+     * @param a1 射线起点x坐标
+     * @param b1 射线起点y坐标
+     * @param c1 射线起点z坐标，可选
+     * @param a2 射线终点x坐标，可选
+     * @param b2 射线终点y坐标，可选
+     * @param c2 射线终点z坐标，可选
      *
-     * a1、b1、c1、a2、b2和c2这六个值在设置的时候，不是一定需要全部设置，还有以下可选：
+     * 参数说明：
+     * 1）只设置a1和b1：表示在xoy平面围绕点(a1, b1)旋转
+     * 2）设置三个点（不足六个点）：表示围绕从原点出发的射线旋转
+     * 3）设置六个点：表示围绕指定射线旋转
      *
-     *      1）只设置了a1和b1，表示在xoy平面围绕（a1, b1）旋转
-     *      2）设置三个点(设置不足六个点都认为只设置了三个点)，表示围绕从原点出发的射线旋转
+     * 旋转方向由右手法则确定
+     * @returns 返回当前实例，支持链式调用
      */
     rotate(deg: number, a1: number, b1: number, c1?: number, a2?: number, b2?: number, c2?: number): this
 

package/types/SVG.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SVG绘图类型定义
+ * 提供SVG绘图的各种方法和功能
+ */
 import SVGConfigType from './SVGConfig'
 import GradientType from "./Gradient"
 

package/types/SVGConfig.d.ts

@@ -1,72 +1,55 @@
 import { arcCapType, textAlignType, textBaselineType, lineCapType, lineJoinType } from './painterConfig'
 
+/** SVG元素类型定义 */
 export type svgElType = SVGElement | "g" | "text" | "path" | "circle" | "rect" | "polygon" | "polyline"
+/** SVG绘图板类型定义 */
 export type svgBoardType = SVGElement | "text" | "path" | "arc" | "circle" | "rect"
 
+/**
+ * SVG配置类型定义
+ * 用于配置SVG绘图的各种样式和属性
+ */
 export default interface SVGConfigType {
 
-    /**
-     * 填充色或图案，默认"#000"
-     */
+    /** 填充色或图案，默认"#000" */
     fillStyle?: string
 
-    /**
-     * 轮廓色或图案，默认"#000"
-     */
+    /** 轮廓色或图案，默认"#000" */
     strokeStyle?: string
 
-    /**
-     * 线条宽度，默认1(单位px)
-     */
+    /** 线条宽度，默认1(单位px) */
     lineWidth?: number
 
-    /**
-     * 线的端点类型，默认"butt"平直边缘（还有"round"半圆和"square"矩形）
-     */
+    /** 线的端点类型，默认"butt"平直边缘（还有"round"半圆和"square"矩形） */
     lineCap?: lineCapType
 
-    /**
-     * 线的拐角连接方式，默认"miter"连接处边缘延长相接（还有"bevel"对角线斜角和"round"圆）
-     */
+    /** 线的拐角连接方式，默认"miter"连接处边缘延长相接（还有"bevel"对角线斜角和"round"圆） */
     lineJoin?: lineJoinType
 
     /**
      * 设置线条虚线，默认为[]表示使用实线绘制
-     *
      * 值应该是一个数组，格式：[实线长，虚线长，实线长 ...]，数组长度任意，会自动循环
      */
     lineDash?: Array<number>
 
-    /**
-     * 文字水平对齐方式，默认"left"左对齐（还有"center"居中和"right"右对齐）
-     */
+    /** 文字水平对齐方式，默认"left"左对齐（还有"center"居中和"right"右对齐） */
     textAlign?: textAlignType
 
-    /**
-     * 文字垂直对齐方式，默认"middle"垂直居中（还有"top"上对齐和"bottom"下对齐）
-     */
+    /** 文字垂直对齐方式，默认"middle"垂直居中（还有"top"上对齐和"bottom"下对齐） */
     textBaseline?: textBaselineType
 
-    /**
-     * 文字大小，默认16
-     */
+    /** 文字大小，默认16 */
     fontSize?: number
 
-    /**
-     * 字体，默认"sans-serif"
-     */
+    /** 字体，默认"sans-serif" */
     fontFamily?: string
 
-    /**
-     * 圆弧开始端闭合方式，默认"butt"直线闭合（还有"round"圆帽闭合,"-round"反圆帽闭合）
-     */
+    /** 圆弧开始端闭合方式，默认"butt"直线闭合（还有"round"圆帽闭合,"-round"反圆帽闭合） */
     arcStartCap?: arcCapType
 
-    /**
-     * 圆弧结束端闭合方式，默认"butt"直线闭合（还有"round"圆帽闭合,"-round"反圆帽闭合）
-     */
+    /** 圆弧结束端闭合方式，默认"butt"直线闭合（还有"round"圆帽闭合,"-round"反圆帽闭合） */
     arcEndCap?: arcCapType
 
-    // 矩形圆角半径
+    /** 矩形圆角半径 */
     rectRadius?: Array<number>
 }

package/types/Shader.d.ts

@@ -1,17 +1,23 @@
+/**
+ * 着色器类型定义
+ * 用于WebGL着色器的编译和使用
+ */
 export default interface ShaderType {
 
+    /** 着色器程序对象 */
     program: WebGLProgram
 
     /**
-     * 使用这个程序
-     * （后于编译）
+     * 使用这个着色器程序
+     * @returns 返回当前实例，支持链式调用
      */
     use(): this
 
     /**
      * 编译着色器程序
-     * @param vshaderSource 顶点着色器
-     * @param fshaderSource 片段（元）着色器
+     * @param vshaderSource 顶点着色器源码
+     * @param fshaderSource 片段着色器源码
+     * @returns 返回当前实例，支持链式调用
      */
     compile(vshaderSource: string, fshaderSource: string): this
 }

package/types/Texture.d.ts

@@ -1,16 +1,22 @@
+/**
+ * WebGL纹理类型定义
+ * 用于管理WebGL中的纹理资源
+ */
 export default interface TextureType {
 
     /**
-     * 链接图片资源(单一)
-     * @param image 纹理图片
+     * 绑定单一图片作为纹理
+     * @param image 纹理图片资源
+     * @returns 返回当前实例，支持链式调用
      */
     useImage(image: TexImageSource): this
 
     /**
-     * 链接图片资源（多张）
-     * @param images 纹理图片集
-     * @param width 图片宽
-     * @param height 图片高
+     * 绑定立方体贴图纹理
+     * @param images 纹理图片数组（6张图片）
+     * @param width 图片宽度
+     * @param height 图片高度
+     * @returns 返回当前实例，支持链式调用
      */
     useCube(images: TexImageSource[], width: number, height: number): this
 

package/types/TreeConfig.d.ts

@@ -1,37 +1,53 @@
+/**
+ * 获取根节点函数类型定义
+ */
 export interface rootType {
+    /**
+     * 获取根节点
+     * @param initTree 原始树数据
+     * @returns 返回根节点
+     */
     (initTree: any): any
 }
 
+/**
+ * 获取子节点函数类型定义
+ */
 export interface childrenType {
+    /**
+     * 获取子节点数组
+     * @param parentTree 父节点
+     * @param initTree 原始树数据
+     * @returns 返回子节点数组
+     */
     (parentTree: any, initTree: any): any[]
 }
 
+/**
+ * 获取节点ID函数类型定义
+ */
 export interface idType {
+    /**
+     * 获取节点唯一标识
+     * @param treedata 节点数据
+     * @returns 返回节点唯一ID
+     */
     (treedata: any): string
 }
 
+/**
+ * 树布局配置类型定义
+ * 用于配置树形布局的各种参数和方法
+ */
 export default interface TreeConfigType {
 
-    /**
-     * 获取根结点的方法
-     * @param initTree 原始数据
-     * @returns 返回根结点
-     */
+    /** 获取根节点的方法 */
     root?: rootType
 
-    /**
-     * 获取子结点的方法
-     * @param parentTree 父结点
-     * @param initTree 原始数据
-     * @returns 返回当前父结点的所有子结点数组
-     */
+    /** 获取子节点的方法 */
     children?: childrenType
 
-    /**
-     * 获取结点ID方法
-     * @param treedata 当前结点
-     * @returns 返回可以唯一标识当前结点的id
-     */
+    /** 获取节点ID方法 */
     id?: idType
 
 }

package/types/TreeLayout.d.ts

@@ -2,58 +2,70 @@ import TreeType from "./Tree"
 import { TreeResultType } from "./Tree"
 import TreeOptionType from './TreeOption'
 
+/**
+ * 树布局类型定义
+ * 继承自TreeType，提供树形布局的计算和操作功能
+ */
 export default interface TreeLayoutType extends TreeType {
 
     /**
      * 设置布局的行为
-     * @param option
+     * @param option 布局选项
+     * @returns 返回当前实例，支持链式调用
      */
     setOption(option: TreeOptionType): this
 
     /**
-     * 单纯的树图坐标计算
-     * @param initTree 原始数据
-     * @param noOpens 可选，结点初始是否闭合控制
+     * 计算树图坐标
+     * @param initTree 原始树数据
+     * @param noOpens 可选，节点初始是否闭合控制
+     * @returns 返回计算后的树结构数据
      */
     use(initTree: any, noOpens?: {
         [id: string]: boolean
     }): TreeResultType
 
     /**
-     * 绑定新的数据和渲染方法
-     * @param initTree 原始数据
-     * @param renderBack 渲染方法
-     * @param noOpens 可选，结点初始是否闭合控制
+     * 绑定数据和渲染方法
+     * @param initTree 原始树数据
+     * @param renderBack 渲染回调函数
+     * @param noOpens 可选，节点初始是否闭合控制
+     * @returns 返回当前实例，支持链式调用
      */
     bind(initTree: any, renderBack: (tree: TreeResultType) => void, noOpens?: {
         [id: string]: boolean
     }): this
 
     /**
-     * 解除绑定
+     * 解除数据绑定
+     * @returns 返回当前实例，支持链式调用
      */
     unbind(): this
 
     /**
      * 闭合指定节点
-     * @param id
+     * @param id 节点ID
+     * @returns 返回当前实例，支持链式调用
      */
     closeNode(id: string): this
 
     /**
      * 展开指定节点
-     * @param id
+     * @param id 节点ID
+     * @returns 返回当前实例，支持链式调用
      */
     openNode(id: string): this
 
     /**
-     * 闭合或展开指定节点
-     * @param id
+     * 切换指定节点的展开/闭合状态
+     * @param id 节点ID
+     * @returns 返回当前实例，支持链式调用
      */
     toggleNode(id: string): this
 
     /**
      * 主动触发绘制更新
+     * @returns 返回当前实例，支持链式调用
      */
     doUpdate(): this
 

package/types/animation.d.ts

@@ -1,8 +1,23 @@
+/**
+ * 动画回调函数类型定义
+ * @param deep 动画进度值，范围0-1
+ */
 interface animationFun {
     (deep: number): void
 }
 
+/**
+ * 动画函数类型定义
+ * 用于创建平滑的动画效果
+ */
 interface animationType {
+    /**
+     * 执行动画
+     * @param doback 动画执行函数，接收一个0-1之间的进度值
+     * @param duration 动画持续时间（毫秒），可选，默认为500ms
+     * @param callback 动画完成后的回调函数，可选
+     * @returns 返回一个函数，调用该函数可提前结束动画
+     */
     (doback: animationFun, duration?: number, callback?: animationFun): Function
 }
 

package/types/assemble.d.ts

@@ -1,6 +1,15 @@
 /**
- * 步进生成器
+ * 步进生成器函数类型定义
+ * 用于生成步进序列数据
  */
 export default interface assembleType {
+    /**
+     * 创建步进序列生成器
+     * @param begin 起始值
+     * @param end 结束值
+     * @param step 步长
+     * @param count 元素个数
+     * @returns 返回一个生成器函数，调用后返回数组
+     */
     (begin: number, end: number, step: number, count: number): () => Array<number>
 }

package/types/getLoopColors.d.ts

@@ -1,6 +1,14 @@
 /**
- * 获取一组循环色彩
+ * 循环颜色获取函数类型定义
+ * 用于生成指定数量的循环色彩数组
  */
 export default interface getLoopColorsType {
+    /**
+     * 生成循环色彩数组
+     * @param num 需要生成的颜色数量
+     * @param alpha 颜色透明度，可选，默认为1
+     * @param colorsFactory 自定义颜色工厂函数，可选
+     * @returns 返回生成的颜色数组
+     */
     (num: number, alpha?: number, colorsFactory?: (alpha: number) => Array<string>): string[]
 }

package/types/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * VISLite 主类型定义文件
+ * 包含所有核心组件的类型定义
+ */
+
 /// <reference path="./uni-canvas.d.ts" />
 /// <reference path="./module.d.ts" />
 
@@ -42,7 +47,7 @@ import BarLayoutType from './BarLayout'
 
 import { initOptionType, mergeOptionType } from './option'
 
-// 插值
+// 插值构造函数类型
 interface NewCardinalType extends CardinalType {
     new(t?: number): CardinalType
 }
@@ -50,12 +55,12 @@ interface NewHermiteType extends HermiteType {
     new(u?: number): HermiteType
 }
 
-// 变换
+// 变换构造函数类型
 interface NewMatrix4Type extends Matrix4Type {
     new(initMatrix4?: number[]): Matrix4Type
 }
 
-// 画笔
+// 画笔构造函数类型
 interface NewSVGType extends SVGType {
     new(el: HTMLElement | null): SVGType
 }
@@ -66,7 +71,7 @@ interface NewRawCanvasType extends CanvasType {
     new(canvas: any, region?: any, scaleSize?: number): CanvasType
 }
 
-// WebGL
+// WebGL构造函数类型
 interface NewShaderType extends ShaderType {
     new(painter: WebGLRenderingContext): ShaderType
 }
@@ -77,7 +82,7 @@ interface NewTextureType extends TextureType {
     new(painter: WebGLRenderingContext, type: string, unit?: number): TextureType
 }
 
-// 投影
+// 投影构造函数类型
 interface NewEoapType extends MapType {
     new(scale?: number, center?: number[]): MapType
 }
@@ -85,12 +90,12 @@ interface NewMercatorType extends MapType {
     new(scale?: number, center?: number[]): MapType
 }
 
-// 坐标系
+// 坐标系构造函数类型
 interface NewMapCoordinateType extends MapCoordinateType {
     new(config?: MapConfigType): MapCoordinateType
 }
 
-// 布局
+// 布局构造函数类型
 interface NewTreeLayoutType extends TreeLayoutType {
     new(config?: TreeConfigType): TreeLayoutType
 }
@@ -101,97 +106,117 @@ interface NewBarLayoutType extends BarLayoutType {
     new(config?: BarConfigType): BarLayoutType
 }
 
+/**
+ * VISLite 主类
+ * 提供所有核心功能的静态访问入口
+ */
 export default class VISLite {
 
-    // 插值
+    /** Cardinal插值函数 */
     static Cardinal: NewCardinalType
+    /** Hermite插值函数 */
     static Hermite: NewHermiteType
 
-    // 变换
+    /** 4x4矩阵变换 */
     static Matrix4: NewMatrix4Type
+    /** 旋转变换函数 */
     static rotate: rotateType
+    /** 平移变换函数 */
     static move: moveType
+    /** 缩放变换函数 */
     static scale: scaleType
 
-    // 工具
+    /** 循环颜色获取函数 */
     static getLoopColors: getLoopColorsType
+    /** 动画函数 */
     static animation: animationType
+    /** 刻度尺计算函数 */
     static ruler: rulerType
 
-    // 画笔
+    /** SVG绘图类 */
     static SVG: NewSVGType
+    /** Canvas绘图类 */
     static Canvas: NewCanvasType
+    /** 原始Canvas绘图类 */
     static RawCanvas: NewRawCanvasType
 
-    // WebGL
+    /** WebGL上下文获取函数 */
     static getWebGLContext: getWebGLContextType
+    /** WebGL着色器类 */
     static Shader: NewShaderType
+    /** WebGL缓冲区类 */
     static Buffer: NewBufferType
+    /** WebGL纹理类 */
     static Texture: NewTextureType
 
-    // 投影
+    /** Eoap投影类 */
     static Eoap: NewEoapType
+    /** Mercator投影类 */
     static Mercator: NewMercatorType
 
-    // 辅助
+    /** 节流函数 */
     static throttle: throttleType
+    /** 数据组装函数 */
     static assemble: assembleType
 
-    // 坐标系
+    /** 地图坐标系类 */
     static MapCoordinate: NewMapCoordinateType
 
-    // 布局
+    /** 树形布局类 */
     static TreeLayout: NewTreeLayoutType
+    /** 饼图布局类 */
     static PieLayout: NewPieLayoutType
+    /** 柱状图布局类 */
     static BarLayout: NewBarLayoutType
 
-    // 配置项
+    /** 配置项初始化函数 */
     static initOption: initOptionType
+    /** 配置项合并函数 */
     static mergeOption: mergeOptionType
 }
 
-// 插值
+// 插值函数导出
 export let Cardinal: NewCardinalType
 export let Hermite: NewHermiteType
 
-// 变换
+// 变换函数导出
 export let Matrix4: NewMatrix4Type
 export let rotate: rotateType
 export let move: moveType
 export let scale: scaleType
 
-// 工具
+// 工具函数导出
 export let getLoopColors: getLoopColorsType
 export let animation: animationType
 export let ruler: rulerType
 
-// 画笔
+// 画笔类导出
 export let SVG: NewSVGType
 export let Canvas: NewCanvasType
 export let RawCanvas: NewRawCanvasType
 
-// WebGL
+// WebGL相关导出
 export let getWebGLContext: getWebGLContextType
 export let Shader: NewShaderType
 export let Buffer: NewBufferType
 export let Texture: NewTextureType
 
-// 投影
+// 投影类导出
 export let Eoap: NewEoapType
 export let Mercator: NewMercatorType
 
-// 辅助
+// 辅助函数导出
 export let throttle: throttleType
 export let assemble: assembleType
 
-// 坐标系
+// 坐标系类导出
 export let MapCoordinate: NewMapCoordinateType
 
-// 布局
+// 布局类导出
 export let TreeLayout: NewTreeLayoutType
 export let PieLayout: NewPieLayoutType
 export let BarLayout: NewBarLayoutType
 
-// 配置项
+// 配置项函数导出
 export let initOption: initOptionType
 export let mergeOption: mergeOptionType

package/types/move.d.ts

@@ -1,6 +1,16 @@
 /**
- * 移动
+ * 平移变换函数类型定义
+ * 用于计算二维坐标系中的平移变换
  */
 export default interface moveType {
+    /**
+     * 计算平移后的坐标
+     * @param ax 平移向量的x分量
+     * @param ay 平移向量的y分量
+     * @param d 平移距离
+     * @param x 原始点的x坐标
+     * @param y 原始点的y坐标
+     * @returns 返回平移后的坐标 [newX, newY]
+     */
     (ax: number, ay: number, d: number, x: number, y: number): [number, number]
 }