在 React 或 Vue 项目中集成 p5.js 的实例模式教程

一、为什么现代组件中必须使用实例模式

p5.js 最初的设计偏向艺术教育与快速原型开发，其官方教程最常见的是全局模式（Global Mode）。在全局模式下，开发者直接定义 window.setup 和 window.draw。p5 会在页面加载完成后自动寻找这两个函数，隐式创建默认画布（<canvas id="defaultCanvas0">），并强行将其追加到宿主页面的 document.body 最末端。

这种“简单粗暴”的做法在 React 或 Vue 的组件树体系下会引发三大不可接受的隐患：

• 挂载位置失控：生成的 Canvas 脱离了虚拟 DOM 的结构层级，无法直接遵循组件的 Flex/Grid 栅格或定位约束；
• 命名空间冲突：一个页面无法同时渲染两个以上的 p5 画布，后初始化的全局方法会直接覆盖先前挂载的逻辑；
• 无法清理与内存泄漏：在 SPA 路由跳转或弹窗关闭后，全局定时循环（requestAnimationFrame）仍在无意义轮询，Canvas 元素残留在 DOM 树中，造成 GPU 显存与 CPU 资源大量浪费。

实例模式（Instance Mode）正是 p5.js 为工程化项目提供的官方解法。它把全部 p5 方法（如 createCanvas、background、ellipse、noise 等）收敛到一个局部的实例对象 p 中，由开发者显式传入挂载容器 DOM，且赋予开发者精准销毁实例的 remove() 方法。

二、实例模式的语法基础与核心规范

实例模式的基本语法依赖一个接收 p 作为参数的闭包函数（通常约定命名为 sketch）。所有原生顶层 API 均作为 p 的属性访问：

// 实例模式闭包标准结构
const sketch = (p) => {
  // 必须把 setup 和 draw 挂载到 p 对象上
  p.setup = () => {
    p.createCanvas(400, 300);
  };

  p.draw = () => {
    p.background(240);
    p.fill(82, 103, 125);
    p.circle(p.mouseX, p.mouseY, 40);
  };
};

// 实例化：第一参数为闭包，第二参数为真实的 HTML DOM 节点
const myP5 = new p5(sketch, targetDomElement);

// 卸载与清理：终止内部 requestAnimationFrame 循环，移除 canvas
myP5.remove();

值得注意的是：在全局模式中可以直接调用的内置数学常量与预置变量（例如 PI、TWO_PI、CENTER、RGB、width、height），在实例模式中均需要前缀 p.，例如 p.PI、p.CENTER。

三、在 React 中集成 p5.js 的完整步骤与实现

在 React 18 / 19 函数组件中集成 p5.js，核心原则是：利用 useRef 持有容器 DOM 与 p5 实例指针，在 useEffect 中完成挂载，在 cleanup 回调中完成注销。

1. 环境安装

npm install p5
# 如果使用 TypeScript，补充类型声明库
npm install --save-dev @types/p5

2. 编写通用 React 画布组件

以下是一个具备响应式属性更新、尺寸自适应与干净生命周期销毁的标准 React 组件 P5Canvas.jsx：

import React, { useEffect, useRef } from 'react';
import p5 from 'p5';

export default function P5Canvas({ circleColor = '#52677D', speed = 1 }) {
  // 1. 声明容器 DOM 引用与 p5 实例引用
  const containerRef = useRef(null);
  const p5InstanceRef = useRef(null);
  
  // 2. 使用 ref 保存外部响应式 props，供 p5 的 draw 循环无闭包延迟地读取最新值
  const propsRef = useRef({ circleColor, speed });
  useEffect(() => {
    propsRef.current = { circleColor, speed };
  }, [circleColor, speed]);

  useEffect(() => {
    // 确保容器节点真实存在
    if (!containerRef.current) return;

    // 3. 构造实例模式闭包
    const sketch = (p) => {
      let x = 0;

      p.setup = () => {
        // 获取容器宽度，支持自适应布局
        const width = containerRef.current.clientWidth || 400;
        const height = containerRef.current.clientHeight || 300;
        p.createCanvas(width, height);
      };

      p.draw = () => {
        p.background(248, 250, 252);
        
        // 从 propsRef 读取最新组件状态，无需反复销毁实例
        const { circleColor: colorHex, speed: moveSpeed } = propsRef.current;
        
        x = (x + moveSpeed) % p.width;
        
        p.noStroke();
        p.fill(colorHex);
        p.ellipse(x, p.height / 2, 60, 60);
      };

      // 监听窗口尺寸变化，自适应重设画布尺寸
      p.windowResized = () => {
        if (containerRef.current) {
          p.resizeCanvas(
            containerRef.current.clientWidth,
            containerRef.current.clientHeight
          );
        }
      };
    };

    // 4. 创建实例并挂载到 containerRef
    p5InstanceRef.current = new p5(sketch, containerRef.current);

    // 5. 卸载清理函数：必须调用 remove() 彻底释放资源
    return () => {
      if (p5InstanceRef.current) {
        p5InstanceRef.current.remove();
        p5InstanceRef.current = null;
      }
    };
  }, []); // 仅在组件初次挂载时初始化一次

  return (
    <div 
      ref={containerRef} 
      style={{ width: '100%', height: '360px', position: 'relative' }} 
    />
  );
}

四、在 Vue 3 中集成 p5.js 的完整步骤与实现

在 Vue 3 组合式 API（<script setup>）中集成 p5.js，核心差异在于响应式系统的机制。强烈建议使用 shallowRef 存储 p5 实例指针，严禁使用普通的 ref()。

1. 为什么不能用 Vue 默认的 ref() 存储 p5 实例？

Vue 3 的 ref() 底层基于 Proxy 对对象进行递归深度代理。而 p5 实例内部包含数以百计的原型方法、WebGL 上下文引用、CanvasRenderingContext2D、原生事件监听器及状态栈。一旦被 Vue 递归 Proxy 劫持：

• 调用原生方法时可能会抛出 TypeError: Illegal invocation 报错；
• 在每一帧绘制时触发巨量无意义的依赖追踪，导致明显的帧率暴跌（FPS 从 60 跌至个位数）；
• 使用 shallowRef 只代理顶层 .value 读写，内部结构保持原始引用，完全避免代理冲突。

2. 编写 Vue 3 单文件组件 (SFC)

以下是标准单文件组件 P5VueCanvas.vue 的完整实现：

<template>
  <div class="p5-wrapper">
    <!-- 容器 DOM 引用 -->
    <div ref="containerRef" class="canvas-box"></div>
  </div>
</template>

<script setup>
import { ref, shallowRef, onMounted, onUnmounted, watch } from 'vue';
import p5 from 'p5';

// 接收外部 props
const props = defineProps({
  particleCount: {
    type: Number,
    default: 80
  },
  primaryColor: {
    type: String,
    default: '#52677D'
  }
});

// 模板引用：对应 template 中的 div
const containerRef = ref(null);

// 关键点：使用 shallowRef 规避深度响应式代理劫持
const p5Instance = shallowRef(null);

// 闭包内共享的运行期状态
let sketchState = {
  count: props.particleCount,
  color: props.primaryColor
};

// 监听外部 props 变动，平滑同步内部数据，无需重建实例
watch(
  () => [props.particleCount, props.primaryColor],
  ([newCount, newColor]) => {
    sketchState.count = newCount;
    sketchState.color = newColor;
  }
);

onMounted(() => {
  if (!containerRef.value) return;

  const sketch = (p) => {
    let particles = [];

    p.setup = () => {
      const width = containerRef.value.clientWidth || 500;
      const height = containerRef.value.clientHeight || 350;
      p.createCanvas(width, height);

      // 初始化粒子
      for (let i = 0; i < 200; i++) {
        particles.push({
          x: p.random(p.width),
          y: p.random(p.height),
          vx: p.random(-1, 1),
          vy: p.random(-1, 1)
        });
      }
    };

    p.draw = () => {
      p.background(255);
      p.fill(sketchState.color);
      p.noStroke();

      // 根据动态同步的粒子数进行局部绘制
      const activeCount = Math.min(sketchState.count, particles.length);
      for (let i = 0; i < activeCount; i++) {
        const pt = particles[i];
        pt.x = (pt.x + pt.vx + p.width) % p.width;
        pt.y = (pt.y + pt.vy + p.height) % p.height;
        p.circle(pt.x, pt.y, 8);
      }
    };

    p.windowResized = () => {
      if (containerRef.value) {
        p.resizeCanvas(
          containerRef.value.clientWidth,
          containerRef.value.clientHeight
        );
      }
    };
  };

  // 挂载实例
  p5Instance.value = new p5(sketch, containerRef.value);
});

onUnmounted(() => {
  // 必须显式注销
  if (p5Instance.value) {
    p5Instance.value.remove();
    p5Instance.value = null;
  }
});
</script>

<style scoped>
.p5-wrapper {
  width: 100%;
}
.canvas-box {
  width: 100%;
  height: 380px;
  border-radius: 8px;
  overflow: hidden;
  background: #F8FAFC;
}
</style>

五、组件状态与 p5 绘制循环的双向通信机制

在常规数据大屏或交互动画场景中，前端框架的响应式状态（UI 层）与 p5 画布（图形层）需要频繁通信。如果不加规范，很容易写出“每次 props 变化就重新 new p5”的极端低效代码。

1. 正确的下行通信：状态映射而不重建实例

p5 的 draw() 本质上是由浏览器 requestAnimationFrame 驱动的独立渲染线程循环。这意味着：只要我们在外部组件修改了某个对象或 Ref 的内部属性，draw() 在下一帧执行时就可以直接读取到最新数值，完全不需要触碰组件的 DOM 树或重建 WebGL 上下文。

• React 方案：使用 useRef 存储最新 props（如 propsRef.current = props），在 p.draw() 中直接解构 propsRef.current；
• Vue 方案：在 <script setup> 顶层声明普通 JavaScript 闭包变量（或在 sketch 对象上附加属性），通过 watch 响应式监听并赋值给闭包变量。

2. 正确的上行通信：画布事件向外派发

当用户在 p5 画布上触发交互（如点击命中某个粒子、完成手绘轨迹）时，可以通过在 sketch 闭包内直接调用 React 传入的事件函数（如 props.onShapeSelect(id)）或 Vue 的 emit('select', id)，完成从画布内部到外部 UI 组件的状态回传。

六、工程化避坑指南与常见问题核对

在实际项目落地的过程中，还会遇到诸如服务端渲染（SSR）兼容、动态自适应容器大小等特定工程挑战。对照以下检查表可快速排查绝大多数疑难故障。

七、总结

将 p5.js 集成到现代前端技术栈的本质，是在组件的声明式生命周期与 Canvas 的命令式渲染循环之间建立一条明确受控的隔离边界。

只要坚持使用实例模式（new p5(sketch, domNode)）、确保在卸载钩子中执行 remove() 回收资源、采用非深层响应式的引用持有实例，并通过闭包状态桥接数据，就能在 React 和 Vue 项目中既享受现代工程化组件体系的模块化优势，又发挥 p5.js 强大的图形表现力。