vislite 1.10.0 → 1.11.0

package/skills/vislite-lib/Utilities.md

@@ -0,0 +1,177 @@
+# 工具函数 API
+
+VISLite 提供多种实用的工具函数。
+
+## ruler 刻度尺算法
+
+根据数值范围计算合适的刻度尺刻度。
+
+### 引入
+
+```js
+import { ruler } from 'vislite';
+```
+
+### 使用方法
+
+```js
+var scales = ruler(maxValue, minValue, num);
+```
+
+### 参数说明
+
+- **maxValue**: 最大值
+- **minValue**: 最小值
+- **num**: 刻度数量（建议值）
+
+### 返回值
+
+返回刻度数组，例如 `[0, 20, 40, 60, 80, 100]`
+
+### 示例
+
+```js
+var scales = ruler(85, 12, 5);
+console.log(scales); // 可能输出 [0, 20, 40, 60, 80, 100]
+```
+
+---
+
+## animation 动画控制
+
+提供基于requestAnimationFrame的动画控制。
+
+### 引入
+
+```js
+import { animation } from 'vislite';
+```
+
+### 使用方法
+
+```js
+var stop = animation(function(percent) {
+    // percent: 0-1 的动画进度
+    var x = startX + (endX - startX) * percent;
+    // 更新绘制...
+}, duration, function() {
+    // 动画结束回调
+});
+```
+
+### 返回值
+
+`stop` 函数，调用可停止动画。
+
+### 示例
+
+```js
+var stop = animation(function(percent) {
+    var x = 0 + (200 - 0) * percent;
+    painter.clearRect(0, 0, 300, 300);
+    painter.fillCircle(x, 100, 20);
+}, 1000, function() {
+    console.log('动画结束');
+});
+
+// 1秒后停止
+setTimeout(stop, 1000);
+```
+
+---
+
+## getLoopColors 循环颜色
+
+生成一组循环使用的颜色数组。
+
+### 引入
+
+```js
+import { getLoopColors } from 'vislite';
+```
+
+### 使用方法
+
+```js
+var colors = getLoopColors(num, alpha, colorsFactory);
+```
+
+### 参数说明
+
+- **num**: 需要的颜色数量
+- **alpha**: 透明度（0-1），默认 1
+- **colorsFactory**: 自定义颜色工厂函数
+
+### 返回值
+
+返回颜色数组，例如 `['rgba(84,112,198,1)', 'rgba(145,204,117,1)', ...]`
+
+### 示例
+
+```js
+// 获取10个颜色
+var colors = getLoopColors(10);
+
+// 获取半透明颜色
+var colors = getLoopColors(10, 0.5);
+
+// 自定义颜色
+var colors = getLoopColors(5, 1, function(alpha) {
+    return [
+        'rgba(255,0,0,' + alpha + ')',
+        'rgba(0,255,0,' + alpha + ')'
+    ];
+});
+```
+
+---
+
+## throttle 节流函数
+
+限制函数执行频率。
+
+### 引入
+
+```js
+import { throttle } from 'vislite';
+```
+
+### 使用方法
+
+```js
+var throttleFunc = throttle(func, delay);
+```
+
+### 参数说明
+
+- **func**: 要节流的函数
+- **delay**: 延迟时间（毫秒）
+
+### 返回值
+
+返回节流后的函数。
+
+### 示例
+
+```js
+// 滚动事件节流
+var handleScroll = throttle(function() {
+    console.log('scrolling');
+}, 100);
+
+window.addEventListener('scroll', handleScroll);
+```
+
+---
+
+## assemble 颜色组装
+
+内部使用的颜色组装工具，用于区域检测的颜色编码。
+
+### 引入
+
+```js
+import { assemble } from 'vislite';
+```
+
+返回给定范围内的随机颜色值，用于 Canvas 区域检测功能。

package/skills/vislite-lib/WebGL.md

@@ -0,0 +1,107 @@
+# WebGL API
+
+WebGL 相关模块，用于 3D 图形渲染。**仅支持 H5 端**。
+
+## 获取 WebGL 上下文
+
+```js
+import { getWebGLContext } from 'vislite';
+
+var canvas = document.getElementById('canvas');
+var gl = getWebGLContext(canvas, scale, {
+    preserveDrawingBuffer: true
+}, 'scaleToFill');
+```
+
+### 参数说明
+
+- **canvas**: HTMLCanvasElement
+- **scale**: 缩放比例，默认1
+- **opts**: 配置项
+  - `preserveDrawingBuffer`: 是否保留绘制缓冲区
+- **mode**: 缩放模式
+  - `scaleToFill`: 拉伸填充
+  - `aspectFit`: 适应（保持比例）
+  - `aspectFill`: 覆盖（保持比例）
+
+### 返回值
+
+返回 `WebGL2RenderingContext` 对象。
+
+## Shader (着色器)
+
+```js
+import { Shader } from 'vislite';
+
+var shader = new Shader(gl, {
+    vertexShader: '...',      // 顶点着色器源码
+    fragmentShader: '...'      // 片元着色器源码
+});
+
+shader.use();
+```
+
+### 方法
+
+- `use()`: 使用该着色器程序
+- `setAttribute(name, data)`: 设置顶点属性
+- `setUniform(name, type, value)`: 设置 uniform 变量
+
+## Buffer (缓冲区)
+
+```js
+import { Buffer } from 'vislite';
+
+var buffer = new Buffer(gl);
+buffer.setAttribute('position', data);
+buffer.bind();
+```
+
+## Texture (纹理)
+
+```js
+import { Texture } from 'vislite';
+
+var texture = new Texture(gl);
+texture.bind();
+texture.setImage(image);
+texture.setParameter(params);
+```
+
+## 使用示例
+
+```js
+import { getWebGLContext, Shader, Buffer, Texture } from 'vislite';
+
+var gl = getWebGLContext(canvas, 1);
+
+// 创建着色器
+var shader = new Shader(gl, {
+    vertexShader: `
+        attribute vec4 position;
+        void main() {
+            gl_Position = position;
+        }
+    `,
+    fragmentShader: `
+        precision mediump float;
+        void main() {
+            gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
+        }
+    `
+});
+
+shader.use();
+
+// 创建缓冲区
+var buffer = new Buffer(gl);
+buffer.setAttribute('position', new Float32Array([
+    0, 0.5, 0,
+    -0.5, -0.5, 0,
+    0.5, -0.5, 0
+]));
+buffer.bind();
+
+// 绘制
+gl.drawArrays(gl.TRIANGLES, 0, 3);
+```

package/skills/vislite-lib/minialipay/ui-canvas.md

@@ -0,0 +1,96 @@
+# 支付宝小程序 Canvas
+
+支付宝小程序使用自定义组件方式接入 VISLite Canvas。
+
+## 安装
+
+在支付宝小程序项目中引入 vislite：
+
+```bash
+npm install vislite
+```
+
+## 使用方式
+
+### 在小程序配置中引入
+
+```json
+{
+  "usingComponents": {
+    "ui-canvas": "vislite/minialipay/ui-canvas/index"
+  }
+}
+```
+
+### 在页面中使用
+
+```xml
+<ui-canvas
+  id="canvas"
+  width="300"
+  height="150"
+  region="{{true}}"
+  onDoTouchstart="onTouchstart"
+/>
+```
+
+### 在 JS 中获取画笔
+
+```js
+Page({
+    onLoad() {
+        this.selectComponent('#canvas').fetch().then(painter => {
+            this.painter = painter;
+
+            // 使用画笔
+            this.painter.config({
+                fillStyle: 'red'
+            }).fillCircle(150, 75, 50);
+        });
+    },
+
+    onTouchstart(e) {
+        console.log('区域:', e.detail.name);
+        console.log('坐标:', e.detail.x, e.detail.y);
+    }
+});
+```
+
+## 组件属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| width | Number | 300 | 画布宽度 |
+| height | Number | 150 | 画布高度 |
+| region | Boolean | true | 是否启用区域检测 |
+| onDoTouchstart | Function | - | 点击事件回调 |
+
+## 事件详情
+
+### onDoTouchstart
+
+当用户点击画布时触发，返回对象包含：
+
+```js
+{
+    name: '区域名称',  // 通过 setRegion 设置的区域名
+    x: 100,          // 点击x坐标
+    y: 50            // 点击y坐标
+}
+```
+
+## 注意事项
+
+1. 支付宝小程序的 Canvas 上下文获取方式与 Web 不同
+2. 需要使用 `my.createSelectorQuery()` 获取 canvas 节点
+3. 区域检测功能依赖透明度拾取，可能影响性能
+4. 导出图片使用 `toDataURL()` 方法会返回临时文件路径
+
+## 与 Web 版的差异
+
+| 功能 | Web版 | 支付宝小程序版 |
+|------|-------|---------------|
+| 初始化 | `new Canvas(el)` | 组件 + `fetch()` |
+| 事件绑定 | `bind('click', cb)` | 组件 `onDoTouchstart` |
+| 导出 | `toDataURL()` base64 | `toDataURL()` 临时路径 |
+| 区域检测 | 自动绑定 | 需要组件属性开启 |

package/skills/vislite-lib/miniprogram/ui-canvas.md

@@ -0,0 +1,99 @@
+# 微信小程序 Canvas
+
+微信小程序使用自定义组件方式接入 VISLite Canvas。
+
+## 安装
+
+在微信小程序项目中引入 vislite：
+
+```bash
+npm install vislite
+```
+
+## 使用方式
+
+### 在小程序配置中引入
+
+```json
+{
+  "usingComponents": {
+    "ui-canvas": "vislite/miniprogram/ui-canvas/index"
+  }
+}
+```
+
+### 在页面中使用
+
+```xml
+<ui-canvas
+  id="canvas"
+  width="300"
+  height="150"
+  region="{{true}}"
+  bind:dotouchstart="onTouchstart"
+/>
+```
+
+### 在 JS 中获取画笔
+
+```js
+Component({
+    lifetimes: {
+        ready() {
+            this.selectComponent('#canvas').fetch().then(painter => {
+                this.painter = painter;
+
+                // 使用画笔
+                this.painter.config({
+                    fillStyle: 'red'
+                }).fillCircle(150, 75, 50);
+            });
+        }
+    },
+
+    methods: {
+        onTouchstart(e) {
+            console.log('区域:', e.detail.name);
+            console.log('坐标:', e.detail.x, e.detail.y);
+        }
+    }
+});
+```
+
+## 组件属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| width | Number | 300 | 画布宽度 |
+| height | Number | 150 | 画布高度 |
+| region | Boolean | true | 是否启用区域检测 |
+
+## 事件
+
+### dotouchstart
+
+当用户点击画布时触发，返回对象包含：
+
+```js
+{
+    name: '区域名称',  // 通过 setRegion 设置的区域名
+    x: 100,          // 点击x坐标
+    y: 50            // 点击y坐标
+}
+```
+
+## 注意事项
+
+1. 微信小程序使用 `wx.createSelectorQuery()` 获取 canvas 节点
+2. 需要处理高清屏的 dpr（设备像素比）缩放
+3. 导出图片需要使用 `wx.canvasToTempFilePath` 转换
+4. 区域检测依赖 `getImageData`，可能存在性能问题
+
+## 与 Web 版的差异
+
+| 功能 | Web版 | 微信小程序版 |
+|------|-------|------------|
+| 初始化 | `new Canvas(el)` | 组件 + `fetch()` |
+| 事件绑定 | `bind('click', cb)` | 组件 `bind:dotouchstart` |
+| 导出 | `toDataURL()` base64 | `toDataURL()` 需转换 |
+| dpr处理 | 需手动处理 | 组件自动处理 |

package/skills/vislite-lib/uniapp/ui-canvas.md

@@ -0,0 +1,114 @@
+# uni-app Canvas
+
+uni-app 是一个跨平台框架，VISLite Canvas 可以直接用于 uni-app 项目。
+
+## 安装
+
+```bash
+npm install vislite
+```
+
+## Web 平台使用
+
+```js
+import { Canvas } from 'vislite';
+
+export default {
+    onReady() {
+        this.painter = new Canvas(this.$refs.canvas);
+        this.painter.config({
+            fillStyle: 'red'
+        }).fillCircle(150, 75, 50);
+    }
+}
+```
+
+```html
+<template>
+    <view ref="canvas" style="width: 300px; height: 150px;"></view>
+</template>
+```
+
+## 小程序平台使用
+
+### 方式一：使用原生 Canvas
+
+uni-app 编译到微信/支付宝小程序时，可以获取原生 canvas 上下文：
+
+```js
+import { RawCanvas } from 'vislite';
+
+onLoad() {
+    uni.createSelectorQuery()
+        .select('#canvas')
+        .node()
+        .exec((res) => {
+            const canvas = res[0].node;
+            const ctx = canvas.getContext('2d');
+            const dpr = uni.getSystemInfoSync().pixelRatio;
+
+            canvas.width = 300 * dpr;
+            canvas.height = 150 * dpr;
+            ctx.scale(dpr, dpr);
+
+            this.painter = new RawCanvas({
+                getContext() { return ctx; }
+            });
+        });
+}
+```
+
+### 方式二：使用各平台组件
+
+各小程序平台也可以使用对应的 ui-canvas 组件：
+
+#### 微信小程序
+
+```json
+{
+    "usingComponents": {
+        "ui-canvas": "vislite/miniprogram/ui-canvas/index"
+    }
+}
+```
+
+#### 支付宝小程序
+
+```json
+{
+    "usingComponents": {
+        "ui-canvas": "vislite/minialipay/ui-canvas/index"
+    }
+}
+```
+
+## 跨平台注意事项
+
+### 平台差异
+
+| 功能 | H5 | 微信 | 支付宝 |
+|------|-----|------|--------|
+| new Canvas() | ✅ | ⚠️ 需用组件 | ⚠️ 需用组件 |
+| region检测 | ✅ | ⚠️ 性能差 | ⚠️ 性能差 |
+| toDataURL() | ✅ | ⚠️ 需转换 | ⚠️ 需转换 |
+
+### 建议
+
+1. **H5 优先**：核心逻辑使用 H5 Canvas 实现
+2. **平台检测**：使用 `uni.getSystemInfo()` 判断平台
+3. **降级处理**：小程序平台可关闭 region 功能提升性能
+
+```js
+import { Canvas } from 'vislite';
+
+onReady() {
+    const systemInfo = uni.getSystemInfoSync();
+
+    if (systemInfo.platform === 'h5') {
+        this.painter = new Canvas(this.$refs.canvas);
+    } else {
+        // 小程序平台使用组件
+        // ...
+    }
+}
+```