Universal Canvas Engine

Universal Canvas Engine 是一个统一的Canvas绘图引擎，支持多种Canvas实现（如Fabric.js和微信小程序Canvas）。项目采用适配器模式，提供一致的API接口，屏蔽底层实现差异。

安装

npm install @universal-canvas/engine

在微信小程序中使用

1. 构建步骤

在微信开发者工具中使用此包，需要执行以下步骤：

1. 确保已在项目根目录下执行 npm install 安装所有依赖
2. 在微信开发者工具中，点击菜单栏的 "工具" -> "构建 npm"
3. 构建完成后，会在项目中生成 miniprogram_npm 目录

2. 引入 WeappAdapter

在小程序页面中引入 WeappAdapter：

import { WeappAdapter } from '@universal-canvas/engine'

Page({
  data: {},
  
  onLoad() {
    // 初始化适配器
    const adapter = new WeappAdapter();
    
    // 初始化配置
    const config = {
      containerId: '#canvas-container'  // 页面中canvas容器的ID选择器
    };
    
    // 初始化适配器
    adapter.init(config).then(() => {
      console.log('WeappAdapter initialized successfully');
    }).catch(err => {
      console.error('Failed to initialize WeappAdapter:', err);
    });
  }
})

3. WXML 结构

在对应的 WXML 文件中添加容器元素：

<view id="canvas-container" style="width: 100%; height: 300px;">
  <!-- Canvas 将在此容器中渲染 -->
</view>

4. 常见问题解决

"module not defined" 错误

如果遇到类似以下错误：

Error: module 'miniprogram_npm/@universal-canvas/engine/adapter/weapp.js' is not defined

请按以下步骤排查：

1. 确认已经执行了 "构建 npm" 步骤
2. 检查 miniprogram_npm 目录是否已生成且包含 @universal-canvas/engine 文件夹
3. 如果问题仍然存在，请清理 miniprogram_npm 目录后重新构建：
   • 删除 miniprogram_npm 文件夹
   • 重新执行 "工具" -> "构建 npm"
4. 确保在小程序开发者工具中重新编译项目

适配器环境检查

WeappAdapter 内部包含了环境检查，确保只在微信小程序环境中使用。如果在非小程序环境中使用会抛出错误。

API 参考

WeappAdapter

方法

init(config)

初始化适配器

参数：

• config {Object} 配置对象
  • containerId {String} Canvas 容器的选择器

返回值：Promise

getContainerRect(id)

获取容器的位置和尺寸信息

参数：

• id {String} 容器元素的选择器

返回值：Promise

开发指南

构建项目

npm run build

该命令会：

1. 编译 TypeScript 代码到 dist 目录
2. 将编译结果复制到 miniprogram_npm/@universal-canvas/engine 目录，用于小程序环境

目录结构

src/
├── adapter/
│   └── weapp.ts           # 微信小程序适配器
├── engine.ts              # 引擎接口定义
├── index.ts               # 默认入口文件
├── index.miniprogram.ts   # 小程序专用入口文件
└── types.ts               # 类型定义

dist/                      # 编译后的代码
miniprogram_npm/           # 小程序npm包目录

小程序支持

为了更好地支持微信小程序环境，我们提供了专门的小程序入口文件 index.miniprogram.js，并通过 package.json 中的 miniprogram 字段指定。