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

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

概述

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

p5.js Web Editor, officially launched!

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

登录后查看全文