canvas-sketch 项目核心 API 详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00770/article/details/148506367

canvas-sketch 项目核心 API 详解

canvas-sketch [beta] A framework for making generative artwork in JavaScript and the browser. 项目地址: https://gitcode.com/gh_mirrors/ca/canvas-sketch

canvas-sketch 是一个强大的 JavaScript 创意编程框架，专为艺术家、设计师和开发者设计，用于创建基于 Canvas 的交互式艺术作品和可视化项目。本文将深入解析其核心 API，帮助开发者掌握这一工具的使用方法。

框架概述

canvas-sketch 提供了一套完整的解决方案，将复杂的 Canvas 操作封装成简单易用的 API，主要特点包括：

支持物理尺寸单位（英寸、厘米等）与像素单位的自动转换
内置动画循环管理
便捷的导出功能
响应式设计支持
跨平台兼容性（Node.js 和浏览器环境）

核心 API 详解

1. 基础导入方式

canvas-sketch 采用模块化设计，支持多种导入方式：

// CommonJS 方式（Node.js 环境推荐）
const canvasSketch = require('canvas-sketch');

// ES Modules 方式
import canvasSketch from 'canvas-sketch';

2. 核心方法：canvasSketch()

这是框架的主入口函数，接受两个参数：

const promise = canvasSketch(sketch, settings);

sketch: 核心绘制函数，可以是同步或异步函数
settings: 配置对象（可选）

sketch 函数的两种形式

简单形式 - 返回渲染函数：

const sketch = (initialProps) => {
  // 初始化逻辑
  return (renderProps) => {
    // 渲染逻辑
  };
};

高级形式 - 返回包含多个方法的对象：

const sketch = () => {
  return {
    render(props) { /* 渲染 */ },
    resize(props) { /* 响应尺寸变化 */ },
    // 其他生命周期方法
  };
};

3. 配置参数详解

canvas-sketch 提供了丰富的配置选项，主要分为以下几类：

尺寸相关配置

dimensions: 作品尺寸，如 [11, 7] 表示 11×7 单位
units: 单位类型，支持 "px"（像素）、"in"（英寸）、"cm"（厘米）等
pixelsPerInch: 每英寸像素数（默认 72）
orientation: 方向（"landscape" 或 "portrait"）
scaleToFit: 是否自动缩放以适应窗口

DOM 相关配置

canvas: 指定使用的 canvas 元素
context: 上下文类型（"2d" 或 "webgl"）
parent: 指定挂载的父元素

导出相关配置

file: 导出文件名模式
encoding: 导出格式（"image/png"、"image/jpeg" 等）
encodingQuality: 导出质量（0-1）

动画相关配置

animate: 是否启用动画
fps: 帧率（默认 24）
duration: 动画总时长（秒）
playbackRate: 播放速率控制

4. 属性对象（Props）

在 sketch 函数和渲染函数中，会接收到一个包含丰富信息的 props 对象，主要包含：

尺寸信息

width/height: 作品逻辑尺寸
canvasWidth/canvasHeight: 实际像素尺寸
pixelRatio: 设备像素比

动画信息

time: 当前时间（秒）
frame: 当前帧数
playhead: 播放进度（0-1）
deltaTime: 上一帧时间差

实用功能

render(): 手动触发重绘
exportFrame(): 导出当前帧
play()/pause(): 控制动画播放

5. 渲染器对象（Renderer Objects）

对于复杂场景，可以返回一个包含多个方法的对象：

{
  render(props) {},    // 渲染逻辑
  resize(props) {},    // 响应尺寸变化
  begin(props) {},     // 动画开始
  end(props) {},       // 动画结束
  unload() {}          // 清理资源
}

6. SketchManager 管理接口

canvasSketch() 调用返回一个 Promise，解析为 SketchManager 实例，提供程序控制能力：

const manager = await canvasSketch(sketch, settings);

// 控制方法
manager.play();    // 播放动画
manager.pause();   // 暂停
manager.render();  // 手动渲染

// 属性访问
const currentProps = manager.props;
const currentSettings = manager.settings;