vislite 1.10.0 → 1.11.0

package/skills/vislite-lib/Canvas.md

@@ -0,0 +1,184 @@
+# Canvas 画笔 API
+
+Canvas 是 VISLite 的核心画笔之一，**绘制 API 完全一致**，但初始化方式因平台而异。
+
+## 平台初始化方式
+
+### H5 端
+
+```js
+import { Canvas } from 'vislite';
+
+var painter = new Canvas(document.getElementById('root'), {
+    scale: 2,              // 缩放倍率，默认2
+    region: true,          // 是否启用区域检测，默认true
+    willReadFrequently: false
+}, width, height);
+```
+
+### 微信/支付宝小程序
+
+小程序端需要使用 ui-canvas 组件，详见：
+- [微信小程序 Canvas](miniprogram/ui-canvas.md)
+- [支付宝小程序 Canvas](minialipay/ui-canvas.md)
+
+### uni-app
+
+uni-app 根据编译目标平台选择上述方式，详见：
+- [uni-app Canvas](uniapp/ui-canvas.md)
+
+## 配置项 (config)
+
+```js
+painter.config({
+    fillStyle: 'red',           // 填充色
+    strokeStyle: 'black',       // 轮廓色
+    lineWidth: 1,               // 线宽
+    lineCap: 'butt',            // 线端点类型：butt|round|square
+    lineJoin: 'miter',          // 线拐角：miter|bevel|round
+    lineDash: [],               // 虚线样式
+    textAlign: 'left',          // 文字水平对齐：left|center|right
+    textBaseline: 'middle',     // 文字垂直对齐：middle|top|bottom
+    shadowBlur: 0,              // 阴影模糊
+    shadowColor: 'black',       // 阴影颜色
+    fontSize: 16,               // 字体大小
+    fontFamily: 'sans-serif',   // 字体
+    fontWeight: 400,            // 字重
+    fontStyle: 'normal',        // 字类型
+    arcStartCap: 'butt',       // 圆弧开始端闭合：butt|round|-round
+    arcEndCap: 'butt',          // 圆弧结束端闭合
+    rectRadius: [10, 10, 10, 10] // 矩形圆角
+});
+```
+
+### 渐变色
+
+```js
+// 线性渐变
+var gradient = painter.createLinearGradient(x1, y1, x2, y2);
+gradient.setColor(0, 'red').setColor(1, 'blue');
+painter.config({ fillStyle: gradient.value() });
+
+// 环形渐变
+var gradient = painter.createRadialGradient(cx, cy, r1, r2);
+gradient.setColor(0, 'red').setColor(1, 'blue');
+
+// 角度渐变 (1.2.0+)
+var gradient = painter.createConicGradient(cx, cy, beginDeg, deg);
+gradient.setColor(0, 'red').setColor(1, 'blue');
+```
+
+## 文字绘制
+
+```js
+painter.fillText(text, x, y, deg);       // 填充文字
+painter.strokeText(text, x, y, deg);     // 轮廓文字
+painter.fullText(text, x, y, deg);        // 填充+轮廓文字
+
+// 多行文字
+painter.fillTexts(contents, x, y, width, lineHeight, deg);
+painter.strokeTexts(contents, x, y, width, lineHeight, deg);
+painter.fullTexts(contents, x, y, width, lineHeight, deg);
+
+// 计算文字宽度
+painter.textWidth(text);
+```
+
+## 路径操作
+
+```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.fill();         // 填充
+painter.stroke();       // 描边
+painter.full();         // 填充+描边
+painter.clip();         // 裁剪
+```
+
+## 画布操作
+
+```js
+painter.save();         // 保存状态
+painter.restore();      // 恢复状态
+painter.clearRect(x, y, w, h);  // 清除矩形区域
+painter.clearCircle(cx, cy, r); // 清除圆形区域
+
+// 缩放
+painter.scale(x, y);
+
+// 获取画布信息
+painter.getInfo();  // { width, height }
+
+// 获取原始画布上下文
+painter.getContext();  // CanvasRenderingContext2D
+```
+
+## 区域交互
+
+```js
+// 设置当前绑定的区域名称
+painter.setRegion('regionName');
+
+// 获取点击所在的区域名称
+painter.getRegion(x, y).then(regionName => {
+    console.log(regionName);
+});
+
+// 绑定点击事件
+painter.bind('click', (regionName, x, y) => {
+    console.log(regionName, x, y);
+});
+
+// 只绘制区域（用于交互检测）
+painter.onlyRegion(true);
+
+// 只绘制视图
+painter.onlyView(true);
+```
+
+## 图形绘制（便捷方法）
+
+```js
+// 圆
+painter.fillCircle(x, y, r);      // 填充圆
+painter.strokeCircle(x, y, r);    // 描边圆
+painter.fullCircle(x, y, r);      // 填充+描边圆
+
+// 矩形
+painter.fillRect(x, y, w, h);
+painter.strokeRect(x, y, w, h);
+painter.fullRect(x, y, w, h);
+
+// 圆环 (1.1.0+)
+painter.fillRing(x, y, r1, r2);
+painter.strokeRing(x, y, r1, r2);
+painter.fullRing(x, y, r1, r2);
+
+// 椭圆 (1.1.0+)
+painter.fillEllipse(x, y, r1, r2, deg);
+painter.strokeEllipse(x, y, r1, r2, deg);
+```
+
+## 导出
+
+```js
+// 导出为图片
+painter.toDataURL(type, encoderOptions).then(dataUrl => {
+    // dataUrl 即为 base64 图片
+});
+```
+
+## 重置
+
+```js
+// 重置为默认配置
+painter.reset();
+
+// 带自定义配置重置
+painter.reset({ fillStyle: 'blue', fontSize: 20 });
+```

package/skills/vislite-lib/Interpolation.md

@@ -0,0 +1,130 @@
+# 插值函数 API
+
+VISLite 提供 Cardinal 和 Hermite 两种三次插值函数，用于平滑曲线绘制。
+
+## Hermite 插值
+
+Hermite 插值需要指定两个端点和两个端点处的斜率。
+
+### 引入
+
+```js
+import { Hermite } from 'vislite';
+```
+
+### 初始化
+
+```js
+var hermite = new Hermite(u);
+```
+
+- **u**: 张弛系数，控制曲线在端点处的弯曲程度，默认 0.5
+
+### 设置点位置
+
+```js
+hermite.setP(x1, y1, x2, y2, s1, s2);
+```
+
+参数说明：
+- **x1, y1**: 左边点位置
+- **x2, y2**: 右边点位置
+- **s1**: 左边点的切线斜率
+- **s2**: 右边点的切线斜率
+
+### 计算插值
+
+```js
+var y = hermite.use(x);
+```
+
+根据 x 值返回对应的 y 值。
+
+### 示例
+
+```js
+var hermite = new Hermite(0.5);
+
+hermite.setP(0, 0, 100, 100, 0, 1);
+
+// 计算x=50时的y值
+var y = hermite.use(50);
+```
+
+---
+
+## Cardinal 插值
+
+Cardinal 插值是 Hermite 的扩展，只需提供点序列，系统自动计算斜率。
+
+### 引入
+
+```js
+import { Cardinal } from 'vislite';
+```
+
+### 初始化
+
+```js
+var cardinal = new Cardinal(t);
+```
+
+- **t**: 张弛系数，控制曲线走势，默认 0
+  - t = 0：默认曲线
+  - t = -1：分水岭效果
+  - |t| 越大，曲线调整越剧烈
+
+### 设置点序列
+
+```js
+cardinal.setP([[x1, y1], [x2, y2], [x3, y3], ...]);
+```
+
+至少需要两个点。
+
+### 计算插值
+
+```js
+var y = cardinal.use(x);
+```
+
+根据 x 值返回对应的 y 值。
+
+### 示例
+
+```js
+var cardinal = new Cardinal(0);
+
+cardinal.setP([
+    [0, 0],
+    [25, 25],
+    [50, 10],
+    [75, 50],
+    [100, 100]
+]);
+
+// 绘制平滑曲线
+for (var x = 0; x <= 100; x += 1) {
+    var y = cardinal.use(x);
+    painter.lineTo(x, y);
+}
+painter.stroke();
+```
+
+---
+
+## 对比与选择
+
+| 特性 | Hermite | Cardinal |
+|------|---------|----------|
+| 端点斜率 | 手动指定 | 自动计算 |
+| 参数数量 | 6个 | 2个（点序列） |
+| 灵活性 | 高（可自定义斜率） | 中（受邻近点影响） |
+| 适用场景 | 精确控制曲线形状 | 自然平滑的曲线 |
+
+## 应用场景
+
+- **折线图平滑**: 使用 Cardinal
+- **动画路径**: 使用 Hermite 自定义缓动
+- **字体渲染**: 使用 Cardinal 平滑字形边缘
+- **地图等高线**: 使用 Hermite 精确控制地形变化

package/skills/vislite-lib/Matrix.md

@@ -0,0 +1,175 @@
+# Matrix4 矩阵变换
+
+Matrix4 提供 4x4 矩阵变换能力，用于复杂的图形变换。
+
+## 引入
+
+```js
+import { Matrix4 } from 'vislite';
+```
+
+## 初始化
+
+```js
+var matrix = new Matrix4();
+// 或指定初始矩阵
+var matrix = new Matrix4([1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1]);
+```
+
+## 基本变换
+
+### 平移
+
+```js
+matrix.move(dis, a, b, c);
+```
+
+参数说明：
+- **dis**: 移动距离
+- **a, b, c**: 移动方向向量的 x, y, z 分量
+
+```js
+// 向x轴正方向移动10
+matrix.move(10, 1, 0, 0);
+
+// 向y轴负方向移动5
+matrix.move(-5, 0, 1, 0);
+```
+
+### 旋转
+
+```js
+matrix.rotate(deg, a1, b1, c1, a2, b2, c2);
+```
+
+参数说明：
+- **deg**: 旋转角度（弧度制）
+- **a1, b1, c1**: 旋转轴向量（确定旋转平面）
+- **a2, b2, c2**: 旋转正方向向量
+
+```js
+// 绕x轴旋转
+matrix.rotate(Math.PI, 1, 0, 0);
+
+// 绕y轴旋转
+matrix.rotate(Math.PI, 0, 1, 0);
+
+// 绕z轴旋转
+matrix.rotate(Math.PI, 0, 0, 1);
+```
+
+### 缩放
+
+```js
+matrix.scale(xTimes, yTimes, zTimes, cx, cy, cz);
+```
+
+参数说明：
+- **xTimes, yTimes, zTimes**: 各轴缩放比例
+- **cx, cy, cz**: 缩放中心点坐标
+
+```js
+// 以原点为中心放大2倍
+matrix.scale(2, 2, 2);
+
+// 以(10, 10, 0)为中心放大
+matrix.scale(2, 2, 1, 10, 10, 0);
+```
+
+## 矩阵运算
+
+### 矩阵乘法
+
+```js
+matrix.multiply(newMatrix4, flag);
+```
+
+- **flag**: false（默认）新矩阵左乘当前矩阵；true 则右乘
+
+### 应用变换
+
+```js
+var [x, y, z, w] = matrix.use(px, py, pz, pw);
+```
+
+将变换应用到坐标点，返回变换后的齐次坐标。
+
+### 获取矩阵值
+
+```js
+var values = matrix.value();
+```
+
+返回 4x4 矩阵的 16 个元素数组（列主序存储）。
+
+### 重置矩阵
+
+```js
+matrix.setValue([1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1]);
+```
+
+## 使用示例
+
+### 组合变换
+
+```js
+var matrix = new Matrix4();
+
+// 先平移再旋转
+matrix.move(100, 1, 0, 0);
+matrix.rotate(Math.PI / 4, 0, 0, 1);
+
+// 应用到点
+var [x, y] = matrix.use(10, 20, 0);
+```
+
+### 3D 变换
+
+```js
+var matrix = new Matrix4();
+
+// 绕x轴旋转45度
+matrix.rotate(Math.PI / 4, 1, 0, 0);
+
+// 绕y轴旋转30度
+matrix.rotate(Math.PI / 6, 0, 1, 0);
+
+// 应用到3D点
+var [x, y, z, w] = matrix.use(10, 20, 30);
+```
+
+---
+
+## 基础变换函数
+
+除 Matrix4 类外，还提供独立的基础变换函数：
+
+### rotate 旋转
+
+```js
+import { rotate } from 'vislite';
+
+var [x, y] = rotate(cx, cy, deg, px, py);
+```
+
+绕点 (cx, cy) 旋转 deg 弧度后的 (px, py) 坐标。
+
+### move 平移
+
+```js
+import { move } from 'vislite';
+
+var [x, y, z] = move(dis, a, b, c, px, py, pz);
+```
+
+沿向量 (a, b, c) 方向移动 dis 距离后的坐标。
+
+### scale 缩放
+
+```js
+import { scale } from 'vislite';
+
+var [x, y, z] = scale(times, cx, cy, cz, px, py, pz);
+```
+
+以 (cx, cy, cz) 为中心缩放 times 倍后的坐标。

package/skills/vislite-lib/PieLayout.md

@@ -0,0 +1,132 @@
+# PieLayout 饼图布局
+
+PieLayout 用于绘制饼图/环形图，支持交互和动画。
+
+## 引入
+
+```js
+import { PieLayout } from 'vislite';
+```
+
+## 初始化
+
+```js
+var pieLayout = new PieLayout(config);
+```
+
+### config 配置
+
+```js
+{
+    // 获取名称
+    name: function(pieData, initPie) {
+        return pieData.name;
+    },
+
+    // 获取值
+    value: function(pieData, initPie) {
+        return pieData.value;
+    }
+}
+```
+
+## setOption 设置布局行为
+
+```js
+pieLayout.setOption({
+    cx: 200,                    // 圆心x坐标
+    cy: 200,                    // 圆心y坐标
+    radius: [50, 100],          // 半径：[内半径, 外半径]
+    duration: 200               // 动画时长(ms)
+});
+```
+
+## use 坐标计算
+
+```js
+var pie = pieLayout.use(initPie, hoverIndex);
+```
+
+### 返回值 pie 结构
+
+```js
+{
+    count: 数据项数量,
+    cx: 圆心x,
+    cy: 圆心y,
+    radius: [内半径, 外半径],
+    hoverIndex: 当前悬浮项索引,
+    node: [
+        {
+            value: 数值,
+            name: 名称,
+            beginDeg: 开始弧度,
+            deg: 跨越弧度,
+            isHover: 是否悬浮,
+            radius: [当前内半径, 当前外半径],
+            label: {
+                line: [[x1,y1], [x2,y2], [x3,y3]],  // 标签线
+                position: [x, y],                  // 标签位置
+                align: 'left' | 'right'             // 对齐方式
+            }
+        }
+    ]
+}
+```
+
+## bind 绑定渲染
+
+```js
+pieLayout.bind(initPie, function(pie) {
+    // 绘制饼图
+    for (var i = 0; i < pie.count; i++) {
+        var node = pie.node[i];
+        // 绘制扇形...
+    }
+});
+```
+
+## 交互方法
+
+```js
+// 设置悬浮项
+pieLayout.setHover(index);
+
+// 更新布局
+pieLayout.doUpdate();
+
+// 解绑
+pieLayout.unbind();
+```
+
+## 使用示例
+
+```js
+var pieLayout = new PieLayout();
+
+pieLayout.setOption({
+    cx: 200,
+    cy: 200,
+    radius: [30, 100],
+    duration: 300
+});
+
+var data = [
+    { name: 'HTML', value: 30 },
+    { name: 'CSS', value: 20 },
+    { name: 'JavaScript', value: 50 }
+];
+
+var pie = pieLayout.use(data);
+
+// 绘制饼图
+for (var i = 0; i < pie.count; i++) {
+    var node = pie.node[i];
+    var colors = ['red', 'green', 'blue'];
+
+    painter.config({
+        fillStyle: colors[i]
+    }).fillArc(pie.cx, pie.cy, node.radius[0], node.radius[1],
+               node.beginDeg, node.deg);
+}
+```