element-less-aicanvas

Vue 3 AI 无限画布编辑器组件（含 3D 导演台），开箱即用。传入 projectId 与一个 adapter（接口适配器）即可加载完整画布。

组件内部不含任何 axios / URL / 鉴权 / 路由 / 宿主状态 —— 所有后端交互都通过你实现的 adapter 完成。

安装

pnpm add element-less-aicanvas element-less-tiptab
# peer 依赖（宿主需已安装）：vue ^3.5、pinia ^2、naive-ui ^2

使用

<script setup lang="ts">
import { ElsAiCanvas } from 'element-less-aicanvas'
import type { AiCanvasAdapter } from 'element-less-aicanvas'
import 'element-less-aicanvas/style.css'

// 实现适配器：把三类接口（模型 / 任务 / 项目）对接到你的后端
const adapter: AiCanvasAdapter = {
  // 模型配置类
  fetchModels: ({ modelType, size }) => myApi.queryModels({ modelType, size }),
  calcImagePrice: p => myApi.getDrawFree(p),
  calcVideoPrice: p => myApi.getVideoFree(p),
  // 生成任务类
  submitJob: payload => myApi.submitJob(payload),        // → { jobId }
  getJobStatus: jobId => myApi.getJobStatus(jobId),      // → { status, result, progress }
  cancelJob: jobId => myApi.cancelJob(jobId),            // 可选
  // 独立 AI VRM 动画导演台（可选）
  aiDirectorChat: request => myApi.aiDirectorChat(request),
  aiDirectorMotionGenerate: request => myApi.aiDirectorMotionGenerate(request),
  // 公共 / 项目类
  loadProject: id => myApi.getProject(id),               // → { id, name, nodes, edges, viewport }
  saveProject: (id, payload) => myApi.saveProject(id, payload),
  uploadFile: file => myApi.upload(file),                // → OSS URL
  fetchGallery: p => myApi.galleryList(p),               // 可选，不传则隐藏「我的图库」
}
</script>

<template>
  <ElsAiCanvas
    :project-id="123"
    :adapter="adapter"
    :enable-ai-director-stage="true"
    :message="$message"
    @error="onError"
    @back="goBack"
  />
</template>

普通“导演台”不读取任何 AI Handler。独立“AI 导演台”只有在 enableAiDirectorStage 开启且提供 aiDirectorChat 时才出现在创建入口；aiDirectorMotionGenerate 返回 3–15 秒、30 FPS 的 VRM 动作候选，候选在用户选用前不会写入场景。已保存的 AI 导演台缺少 Handler 时仍可查看和手动编辑。

发布包内的 VRM 位于 models/vrm。宿主需将该目录部署到静态资源服务，并通过 assetBaseUrl 指向其上级路径；本地 demo 默认从 /models/vrm 加载。

Props

| Prop | 类型 | 默认 | 说明 | |------|------|------|------| | projectId | number \| string | — | 必传，画布项目 id | | adapter | AiCanvasAdapter | — | 必传，接口适配器 | | pollInterval | number | 2500 | 任务轮询间隔 ms | | pollMax | number | 240 | 最大轮询次数 | | saveDebounce | number | 260 | 防抖保存间隔 ms | | enableDirectorStage | boolean | true | 是否显示导演台节点 | | enableAiDirectorStage | boolean | false | 是否显示独立 AI VRM 动画导演台节点（还需 adapter.aiDirectorChat） | | canvasAgent | CanvasAgentConfig | — | 画布 Agent 配置；必须包含 agentId 且实现 adapter.runCanvasAgent | | canvasAgentOpen | boolean | false | Agent 抽屉受控状态，使用 v-model:canvas-agent-open；组件不内置入口按钮 | | enableMiniMap | boolean | true | 是否显示小地图 | | enableFileDrop | boolean | true | 是否允许从操作系统拖入文件；图片创建纯图片节点，其他文件创建文件节点并上传 | | message | CanvasMessage | console | 可选，自定义消息提示（如 naive-ui 的 useMessage()） |

Events

| 事件 | 说明 | |------|------| | update:projectName | 项目名变更 | | save-success | 保存成功 | | load-error | 加载项目失败 | | error | 运行时错误（同时会调用 message.error） | | back | 顶栏返回按钮点击（导航由宿主处理） | | update:canvasAgentOpen | Agent 抽屉请求打开或关闭；供 v-model:canvas-agent-open 使用 |

画布 Agent 支持 @ 引用模型和当前画布节点、Skill、流式消息、引导问答， 以及在显式授权后创建画布节点和可点击定位的媒体产物卡片。 完整配置、请求 parts、事件及反馈结构见 画布 Agent 接入文档。

近期画布功能调整

• 支持从操作系统向画布或节点上传槽拖入文件，并支持在图片上传入口粘贴图片。
• 优化普通节点组的拖入捕获、自动贴合、组内布局和整组顺序执行；节点校验失败后停止后续任务。
• 短连线保持可删除，节点组固定在背景层，避免选中后遮挡普通节点和连线。
• 图片、视频、音频或文件输出被替换后，会清理旧素材身份并向下游提供当前最新资源。

宿主若维护本地源码副本，应按功能增量同步；弹窗层级和拖拽反馈样式可根据宿主设计体系自行取舍。

本地运行 Demo（验证迁移完整性）

仓库内置了一套带虚拟数据的 mock 适配器，无需后端即可跑通画布：

pnpm install
pnpm dev      # 打开终端提示的 http://localhost:5xxx

Demo 位于 demo/：

• demo/mockAdapter.ts —— 内存实现的 AiCanvasAdapter：虚拟模型列表、随机图片（picsum）、模拟异步生成任务（提交 5 秒后返回结果）、base64 本地上传、随机图库。
• demo/App.vue —— 用 NMessageProvider 包裹 ElsAiCanvas，顶部提供「加载演示画布 / 加载空白画布」切换。

「演示画布」预置了各类节点（文本注解、素材图、上传、绘画、视频、文本、分镜、导演台）与两条连线，可直接验证：节点渲染、选中配置面板、模型选择、参考图上传、提交生成并轮询出结果、防抖自动保存、图片选择器「我的图库」、导演台 3D 场景与截图发送。

说明

• 用户态不含在组件内：积分余额、用户头像、品牌 logo 由宿主在组件外渲染。
• 导演台：基于 three.js，作为画布内节点内置，同时导出 DirectorStage 组件供高级用法。
• @提及编辑器：依赖已发布的 element-less-tiptab 包。