vislite 1.10.0 → 1.11.0

package/skills/vislite-lib/Projections.md

@@ -0,0 +1,159 @@
+# 坐标投影 API
+
+VISLite 提供多种地图坐标投影算法，用于地图可视化开发。
+
+## Mercator 墨卡托投影
+
+墨卡托投影是航海和航空中常用的投影方式。
+
+### 引入
+
+```js
+import { Mercator } from 'vislite';
+```
+
+### 初始化
+
+```js
+var mercator = new Mercator(scale, center);
+```
+
+### 参数说明
+
+- **scale**: 缩放比例，默认7
+- **center**: 投影中心经纬度 `[经度, 纬度]`，默认 `[107, 36]`（中国中心附近）
+
+### 使用方法
+
+```js
+var mercator = new Mercator(7, [107, 36]);
+
+// 将经纬度转换为平面坐标
+var [x, y, z] = mercator.use(经度, 纬度);
+```
+
+### 使用示例
+
+```js
+var mercator = new Mercator(7, [116.4, 39.2]); // 北京
+
+// 北京的经纬度
+var [x, y] = mercator.use(116.4, 39.2);
+console.log(x, y); // 输出平面坐标
+```
+
+---
+
+## Eoap 等角斜方位投影
+
+等角斜方位投影是一种适合显示以某点为中心区域的投影方式。
+
+### 引入
+
+```js
+import { Eoap } from 'vislite';
+```
+
+### 初始化
+
+```js
+var eoap = new Eoap(scale, center);
+```
+
+### 参数说明
+
+- **scale**: 缩放比例，默认7
+- **center**: 投影中心经纬度 `[经度, 纬度]`，默认 `[107, 36]`
+
+### 使用方法
+
+```js
+var eoap = new Eoap(7, [116.4, 39.2]);
+
+// 将经纬度转换为平面坐标
+var [x, y, z] = eoap.use(经度, 纬度);
+```
+
+### 特点
+
+- 以投影中心为原点，周围的区域变形较小
+- 适合绘制局部地图（如某个国家或城市）
+- 保持了角度的正确性
+
+---
+
+## MapCoordinate 地图坐标系
+
+MapCoordinate 用于处理地图坐标转换和边界计算。
+
+### 引入
+
+```js
+import { MapCoordinate } from 'vislite';
+```
+
+### 初始化
+
+```js
+var mapCoord = new MapCoordinate(projection, option);
+```
+
+### 参数说明
+
+- **projection**: 投影对象（Mercator 或 Eoap）
+- **option**: 配置项
+  - `width`, `height`: 画布尺寸
+  - `x`, `y`: 偏移量
+
+### 主要功能
+
+```js
+// 经纬度转屏幕坐标
+mapCoord.lonlatToScreen(lon, lat);
+
+// 屏幕坐标转经纬度
+mapCoord.screenToLonlat(x, y);
+
+// 获取地图边界
+mapCoord.getBoundary();
+```
+
+### 使用示例
+
+```js
+var mercator = new Mercator(7, [107, 36]);
+var mapCoord = new MapCoordinate(mercator, {
+    width: 800,
+    height: 600
+});
+
+// 绘制地图
+geoJson.features.forEach(feature => {
+    feature.geometry.coordinates.forEach(polygon => {
+        painter.beginPath();
+        polygon[0].forEach((point, i) => {
+            var [x, y] = mapCoord.lonlatToScreen(point[0], point[1]);
+            if (i === 0) painter.moveTo(x, y);
+            else painter.lineTo(x, y);
+        });
+        painter.closePath().fill();
+    });
+});
+```
+
+---
+
+## 投影对比
+
+| 特性 | Mercator | Eoap |
+|------|----------|------|
+| 适用场景 | 全球航海图 | 局部区域图 |
+| 中心点 | 固定赤道 | 可自定义 |
+| 变形 | 高纬度变形大 | 中心区域变形小 |
+| 角度 | 保持方向 | 保持角度 |
+
+## 选择建议
+
+- **全球地图或航海图**: 使用 Mercator
+- **某个国家/城市的局部图**: 使用 Eoap
+- **复杂地图交互**: 使用 MapCoordinate 配合投影

package/skills/vislite-lib/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: vislite-lib
+description: "VISLite数据可视化库开发助手。当用户需要创建Canvas/SVG/WebGL图表、实现树布局/饼图/柱状图布局、使用坐标投影（墨卡托/等角斜方位）、矩阵变换、插值函数等可视化算法时使用。"
+---
+
+# VISLite 数据可视化库
+
+VISLite 是一款轻量、优雅的跨端数据可视化解决方案，支持 Web、uni-app、微信小程序、支付宝小程序等多平台。
+
+**官网**: [https://oi-contrib.github.io/VISLite](https://oi-contrib.github.io/VISLite)
+
+**GitHub**: [https://github.com/oi-contrib/VISLite](https://github.com/oi-contrib/VISLite)
+
+## 安装
+
+```bash
+npm install --save vislite
+```
+
+## 模块索引
+
+### 画笔 (Brushes)
+
+#### 跨平台 Canvas（H5 / 微信 / 支付宝 / uni-app）
+- [Canvas.md](Canvas.md) - 统一 API，初始化方式因平台而异
+- [minialipay/ui-canvas.md](minialipay/ui-canvas.md) - 支付宝小程序 Canvas 组件
+- [miniprogram/ui-canvas.md](miniprogram/ui-canvas.md) - 微信小程序 Canvas 组件
+- [uniapp/ui-canvas.md](uniapp/ui-canvas.md) - uni-app 跨平台使用指南
+
+#### H5 专用画笔
+- [SVG.md](SVG.md) - SVG 矢量图形绘制（仅 H5）
+- [WebGL.md](WebGL.md) - WebGL 3D 图形渲染（仅 H5）
+
+### 布局算法 (Layouts)
+
+- [TreeLayout.md](TreeLayout.md) - 树状布局，支持 TB/LR/RL/BT 方向
+- [PieLayout.md](PieLayout.md) - 饼图/环形图布局
+- [BarLayout.md](BarLayout.md) - 柱状图/条形图布局
+
+### 坐标投影 (Projections)
+
+- [Projections.md](Projections.md) - Mercator 墨卡托投影、Eoap 等角斜方位投影、MapCoordinate 地图坐标系
+
+### 变换与插值
+
+- [Matrix.md](Matrix.md) - 4x4 矩阵变换（平移/旋转/缩放）
+- [Interpolation.md](Interpolation.md) - Cardinal/Hermite 三次插值函数
+
+### 工具函数
+
+- [Utilities.md](Utilities.md) - ruler 刻度尺、animation 动画、getLoopColors 循环颜色、throttle 节流
+
+## 画笔平台支持说明
+
+| 画笔 | H5 | 微信小程序 | 支付宝小程序 | uni-app |
+|------|-----|-----------|-------------|----------|
+| Canvas | ✅ `new Canvas(el)` | ✅ 组件方式 | ✅ 组件方式 | ✅ 组件方式 |
+| SVG | ✅ `new SVG(el)` | ❌ | ❌ | ❌ |
+| WebGL | ✅ `getWebGLContext()` | ❌ | ❌ | ❌ |
+| RawCanvas | ✅ | ✅ | ✅ | ✅ |
+
+**注意**: SVG 和 WebGL 仅支持 H5 端。Canvas 在不同平台的 API 完全一致，但初始化方式不同：
+- **H5**: `new Canvas(domElement)`
+- **小程序**: 通过 ui-canvas 组件的 `fetch()` 方法获取实例
+
+## 快速使用
+
+### H5 端使用 Canvas
+
+```js
+import { Canvas } from 'vislite';
+
+var painter = new Canvas(document.getElementById('root'));
+
+painter.config({
+    fillStyle: "red"
+}).fillCircle(200, 150, 100);
+
+// 设置区域用于交互
+painter.setRegion('circle');
+painter.bind('click', (regionName, x, y) => {
+    console.log(regionName, x, y);
+});
+```
+
+### 小程序端使用 Canvas
+
+详见各小程序平台的文档：
+- [微信小程序 Canvas](miniprogram/ui-canvas.md)
+- [支付宝小程序 Canvas](minialipay/ui-canvas.md)
+- [uni-app Canvas](uniapp/ui-canvas.md)
+
+### 树布局
+
+```js
+import { Canvas, TreeLayout } from 'vislite';
+
+var treeLayout = new TreeLayout();
+treeLayout.setOption({
+    type: "rect",
+    direction: "TB",
+    x: 250,
+    y: 20,
+    width: 500,
+    height: 260
+});
+
+var tree = treeLayout.use(data);
+
+// 绘制连线
+for (var key in tree.node) {
+    var pid = tree.node[key].pid;
+    if (pid) {
+        painter.beginPath()
+            .moveTo(tree.node[key].left, tree.node[key].top)
+            .bezierCurveTo(...)
+            .stroke();
+    }
+}
+
+// 绘制节点
+painter.fullCircle(tree.node[key].left, tree.node[key].top, 10);
+```
+
+## 核心导出
+
+```js
+import {
+    // 画笔
+    Canvas,          // 跨平台（初始化方式不同）
+    SVG,             // 仅 H5
+    RawCanvas,       // 跨平台
+
+    // 布局
+    TreeLayout,
+    PieLayout,
+    BarLayout,
+
+    // 投影
+    Mercator,
+    Eoap,
+    MapCoordinate,
+
+    // 变换
+    Matrix4,
+    rotate,
+    move,
+    scale,
+
+    // 插值
+    Cardinal,
+    Hermite,
+
+    // 工具
+    ruler,
+    animation,
+    getLoopColors,
+    throttle,
+    assemble,
+
+    // WebGL（仅 H5）
+    getWebGLContext,
+    Shader,
+    Texture,
+    Buffer
+} from 'vislite';
+```
+
+## 典型场景
+
+- 创建跨平台图表（柱状图、饼图、树图）
+- 地图可视化（墨卡托/等角斜方位投影）
+- 画布/SVG/WebGL 图形绑制
+- 数据可视化算法应用
+- 矩阵变换与插值计算
+- 小程序/uni-app 多端开发

package/skills/vislite-lib/SVG.md

@@ -0,0 +1,138 @@
+# SVG 画笔 API
+
+SVG 画笔用于绘制矢量图形，支持导出为图片。**仅支持 H5 端**。
+
+## 初始化
+
+```js
+import { SVG } from 'vislite';
+
+var painter = new SVG(document.getElementById('root'));
+```
+
+## 配置项 (config)
+
+```js
+painter.config({
+    fillStyle: 'red',           // 填充色
+    strokeStyle: 'black',       // 轮廓色
+    lineWidth: 1,               // 线宽
+    lineCap: 'butt',            // 线端点类型
+    lineJoin: 'miter',          // 线拐角类型
+    lineDash: [],               // 虚线样式
+    textAlign: 'left',          // 文字水平对齐
+    textBaseline: 'middle',     // 文字垂直对齐
+    fontSize: 16,               // 字体大小
+    fontFamily: 'sans-serif',   // 字体
+    opacity: 1                  // 透明度
+});
+```
+
+## 节点操作
+
+```js
+// 标记当前应用节点
+painter.useEl(el);
+
+// 获取当前应用节点
+painter.getEl();
+
+// 追加节点（el可以是元素或字符串如'text'）
+painter.appendEl(el, context);
+
+// 追加绘制板（自动创建对应类型的SVG元素）
+painter.appendBoard('text');   // 文字
+painter.appendBoard('circle'); // 圆形
+painter.appendBoard('path');   // 路径
+painter.appendBoard('arc');    // 弧形
+painter.appendBoard('rect');   // 矩形
+
+// 删除当前节点
+painter.remove();
+
+// 设置/获取节点属性
+painter.attr({ x: 10, y: 20 });
+var x = painter.attr('x');
+```
+
+## 文字绘制
+
+```js
+painter.fillText(text, x, y, deg);     // 填充文字
+painter.strokeText(text, x, y, deg);   // 轮廓文字
+painter.fullText(text, x, y, deg);     // 填充+轮廓文字
+```
+
+## 路径操作
+
+```js
+painter.beginPath();
+painter.closePath();
+painter.moveTo(x, y);
+painter.lineTo(x, y);
+painter.arc(x, y, r, beginDeg, deg);
+painter.quadraticCurveTo(cpx, cpy, x, y);
+painter.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y);
+painter.stroke();
+painter.fill();
+painter.full();
+```
+
+## 图形绘制
+
+```js
+// 弧形
+painter.fillArc(cx, cy, r1, r2, beginDeg, deg);
+painter.strokeArc(cx, cy, r1, r2, beginDeg, deg);
+painter.fullArc(cx, cy, r1, r2, beginDeg, deg);
+
+// 圆形
+painter.fillCircle(cx, cy, r);
+painter.strokeCircle(cx, cy, r);
+painter.fullCircle(cx, cy, r);
+
+// 矩形
+painter.fillRect(x, y, w, h);
+painter.strokeRect(x, y, w, h);
+painter.fullRect(x, y, w, h);
+```
+
+## 渐变色
+
+```js
+// 线性渐变
+painter.createLinearGradient(x1, y1, x2, y2);
+
+// 环形渐变
+painter.createRadialGradient(cx, cy, r);
+
+// 使用方式同 Canvas
+```
+
+## 变换
+
+```js
+// 平移
+painter.translate(x, y);
+
+// 旋转（deg为角度值）
+painter.rotate(deg);
+
+// 缩放
+painter.scale(x, y);
+```
+
+## 导出
+
+```js
+// 导出为图片
+painter.toDataURL().then(dataUrl => {
+    // dataUrl 即为 base64 图片
+});
+```
+
+## 重置
+
+```js
+painter.reset(config);
+```

package/skills/vislite-lib/TreeLayout.md

@@ -0,0 +1,177 @@
+# TreeLayout 树布局
+
+TreeLayout 用于绘制树状图，支持多种布局方向和交互。
+
+## 引入
+
+```js
+import { TreeLayout } from 'vislite';
+```
+
+## 初始化
+
+```js
+var treeLayout = new TreeLayout(config);
+```
+
+### config 配置
+
+```js
+{
+    // 获取根节点方法
+    root: function(initTree) {
+        return initTree;
+    },
+
+    // 获取子节点方法
+    children: function(parentTree, initTree) {
+        return parentTree.children;
+    },
+
+    // 获取节点ID方法
+    id: function(treedata) {
+        return treedata.name;
+    }
+}
+```
+
+## setOption 设置布局行为
+
+```js
+treeLayout.setOption({
+    offsetX: 0,           // 水平方向隐藏节点偏差
+    offsetY: 0,           // 垂直方向隐藏节点偏差
+    duration: 500,        // 切换动画时长(ms)
+    type: 'rect',         // 树图类型：plain|rect|circle
+    direction: 'LR',      // 方向：LR|RL|TB|BT
+    x: 250,               // 根一侧的中间位置x坐标
+    y: 20,                // 根一侧的中间位置y坐标
+    width: 500,           // 矩形树图宽度(type=rect时有效)
+    height: 260,          // 矩形树图高度(type=rect时有效)
+    radius: 100           // 圆树图半径(type=circle时有效)
+});
+```
+
+### type 类型
+
+- **plain**: 普通树图（默认）
+- **rect**: 矩形树图
+- **circle**: 圆树图
+
+### direction 方向
+
+- **LR**: 从左往右
+- **RL**: 从右往左
+- **TB**: 从上往下（默认）
+- **BT**: 从下往上
+
+## use 坐标计算
+
+```js
+var tree = treeLayout.use(initTree, noOpens);
+```
+
+### 返回值 tree 结构
+
+```js
+{
+    node: {
+        '节点ID': {
+            left: x坐标,
+            top: y坐标,
+            pid: 父节点ID,
+            show: 是否显示,
+            deg: 旋转角度(circle类型时)
+        }
+    },
+    size: 节点数量,
+    deep: 深度
+}
+```
+
+### noOpens 参数
+
+控制节点展开/闭合状态：
+
+```js
+treeLayout.use(initTree, {
+    'nodeId1': false,  // 闭合
+    'nodeId2': true    // 打开
+});
+```
+
+## bind 绑定渲染
+
+```js
+treeLayout.bind(initTree, function(tree) {
+    // 绘制树图
+    for (var key in tree.node) {
+        var node = tree.node[key];
+        // 绘制节点...
+    }
+}, noOpens);
+```
+
+## 交互方法
+
+```js
+// 关闭节点
+treeLayout.closeNode('nodeId');
+
+// 打开节点
+treeLayout.openNode('nodeId');
+
+// 切换节点状态
+treeLayout.toggleNode('nodeId');
+
+// 更新布局
+treeLayout.doUpdate();
+
+// 解绑
+treeLayout.unbind();
+```
+
+## 使用示例
+
+```js
+var treeLayout = new TreeLayout();
+
+treeLayout.setOption({
+    type: 'rect',
+    direction: 'TB',
+    x: 250,
+    y: 20,
+    width: 500,
+    height: 260
+});
+
+var data = {
+    name: '前端',
+    children: [{
+        name: '基础',
+        children: [{ name: 'HTML' }, { name: 'CSS' }]
+    }, {
+        name: '框架'
+    }]
+};
+
+var tree = treeLayout.use(data);
+
+// 绘制连线
+painter.config({ strokeStyle: 'red' });
+for (var key in tree.node) {
+    var pid = tree.node[key].pid;
+    if (pid) {
+        painter
+            .beginPath()
+            .moveTo(tree.node[key].left, tree.node[key].top)
+            .bezierCurveTo(...)
+            .stroke();
+    }
+}
+
+// 绘制节点
+for (var key in tree.node) {
+    painter.fullCircle(tree.node[key].left, tree.node[key].top, 10);
+}
+```