feat: 完成组件化改造 - 支持作为可嵌入组件使用

- 创建 YysEditorEmbed.vue 嵌入式组件 - 实现 preview/edit 双模式 - 配置 Vite library mode 构建 - 生成 ES Module + UMD + CSS 构建产物 - 完善设计文档和使用文档 - 更新 plan.md 标记阶段 2 完成构建产物: - dist/yys-editor.es.js (155KB, gzip: 35KB) - dist/yys-editor.umd.js (112KB, gzip: 31KB) - dist/yys-editor.css (69KB, gzip: 33KB) 相关文档: - docs/2design/ComponentArchitecture.md - docs/3build/YysEditorEmbed.md - docs/3build/EMBED_README.md - docs/4test/BUILD_TEST_REPORT.md
2026-03-05 15:05:27 +00:00 · 2026-02-20 17:23:59 +08:00
parent 92557d553b
commit 15bae3be81
13 changed files with 3553 additions and 424 deletions
--- a/docs/3build/EMBED_README.md
+++ b/docs/3build/EMBED_README.md
@@ -0,0 +1,260 @@
+# YysEditorEmbed 组件化改造
+
+## 📋 概述
+
+yys-editor 现在支持两种使用方式：
+
+1. **独立应用模式**：完整的流程图编辑应用（原有功能）
+2. **嵌入组件模式**：可嵌入到其他项目中的 Vue 组件（新增功能）
+
+## 🎯 完成的工作
+
+### ✅ 已完成
+
+1. **设计文档**
+   - 创建了 `docs/2design/ComponentArchitecture.md`
+   - 详细说明了组件化改造的架构设计
+
+2. **核心组件**
+   - 创建了 `src/YysEditorEmbed.vue` 嵌入式组件
+   - 支持 `preview` 和 `edit` 两种模式
+   - 实现了完整的 Props 和 Emits 接口
+   - 实现了状态隔离（使用局部 Pinia 实例）
+
+3. **构建配置**
+   - 创建了 `vite.config.lib.js` 库模式构建配置
+   - 更新了 `package.json` 导出配置
+   - 支持 ES Module 和 UMD 两种格式
+
+4. **文档和示例**
+   - 创建了 `docs/3usage/YysEditorEmbed.md` 使用文档
+   - 创建了 `examples/embed-demo.html` 示例页面
+   - 创建了 `src/TestEmbed.vue` 测试组件
+
+## 🚀 快速开始
+
+### 1. 测试嵌入式组件
+
+在开发模式下测试组件：
+
+```bash
+# 启动开发服务器
+npm run dev
+
+# 访问测试页面（需要修改 main.js 引入 TestEmbed.vue）
+```
+
+### 2. 构建库文件
+
+```bash
+# 构建嵌入式组件库
+npm run build:lib
+
+# 输出文件：
+# - dist/yys-editor.es.js (ES Module)
+# - dist/yys-editor.umd.js (UMD)
+# - dist/yys-editor.css (样式)
+```
+
+### 3. 在其他项目中使用
+
+#### 方式 1：本地引用（开发阶段）
+
+在 `onmyoji-wiki` 项目的 `package.json` 中：
+
+```json
+{
+  "dependencies": {
+    "yys-editor": "file:../yys-editor"
+  }
+}
+```
+
+然后：
+
+```bash
+cd ../onmyoji-wiki
+npm install
+```
+
+#### 方式 2：使用组件
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { YysEditorEmbed } from 'yys-editor'
+import 'yys-editor/style.css'
+
+const flowData = ref({
+  nodes: [],
+  edges: []
+})
+
+const handleSave = (data) => {
+  console.log('保存数据:', data)
+}
+</script>
+
+<template>
+  <YysEditorEmbed
+    mode="edit"
+    :data="flowData"
+    :height="600"
+    @save="handleSave"
+  />
+</template>
+```
+
+## 📖 API 文档
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `data` | `GraphData` | `undefined` | 初始数据 |
+| `mode` | `'preview' \| 'edit'` | `'edit'` | 模式 |
+| `width` | `string \| number` | `'100%'` | 宽度 |
+| `height` | `string \| number` | `'600px'` | 高度 |
+| `showToolbar` | `boolean` | `true` | 显示工具栏 |
+| `showPropertyPanel` | `boolean` | `true` | 显示属性面板 |
+| `showComponentPanel` | `boolean` | `true` | 显示组件库 |
+| `config` | `EditorConfig` | `{}` | 编辑器配置 |
+
+### Events
+
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| `update:data` | `(data: GraphData)` | 数据变更 |
+| `save` | `(data: GraphData)` | 保存 |
+| `cancel` | `()` | 取消 |
+| `error` | `(error: Error)` | 错误 |
+
+### 方法
+
+| 方法 | 说明 |
+|------|------|
+| `getGraphData()` | 获取当前画布数据 |
+| `setGraphData(data)` | 设置画布数据 |
+
+详细文档请查看：`docs/3usage/YysEditorEmbed.md`
+
+## 🧪 测试
+
+### 手动测试清单
+
+- [ ] **预览模式**
+  - [ ] 正确渲染流程图
+  - [ ] 只读，无法编辑
+  - [ ] 不显示工具栏、组件库、属性面板
+
+- [ ] **编辑模式**
+  - [ ] 完整编辑功能
+  - [ ] 工具栏正常工作
+  - [ ] 组件库可拖拽
+  - [ ] 属性面板可编辑
+  - [ ] 保存/取消按钮触发正确事件
+
+- [ ] **数据接口**
+  - [ ] Props 传入数据正确渲染
+  - [ ] 数据变更触发 update:data 事件
+  - [ ] 保存触发 save 事件
+  - [ ] 取消触发 cancel 事件
+
+- [ ] **状态隔离**
+  - [ ] 多个实例互不影响
+  - [ ] 不污染全局状态
+
+## 📁 文件结构
+
+```
+yys-editor/
+├── src/
+│   ├── YysEditorEmbed.vue          # 嵌入式组件 ⭐
+│   ├── TestEmbed.vue               # 测试组件
+│   ├── App.vue                     # 独立应用（保持不变）
+│   └── components/                 # 共享组件
+├── docs/
+│   ├── 2design/
+│   │   └── ComponentArchitecture.md  # 设计文档
+│   └── 3usage/
+│       └── YysEditorEmbed.md         # 使用文档
+├── examples/
+│   └── embed-demo.html             # 示例页面
+├── vite.config.js                  # 应用构建配置
+├── vite.config.lib.js              # 库构建配置 ⭐
+└── package.json                    # 更新了导出配置 ⭐
+```
+
+## 🔄 下一步
+
+### 在 onmyoji-wiki 中集成
+
+1. **安装依赖**
+   ```bash
+   cd ../onmyoji-wiki
+   npm install file:../yys-editor
+   ```
+
+2. **创建 MDC 组件**
+   ```vue
+   <!-- components/content/YysEditor.vue -->
+   <template>
+     <div class="yys-editor-block" @click="openEditor">
+       <YysEditorEmbed
+         mode="preview"
+         :data="flowData"
+       />
+       <button>✏️ 编辑流程图</button>
+     </div>
+   </template>
+   ```
+
+3. **在 Markdown 中使用**
+   ```markdown
+   ::yys-editor{id="flow-1"}
+   ::
+   ```
+
+## 📝 注意事项
+
+### 状态隔离
+
+嵌入式组件使用局部 Pinia 实例，不会影响宿主应用的状态管理。
+
+### 样式隔离
+
+所有样式都使用 scoped，并添加了 `.yys-editor-embed` 命名空间。
+
+### 依赖管理
+
+以下依赖被标记为 `peerDependencies`，需要宿主项目提供：
+- vue
+- element-plus
+- pinia
+- @logicflow/core
+- @logicflow/extension
+- @logicflow/vue-node-registry
+
+## 🐛 已知问题
+
+1. **预览模式初始化延迟**
+   - 预览模式需要等待 DOM 渲染完成后初始化 LogicFlow
+   - 已使用 `setTimeout` 解决
+
+2. **编辑模式数据加载**
+   - 编辑模式需要等待 FlowEditor 组件初始化完成
+   - 已使用 `setTimeout` 延迟加载数据
+
+## 📚 相关文档
+
+- [设计文档](./docs/2design/ComponentArchitecture.md)
+- [使用文档](./docs/3usage/YysEditorEmbed.md)
+- [项目计划](./docs/1management/plan.md)
+
+## 🤝 贡献
+
+如有问题或建议，请提交 Issue 或 Pull Request。
+
+## 📄 许可证
+
+MIT
--- a/docs/3build/YysEditorEmbed.md
+++ b/docs/3build/YysEditorEmbed.md
@@ -0,0 +1,503 @@
+# YysEditorEmbed 使用文档
+
+## 简介
+
+YysEditorEmbed 是 yys-editor 的可嵌入式组件版本，可以作为 Vue 组件集成到其他项目中。
+
+## 安装
+
+### 方式 1：本地引用（开发阶段）
+
+在 `package.json` 中添加：
+
+```json
+{
+  "dependencies": {
+    "yys-editor": "file:../yys-editor"
+  }
+}
+```
+
+然后运行：
+
+```bash
+npm install
+```
+
+### 方式 2：npm 包（发布后）
+
+```bash
+npm install yys-editor
+```
+
+## 基础使用
+
+### 1. 引入组件
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { YysEditorEmbed } from 'yys-editor'
+import 'yys-editor/style.css'
+
+const flowData = ref({
+  nodes: [],
+  edges: []
+})
+</script>
+
+<template>
+  <YysEditorEmbed
+    :data="flowData"
+    mode="edit"
+    :height="600"
+  />
+</template>
+```
+
+### 2. 预览模式
+
+```vue
+<template>
+  <YysEditorEmbed
+    :data="flowData"
+    mode="preview"
+    :height="400"
+  />
+</template>
+```
+
+### 3. 编辑模式
+
+```vue
+<template>
+  <YysEditorEmbed
+    :data="flowData"
+    mode="edit"
+    :height="600"
+    @save="handleSave"
+    @cancel="handleCancel"
+  />
+</template>
+
+<script setup>
+const handleSave = (data) => {
+  console.log('保存数据:', data)
+  // 保存到后端或本地
+}
+
+const handleCancel = () => {
+  console.log('取消编辑')
+}
+</script>
+```
+
+## API 文档
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `data` | `GraphData` | `undefined` | 初始数据（LogicFlow GraphData 格式） |
+| `mode` | `'preview' \| 'edit'` | `'edit'` | 模式：预览或编辑 |
+| `width` | `string \| number` | `'100%'` | 宽度 |
+| `height` | `string \| number` | `'600px'` | 高度 |
+| `showToolbar` | `boolean` | `true` | 是否显示工具栏（仅编辑模式） |
+| `showPropertyPanel` | `boolean` | `true` | 是否显示属性面板（仅编辑模式） |
+| `showComponentPanel` | `boolean` | `true` | 是否显示组件库（仅编辑模式） |
+| `config` | `EditorConfig` | `{}` | 编辑器配置 |
+
+### Events
+
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| `update:data` | `(data: GraphData)` | 数据变更（实时） |
+| `save` | `(data: GraphData)` | 保存（用户点击保存按钮） |
+| `cancel` | `()` | 取消（用户点击取消按钮） |
+| `error` | `(error: Error)` | 错误 |
+
+### 方法（通过 ref 调用）
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `getGraphData()` | - | `GraphData \| null` | 获取当前画布数据 |
+| `setGraphData(data)` | `GraphData` | `void` | 设置画布数据 |
+
+### 类型定义
+
+```typescript
+interface GraphData {
+  nodes: NodeData[]
+  edges: EdgeData[]
+}
+
+interface NodeData {
+  id: string
+  type: string
+  x: number
+  y: number
+  properties?: Record<string, any>
+  text?: { value: string }
+}
+
+interface EdgeData {
+  id: string
+  type: string
+  sourceNodeId: string
+  targetNodeId: string
+  properties?: Record<string, any>
+}
+
+interface EditorConfig {
+  grid?: boolean
+  snapline?: boolean
+  keyboard?: boolean
+  theme?: 'light' | 'dark'
+  locale?: 'zh' | 'ja' | 'en'
+}
+```
+
+## 使用场景
+
+### 场景 1：在 Wiki 中作为块插件
+
+```vue
+<template>
+  <div class="yys-editor-block">
+    <!-- 预览模式 -->
+    <div v-if="!isEditing" @click="startEdit">
+      <YysEditorEmbed
+        mode="preview"
+        :data="flowData"
+        :height="400"
+      />
+      <button class="edit-btn">✏️ 编辑流程图</button>
+    </div>
+
+    <!-- 编辑模式（弹窗） -->
+    <el-dialog v-model="isEditing" fullscreen>
+      <YysEditorEmbed
+        mode="edit"
+        :data="flowData"
+        :height="'100%'"
+        @save="handleSave"
+        @cancel="handleCancel"
+      />
+    </el-dialog>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { YysEditorEmbed } from 'yys-editor'
+import 'yys-editor/style.css'
+
+const isEditing = ref(false)
+const flowData = ref({
+  nodes: [],
+  edges: []
+})
+
+const startEdit = () => {
+  isEditing.value = true
+}
+
+const handleSave = (data) => {
+  flowData.value = data
+  isEditing.value = false
+  // 保存到文档
+  saveToDocument(data)
+}
+
+const handleCancel = () => {
+  isEditing.value = false
+}
+
+const saveToDocument = async (data) => {
+  // 调用 API 保存到后端
+  await fetch('/api/documents/update', {
+    method: 'POST',
+    body: JSON.stringify({ flowData: data })
+  })
+}
+</script>
+
+<style scoped>
+.yys-editor-block {
+  margin: 20px 0;
+}
+
+.edit-btn {
+  margin-top: 10px;
+  padding: 8px 16px;
+  background: #409eff;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+</style>
+```
+
+### 场景 2：在管理后台中使用
+
+```vue
+<template>
+  <div class="admin-editor">
+    <YysEditorEmbed
+      ref="editorRef"
+      mode="edit"
+      :data="flowData"
+      :height="'calc(100vh - 100px)'"
+      @save="handleSave"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+import { YysEditorEmbed } from 'yys-editor'
+import 'yys-editor/style.css'
+
+const editorRef = ref()
+const flowData = ref(null)
+
+// 从后端加载数据
+onMounted(async () => {
+  const response = await fetch('/api/flow/123')
+  flowData.value = await response.json()
+})
+
+const handleSave = async (data) => {
+  // 保存到后端
+  await fetch('/api/flow/123', {
+    method: 'PUT',
+    body: JSON.stringify(data)
+  })
+  alert('保存成功')
+}
+
+// 手动获取数据
+const getData = () => {
+  const data = editorRef.value?.getGraphData()
+  console.log('当前数据:', data)
+}
+</script>
+```
+
+### 场景 3：只读展示
+
+```vue
+<template>
+  <div class="flow-display">
+    <h2>流程图展示</h2>
+    <YysEditorEmbed
+      mode="preview"
+      :data="flowData"
+      :height="500"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { YysEditorEmbed } from 'yys-editor'
+import 'yys-editor/style.css'
+
+const flowData = ref({
+  nodes: [
+    {
+      id: 'node1',
+      type: 'rect',
+      x: 100,
+      y: 100,
+      text: { value: '开始' }
+    }
+  ],
+  edges: []
+})
+</script>
+```
+
+## 高级用法
+
+### 自定义配置
+
+```vue
+<template>
+  <YysEditorEmbed
+    :data="flowData"
+    mode="edit"
+    :config="{
+      grid: true,
+      snapline: true,
+      keyboard: true,
+      theme: 'light',
+      locale: 'zh'
+    }"
+  />
+</template>
+```
+
+### 监听数据变化
+
+```vue
+<template>
+  <YysEditorEmbed
+    :data="flowData"
+    mode="edit"
+    @update:data="handleDataChange"
+  />
+</template>
+
+<script setup>
+const handleDataChange = (data) => {
+  console.log('数据变化:', data)
+  // 实时保存到本地存储
+  localStorage.setItem('flowData', JSON.stringify(data))
+}
+</script>
+```
+
+### 错误处理
+
+```vue
+<template>
+  <YysEditorEmbed
+    :data="flowData"
+    mode="edit"
+    @error="handleError"
+  />
+</template>
+
+<script setup>
+const handleError = (error) => {
+  console.error('编辑器错误:', error)
+  alert(`发生错误: ${error.message}`)
+}
+</script>
+```
+
+## 样式定制
+
+### 覆盖默认样式
+
+```vue
+<style>
+/* 修改编辑器背景色 */
+.yys-editor-embed {
+  background: #ffffff !important;
+}
+
+/* 修改画布背景 */
+.yys-editor-embed .lf-canvas {
+  background: #f9f9f9 !important;
+}
+</style>
+```
+
+### 响应式布局
+
+```vue
+<template>
+  <div class="responsive-editor">
+    <YysEditorEmbed
+      :data="flowData"
+      mode="edit"
+      width="100%"
+      :height="editorHeight"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue'
+
+const editorHeight = ref(600)
+
+const updateHeight = () => {
+  editorHeight.value = window.innerHeight - 200
+}
+
+onMounted(() => {
+  updateHeight()
+  window.addEventListener('resize', updateHeight)
+})
+
+onUnmounted(() => {
+  window.removeEventListener('resize', updateHeight)
+})
+</script>
+```
+
+## 常见问题
+
+### Q: 如何在 Nuxt 3 中使用？
+
+A: 在 Nuxt 3 中，需要将组件设置为客户端渲染：
+
+```vue
+<template>
+  <ClientOnly>
+    <YysEditorEmbed
+      :data="flowData"
+      mode="edit"
+    />
+  </ClientOnly>
+</template>
+```
+
+### Q: 如何保存和加载数据？
+
+A: 使用 `getGraphData()` 和 `setGraphData()` 方法：
+
+```vue
+<script setup>
+const editorRef = ref()
+
+// 保存
+const save = () => {
+  const data = editorRef.value?.getGraphData()
+  localStorage.setItem('flowData', JSON.stringify(data))
+}
+
+// 加载
+const load = () => {
+  const data = JSON.parse(localStorage.getItem('flowData'))
+  editorRef.value?.setGraphData(data)
+}
+</script>
+```
+
+### Q: 如何禁用某些 UI 元素？
+
+A: 使用 Props 控制：
+
+```vue
+<template>
+  <YysEditorEmbed
+    mode="edit"
+    :show-toolbar="false"
+    :show-component-panel="false"
+  />
+</template>
+```
+
+### Q: 如何集成到现有项目？
+
+A: 参考上面的"场景 1：在 Wiki 中作为块插件"示例。
+
+## 浏览器兼容性
+
+- Chrome >= 90
+- Firefox >= 88
+- Safari >= 14
+- Edge >= 90
+
+## 许可证
+
+MIT
+
+## 支持
+
+如有问题，请提交 Issue 或联系开发团队。