# Vue Canvas Engine

[![NPM Version](https://img.shields.io/npm/v/@iss-ai/vue-canvas-core.svg)](https://www.npmjs.com/package/@iss-ai/vue-canvas-core)
[![NPM Downloads](https://img.shields.io/npm/dt/@iss-ai/vue-canvas-core.svg)](https://www.npmjs.com/package/@iss-ai/vue-canvas-core)
[![License](https://img.shields.io/npm/l/@iss-ai/vue-canvas-core.svg)](https://github.com/iss-tools/vue-canvas-core/blob/main/LICENSE)

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

[English](./README.md) | [简体中文](./README.zh-CN.md)

---

## 🚀 项目介绍

**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 布局配置！

---

## 📦 快速启动

### 依赖安装与运行

```bash
# 安装所需依赖
pnpm install

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

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

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

---

## 📚 文档导读与核心架构

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

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

[API 协议与开发指南](./docs/api-sdk.md) 详细披露了底层的数据结构规范和交互接口：

- **`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/` 的源码）：

```vue
<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)](./LICENSE)** 协议。