@iss-ai/vue-canvas-core

Vue Canvas Engine

基于 Vue 3 构建的、由 JSON 驱动的高级低代码 UI 引擎，完美支持动态大屏与 PPT 演示播放。

English | 简体中文

🚀 项目介绍

Vue Canvas Engine 是一个高度灵活的数据驱动可视化沙盒。有了它，您无需再编写重复冗长的 Vue 模板代码，而是通过统一的 JSON 协议来定义整个版面布局、UI 组件以及动画流转。它被设计为一个强大的 低代码 (Low-Code) 编排层，不仅能直接渲染基础的 HTML 标签，还能与第三方 UI 组件库（如 Element Plus, Ant Design Vue 等）无缝整合。

无论您是要搭建一个静态的 数据看板 (Dashboard)、构建高交互性的 低代码编辑器底座，还是要做一个充满电影感的 交互式幻灯片 (PPT)，本引擎都为您准备好了底层 API、状态管理以及完善的可视化外壳。

✨ 核心特性

• 数据驱动视图 (JSON-Driven): 画布 UI 完全由一组对象数组 (CanvasElementData) 描述。对 JSON 数据的任何修改都会实时映射到画布渲染上。
• 组件库无缝兼容: 借助 Vue 的动态 <component :is="..."> 渲染能力，引擎不仅支持挂载 div、span、img 等原生标签，也能直接挂载全局注册的任何 Vue 组件（如 el-button）。引擎甚至在内部代理了 props、slots 甚至表单输入类的 modelValue 双向绑定。
• PPT 演说稿模式: 引擎内置了一条强大的时间线总控 (Timeline Controller)。只要为元素配置 enterStep（入场步骤）和 exitStep（退场步骤），再搭配 animate.css 动画库与自带的音效系统，静态网页立刻化身为炫酷的幻灯片。
• 高度互动的编辑器底座: 引擎自带了一个开箱即用的可视化画布外壳，功能包含：
  • 自由拖拽定位、边缘缩放把手与多选框选。
  • 组件的成组 (Group) 与解组 (Ungroup)。
  • 空格键拖拽平移与滚轮无限缩放。
  • 智能网格吸附与边缘标尺。
  • 完善的撤销/重做 (Undo/Redo) 历史记录流。
• 多格式一键导出: 借助内建的 html2canvas 和 jsPDF 方案，您可以一键将辛勤排版好的画布导出为 JSON 配置、高清 PNG 截图或 PDF 文档。
• 国际化多语言 (i18n): 编辑器 UI 原生支持多语言环境（目前已支持中/英双语），可通过 setLanguage 接口一键无缝切换。
• AI-Agent 友好: 源码自带 docs/ai/ 预设提示词库。大语言模型可以利用这些预设身份，轻松地根据模糊的自然语言甚至一张截图，直接生成可以直接渲染在画布上的 JSON 布局配置！

📦 快速启动

依赖安装与运行

# 安装所需依赖
pnpm install

# 启动本地沙盒环境与可视化调试面板
pnpm dev

打开浏览器访问 http://localhost:5173/ 即可体验 Vue Canvas 的调试沙盒。

• 强烈建议点击顶部导航栏右上角的 "Load PPT" 按钮，体验自带的带有声效与动画的幻灯片模式。
• 利用右侧面板，您可以随意修改组件坐标、属性 (Props)、内联样式以及进出场动画。

📚 文档导读与核心架构

为了方便开发者快速上手以及让 AI Agent 无缝接入，项目提供了丰富的文档支持。

1. 引擎 API 与事件系统 (docs/api-sdk.md)

API 协议与开发指南 详细披露了底层的数据结构规范和交互接口：

• CanvasElementData 结构: 详细阐述了描述节点的 id, type, 坐标, props, slots 及 animation 动效对象的写法规则。
• 核心操作 API: 诸如 addElement, removeElement, updateElement, groupSelected, setPresentationMode 等方法的传参及作用。
• 事件机制: 包含极其细粒度的 Vue Emit 事件（如 @select, @element:move, @element:resize），帮助您轻松开发外部联动属性面板。

2. AI 提示词库与 Agent 接入规范 (docs/ai/ & SKILL.md)

本引擎旨在成为下一个世代 AI 自动写 UI 的绝佳渲染底座。在 docs/ai/ 下，我们沉淀了一套极具杀伤力的提示词模板：

• 视觉提取复刻 (Vision Extraction):
  • prompt-image-to-normal.md：指导多模态大模型“看图写 JSON”，逆向提取 UI 截图并在画板中实现静态重排。
  • prompt-image-to-presentation.md：不仅看图写排版，还会指令 AI 充当“动效导演”，自动分析视觉层级并分配 enterStep，将静态图脑补为动态幻灯片！
• 外部组件库智能提取:
  • prompt-repo-to-components.md & prompt-url-to-components.md：指挥 AI 从 Github Markdown 源码或官方 API 网页中抽取有价值的组件数据并生成标准的引入字典。
  • prompt-html-to-component.md：神奇的逆向工程模板。允许用户在任一网页的 Chrome F12 中拷贝一段极其混乱的 outerHTML 代码，AI 负责洗去垃圾代码，提纯复原为干净的 Canvas 节点。
• AI 开发者手册 (AGENT.md):
  • 这是写给具备 Autonomous (自主执行) 能力的代码 Agent 看的技术文档，指明了项目架构的边界以及响应式状态更新的军规。
• 外部框架整合 (SKILL.md):
  • 位于项目根目录的描述文件。符合规范的提示词框架（如 Dify / Coze 等）可以将本项目作为独立技能 (Skill) 外挂接入。

🛠 在您的项目中使用

虽然 playground/ 目录是一个完整的沙盒工程，但引擎本身是被设计为 Vue 组件包的（目前正待打包发布，您可以直接引用 src/components/ 的源码）：

<template>
  <div style="width: 100vw; height: 100vh;">
    <CanvasEditor
      ref="editorRef"
      :initial-elements="myData"
      mode="edit"
      theme="dark"
      @select="handleSelect"
      @change="handleCanvasChange"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { CanvasEditor } from '@iss-ai/vue-canvas-core';

const editorRef = ref(null);
const myData = [
  {
    id: 'btn_1',
    type: 'el-button',
    x: 100,
    y: 100,
    props: { type: 'primary' },
    slots: { default: '点我试试' },
  },
];

const handleSelect = selectedIds => {
  console.log('被选中的元素 ID 列表:', selectedIds);
};
</script>

📄 开源许可

本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 协议。