Polypad 交互式数学教具的 Canvas 渲染管线与事件分发架构

Polypad 作为 Mathigon 开发、现由 Amplify 运营的交互式数学教具平台，其技术架构为构建高性能交互式白板类应用提供了值得参考的工程范式。本文基于其公开 API 文档，剖析其 Canvas 渲染管线、状态管理 Schema 与事件分发机制，并给出可直接应用的参数配置与性能边界。

渲染层：2D Canvas 与性能阈值

与常见的 WebGL 方案不同，Polypad 选择 2D Canvas API 作为渲染基底。这一决策权衡了数学教具场景的特定需求：几何图形以矢量路径为主，抗锯齿要求高，且无需复杂的三维变换。2D Canvas 的 Path2D 与 fill/stroke 操作足以支撑多边形、数轴、概率图表等教具的绘制需求。

官方文档明确给出了性能上限：单个 Canvas 实例中 tiles 与 strokes 的总数建议控制在 2000 以内。超过此阈值，低端设备（尤其是平板与入门级笔记本）将出现明显的帧率下降。这一限制并非硬性编码，而是基于实际测试的经验值，为开发者提供了明确的容量规划基准。

在渲染优化层面，Polypad 采用以下策略：

• 视口裁剪：仅渲染可见区域内的元素，通过 getViewport() 与 setViewport(x, y, zoom) 管理可见范围
• 状态快照：serialize() 方法支持将当前 Canvas 状态导出为 JSON，便于实现撤销栈与协作同步
• 批量更新：change 事件在拖拽 / 旋转操作结束后统一触发，避免高频重绘

状态模型：JSON Schema 与 Tile 系统

Polypad 的核心抽象是 Tile（图块）与 Stroke（笔触）。每个 Tile 遵循统一的 TileData 接口：

interface TileData {
  name: string;           // 图块类型标识
  x?: number;             // 视口坐标 X
  y?: number;             // 视口坐标 Y
  rot?: number;           // 旋转角度（度）
  color?: string;         // HEX 色值
  layer?: 'front'|'normal'|'back';
  status?: 'locked'|'fixed'|'hidden';
  // ... 类型特定属性
}

这一 Schema 设计体现了关键工程决策：

1. 坐标系解耦：Tile 的位置以视口坐标存储，而非屏幕像素，天然支持无限画布与缩放变换
2. 状态最小化：仅存储变换参数（位置、旋转），几何形状由 name 映射到预定义模板，减小序列化体积
3. 层级分离：layer 字段控制渲染顺序，避免频繁的 z-index DOM 操作

Strokes 则采用 SVG Path 字符串存储，支持 pen、marker、highlighter 三种笔刷类型。这种混合存储策略 —— 几何图块用结构化数据、自由笔触用路径数据 —— 在压缩性与表现力之间取得平衡。

事件分发：从手势到键盘的完整链路

Polypad 的事件系统采用发布 - 订阅模式，通过 PolypadInstance.on(event, callback) 绑定监听器。核心事件类型包括：

手势识别方面，Polypad 内置支持 pinch-pan（双指缩放平移），可通过 noPinchPan: true 选项禁用。对于需要自定义手势的场景，可监听 viewport 事件并结合触摸事件的 event.touches 实现多指识别。

键盘事件通过 bindKeyboardEvents(keys?) 方法启用，默认映射包括：

• Space：临时切换为平移工具
• R：旋转选中图块（Shift+R 反向）
• 方向键：微移选中元素
• Ctrl+Z/Y：撤销 / 重做

开发者可通过传入自定义映射对象覆盖默认行为，或传入 {} 禁用所有快捷键。

视口变换：无限画布的实现

Polypad 支持三种画布模式：infinite（无限）、notebook（固定比例）、fixed（固定尺寸）。无限画布的实现依赖于视口变换矩阵的管理：

// 获取当前视口
const {x, y, zoom} = instance.getViewport();

// 设置视口（以画布中心为锚点）
instance.setViewport(100, -50, 1.5);

// 重置为初始位置（自动居中所有元素）
instance.resetViewport();

视口变换的数学本质是 2D 仿射变换：屏幕坐标 = (世界坐标 - 视口原点) × 缩放因子。Polypad 将这一变换封装在内部渲染管线中，开发者只需操作世界坐标系。

值得注意的是，viewport 事件在变换过程中持续触发，但 change 事件仅在操作结束时派发。这种区分使得开发者可以分别处理 "视图导航" 与 "内容编辑" 两种交互语义。

可落地的实现参数

基于 Polypad 的架构设计，构建类似交互式白板时可参考以下参数配置：

性能基准

• 单 Canvas 元素上限：2000 个（Tile + Stroke）
• 建议预留 20% 缓冲：实际使用控制在 1600 以内
• 低端设备测试：iPad 第 6 代或同级 Android 平板

渲染策略

• 启用 ResizeObserver 自动响应容器尺寸变化
• 复杂场景启用 noPinchPan 减少手势冲突
• 批量操作时先 unSerialize 临时数据，确认后再触发 change

事件监听优先级

• 实时协作：监听 change 事件推送增量更新
• 视图同步：监听 viewport 事件同步其他用户视角
• 撤销栈：拦截 undo/redo 事件实现服务端持久化

无障碍配置

• 启用 highContrast 高对比度模式
• 为 Tile 设置 altText 属性支持屏幕阅读器
• 通过 hideHandles 减少视觉干扰

局限与替代方案

Polypad 的 2D Canvas 方案在以下场景存在局限：

• 超大规模场景：超过 5000 个动态元素时，WebGL 实例化渲染（Instanced Rendering）更具优势
• 复杂滤镜效果：Canvas 2D 的滤镜性能低于 WebGL 着色器
• 跨平台原生：Canvas 2D 在 React Native 等环境需额外桥接层

对于需要 WebGL 能力的场景，可考虑将 Polypad 作为 2D 图层叠加在 WebGL 场景之上，通过 toImage() 方法导出静态纹理作为 WebGL 贴图。

资料来源

• Polypad API Documentation - Mathigon 官方 API 文档，包含完整的 JSON Schema 与事件定义
• Polypad Virtual Manipulatives - Amplify 托管的 Polypad 主站，提供交互式演示

Polypad 的架构证明，对于以矢量几何为主的交互式应用，2D Canvas 配合精细的事件分发与状态管理，足以支撑生产级的用户体验。关键在于明确的性能边界意识与合理的视口裁剪策略。

web