Processing/p5.js Web Editor 公共API详解

2026-02-04 05:06:44作者：谭伦延

The p5.js Editor is a website for creating p5.js sketches, with a focus on making coding accessible and inclusive for artists, designers, educators, beginners, and anyone else! You can create, share, or remix p5.js sketches without needing to download or configure anything.

项目地址：https://gitcode.com/gh_mirrors/p5/p5.js-web-editor

概述

Processing/p5.js Web Editor提供了一个功能强大的公共API，允许开发者以编程方式将数据导入编辑器环境。这个API特别适合需要批量创建、管理p5.js项目的场景，为自动化工作流提供了可能。

认证机制

API采用基于个人访问令牌(Personal Access Token)的认证方式：

令牌获取：用户需在编辑器设置页面生成专属访问令牌
认证方式：采用Basic Auth认证方案
请求头格式：需要将用户名:令牌进行base64编码后放入Authorization头

示例认证头：

Authorization: Basic cDU6YWJjMTIzYWJj

API版本控制

API采用版本化设计，当前版本为v1，访问路径需包含版本号：

http://editor.p5js.org/api/v1

核心数据模型

项目(Sketch)结构

{
  "id": "唯一标识符",
  "name": "项目名称",
  "files": "文件目录结构",
  "slug": "URL友好标识(可选)"
}

重要约束：

必须包含至少一个.html文件
如未提供.html文件，系统会自动生成默认的index.html和style.css
slug必须是URL安全且唯一的字符串

文件系统结构

API支持两种文件类型：

直接文件(DirectFile) - 存储在编辑器数据库中的可编辑文件

{
  "content": "文件内容(UTF-8编码)"
}

引用文件(ReferencedFile) - 托管在外部服务器的文件

{
  "url": "外部文件URL"
}

目录结构使用嵌套的键值对表示，键为文件名/目录名，值为文件内容或子目录：

{
  "index.html": {"content": "<html>...</html>"},
  "assets": {
    "files": {
      "image.png": {"url": "https://example.com/image.png"}
    }
  }
}

API端点详解

1. 获取用户项目列表

端点：GET /:user/sketches

功能：列出指定用户的所有项目(仅元数据，不含文件内容)

响应示例：

{
  "sketches": [
    {"id": "H1PLJg8_", "name": "示例项目1"},
    {"id": "Bkhf0APpg", "name": "示例项目2"}
  ]
}

2. 创建新项目

端点：POST /:user/sketches

请求体：完整的Sketch对象

特殊处理：

自动创建默认HTML文件(当请求中未提供时)
支持嵌套目录结构

成功响应：

{"id": "新项目ID"}

错误代码：

422：文件验证失败/不支持的格式/slug已存在

3. 删除项目

端点：DELETE /:user/sketches/:id

注意：该操作将永久删除项目及其所有文件

响应代码：

200：删除成功
404：项目不存在

最佳实践建议

文件组织：合理使用嵌套目录结构保持项目整洁
错误处理：特别注意422状态码的响应，包含详细的验证错误信息
性能考虑：对于大型文件，考虑使用ReferencedFile引用外部资源
默认文件：利用自动生成HTML功能简化简单项目的创建流程

开发环境配置

如需在本地开发环境中启用访问令牌UI，需在环境配置中设置：

UI_ACCESS_TOKEN_ENABLED=true

通过这套API，开发者可以实现与Processing/p5.js Web Editor的深度集成，构建自动化的工作流程，提升创意编程的效率。

p5.js-web-editor