Shadow Editor Pro 公共接口

公共接口提供文件访问、文件下载、文件上传等基础功能，以及Electron特定的接口。

文件访问

文件访问接口用于直接访问服务器上的文件资源。

API 接口

1. 访问文件

接口: GET /api/file/{type}/{filename}

描述: 访问指定类型的文件资源

路径参数:

示例请求:

GET /api/file/mesh/cube.gltf
GET /api/file/screenshot/screenshot_001.jpg
GET /api/file/typeface/helvetiker_regular.typeface.json

响应: 直接返回文件内容

文件下载

文件下载接口用于下载资源文件。

API 接口

1. 下载文件

接口: GET /api/download/{type}/{id}

描述: 下载指定资源文件

路径参数:

示例请求:

GET /api/download/mesh/1
GET /api/download/scene/5
GET /api/download/material/3

响应: 触发浏览器下载文件

文件上传

文件上传接口用于上传各种类型的文件资源。

API 接口

1. 上传缩略图

接口: POST /api/thumbnail/add

描述: 上传图片文件，自动生成缩略图

请求参数:

• Content-Type: multipart/form-data

响应示例:

{
  "success": true,
  "data": [
    {
      "id": "1",
      "filename": "thumbnail.jpg",
      "url": "/thumbnails/thumbnail.jpg",
      "size": 16384
    }
  ]
}

2. 上传模型文件

接口: POST /api/mesh/add

描述: 上传模型文件

请求参数:

• Content-Type: multipart/form-data

支持的模型格式:

• 3D Studio: .3ds
• 3D Manufacturing: .3mf
• Additive Manufacturing: .amf
• Assimp: .assimp
• Away3D: .awd
• Babylon.js: .babylon
• BVH Animation: .bvh
• Compressed Triangle Mesh: .ctm
• Collada: .dae
• Draco: .drc
• Autodesk FBX: .fbx
• G-Code: .gcode
• GLTF: .gltf, .glb
• Three.js JSON: .js, .json
• Google Earth KMZ: .kmz
• Quake MD2: .md2
• Medical Image: .nrrd
• Wavefront OBJ: .obj
• Point Cloud Data: .pcd
• Protein Data Bank: .pdb
• PlayCanvas: .playcanvas
• Stanford PLY: .ply
• MikuMikuDance: .pmd, .pmx
• 3D Systems STL: .stl
• VRM: .vrm
• VRML: .vrml, .wrl
• VTK: .vtk
• DirectX X: .x

响应示例:

{
  "success": true,
  "message": "模型上传成功",
  "data": {
    "id": "1",
    "url": "/meshes/new_model.glb"
  }
}

3. 上传材质文件

接口: POST /api/material/add

描述: 保存材质到材质库

请求参数:

响应示例:

{
  "success": true,
  "message": "材质保存成功"
}

4. 上传动画文件

接口: POST /api/animation/add

描述: 上传动画文件

请求参数:

• Content-Type: multipart/form-data

支持的动画格式:

• MMD Animation: .vmd
• MMD Pose: .vpd

响应示例:

{
  "success": true,
  "message": "动画上传成功"
}

5. 上传音频文件

接口: POST /api/audio/add

描述: 上传音频文件

请求参数:

• Content-Type: multipart/form-data

支持的音频格式:

• MP3: .mp3
• WAV: .wav
• OGG: .ogg

响应示例:

{
  "success": true,
  "message": "音频上传成功"
}

6. 上传视频文件

接口: POST /api/video/add

描述: 上传视频文件

请求参数:

• Content-Type: multipart/form-data

支持的视频格式:

• MP4: .mp4
• WebM: .webm

响应示例:

{
  "success": true,
  "message": "视频上传成功"
}

7. 上传贴图文件

接口: POST /api/map/add

描述: 上传贴图文件

请求参数:

• Content-Type: multipart/form-data

支持的贴图格式:

• 图片: .png, .jpg, .gif, .webp
• HDR: .hdr
• 视频: .mp4, .webm

天空盒说明: 上传天空盒时需要上传6张图片，文件名分别为：

• px.jpg - x轴正向
• nx.jpg - x轴负向
• py.jpg - y轴正向
• ny.jpg - y轴负向
• pz.jpg - z轴正向
• nz.jpg - z轴负向

响应示例:

{
  "success": true,
  "message": "贴图上传成功"
}

8. 上传字体文件

接口: POST /api/typeface/add

描述: 上传字体文件

请求参数:

• Content-Type: multipart/form-data

支持的字体格式:

• TrueType: .ttf
• OpenType: .otf
• JSON: .json (Typeface JSON)

响应示例:

{
  "success": true,
  "message": "字体上传成功"
}

9. 上传截图文件

接口: POST /api/screenshot/add

描述: 保存截图

请求参数:

• Content-Type: multipart/form-data

响应示例:

{
  "success": true,
  "message": "截图保存成功"
}

Electron接口

Electron接口提供桌面应用特有的功能，仅在Electron环境中可用。

API 接口

1. 获取应用信息

接口: GET /api/electron/info

描述: 获取Electron应用信息

响应示例:

{
  "success": true,
  "data": {
    "name": "Shadow Editor Pro",
    "version": "0.0.1",
    "platform": "win32",
    "arch": "x64"
  }
}

2. 打开系统对话框

接口: POST /api/electron/dialog

描述: 打开系统文件选择对话框

请求参数:

filters格式示例:

[
  {
    "name": "Images",
    "extensions": ["jpg", "png", "gif"]
  },
  {
    "name": "All Files",
    "extensions": ["*"]
  }
]

响应示例:

{
  "success": true,
  "data": {
    "canceled": false,
    "filePaths": ["/path/to/file.jpg"]
  }
}

3. 获取应用路径

接口: GET /api/electron/path/{name}

描述: 获取指定路径

路径参数:

示例请求:

GET /api/electron/path/home
GET /api/electron/path/userData
GET /api/electron/path/temp

响应示例:

{
  "success": true,
  "data": {
    "path": "C:\\Users\\Username\\AppData\\Roaming\\ShadowEditorPro"
  }
}

4. 打开外部链接

接口: POST /api/electron/open-external

描述: 在系统默认浏览器中打开链接

请求参数:

响应示例:

{
  "success": true,
  "message": "外部链接已打开"
}

5. 窗口控制

接口: POST /api/electron/window

描述: 控制Electron窗口

请求参数:

action可选值:

• minimize: 最小化窗口
• maximize: 最大化窗口
• restore: 还原窗口
• close: 关闭窗口

响应示例:

{
  "success": true,
  "message": "窗口操作成功"
}

6. 全屏切换

接口: POST /api/electron/fullscreen

描述: 切换窗口全屏状态

请求参数:

响应示例:

{
  "success": true,
  "message": "全屏状态已切换"
}

通用响应格式

所有API接口的响应都遵循统一的格式：

成功响应

{
  "success": true,
  "data": {
    /* 响应数据 */
  },
  "message": "操作成功"
}

错误响应

{
  "success": false,
  "message": "错误描述信息",
  "code": 400
}

错误代码

请求限制

文件大小限制

请求频率限制

• 每个IP每分钟最多100次请求
• 文件上传操作每分钟最多5次

使用示例

JavaScript/TypeScript 示例

import axios from 'axios'

// 上传模型文件
async function uploadMesh(file: File, name?: string) {
  const formData = new FormData()
  formData.append('file', file)
  if (name) {
    formData.append('name', name)
  }

  const response = await axios.post('/api/mesh/add', formData, {
    headers: {
      'Content-Type': 'multipart/form-data'
    }
  })

  return response.data
}

// 下载场景文件
async function downloadScene(sceneId: string) {
  window.location.href = `/api/download/scene/${sceneId}`
}

// 获取场景列表
async function getSceneList() {
  const response = await axios.get('/api/scene/list')
  return response.data.data
}

cURL 示例

# 上传模型文件
curl -X POST http://localhost:3000/api/mesh/add \
  -F "file=@/path/to/model.gltf" \
  -F "name=我的模型"

# 获取场景列表
curl http://localhost:3000/api/scene/list

# 下载场景
curl -O http://localhost:3000/api/download/scene/1