yys-editor/docs/3build/EMBED_README.md

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. 测试嵌入式组件

在开发模式下测试组件：

# 启动开发服务器
npm run dev

# 访问测试页面（需要修改 main.js 引入 TestEmbed.vue）

2. 构建库文件

# 构建嵌入式组件库
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 中：

{
  "dependencies": {
    "yys-editor": "file:../yys-editor"
  }
}

然后：

cd ../onmyoji-wiki
npm install

方式 2：使用组件

<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. 安装依赖

   cd ../onmyoji-wiki
   npm install file:../yys-editor
   

2. 创建 MDC 组件

   <!-- components/content/YysEditor.vue -->
   <template>
     <div class="yys-editor-block" @click="openEditor">
       <YysEditorEmbed
         mode="preview"
         :data="flowData"
       />
       <button>✏️ 编辑流程图</button>
     </div>
   </template>
   

3. 在 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 延迟加载数据

📚 相关文档

• 设计文档
• 使用文档
• 项目计划

🤝 贡献

如有问题或建议，请提交 Issue 或 Pull Request。

📄 许可证

MIT