KT Template Online Playground

kt-template-online-playground 是 KT Template Online 的在线编辑器。项目基于 @vue/repl 改造，负责编辑 Vue SFC 模板、预览运行效果、读取前台传入的组件信息，并在保存时截图上传 MinIO 后写入后端组件数据。

技术栈

• Vue 3 + TypeScript
• Vite
• @vue/repl
• Monaco Editor / CodeMirror
• Axios
• MinIO 上传接口
• pnpm

功能概览

• 在线编辑 Vue 单文件组件。
• 实时编译并在 iframe 预览运行结果。
• 支持从 URL hash 恢复编辑器文件状态。
• 读取 URL query 初始化组件 id、name、type、componentType。
• 保存时自动截取预览区图片，上传到 MinIO，并把图片地址写入组件 image 字段。
• 根据是否存在 id 自动调用新增或编辑接口。

目录结构

src
  api/                 # axios 封装和组件/字典/MinIO 接口
  editor/              # 文件列表、编辑器容器、编辑器适配
  output/              # 预览、沙箱、SSR 输出
  monaco/              # Monaco 语言服务和资源加载
  codemirror/          # CodeMirror 编辑器
  template/            # 默认模板
  PlaygroundHeader.vue # 组件表单、截图上传、保存入口
  Repl.vue             # 编辑器主体
  store.ts             # REPL 文件状态、序列化和反序列化
  index.ts             # 包导出入口
test/main.ts           # 本地 Playground 页面入口

环境变量

仓库只提交 .env.example，真实 .env.development 和 .env.production 保留在本地。

VITE_APP_API_BASE=/api
VITE_APP_PROXY=http://localhost:48085/
VITE_APP_ADMIN_LOGIN=http://localhost:5999/auth/login

关键变量：

变量	说明
VITE_APP_API_BASE	前端请求前缀，默认 /api
VITE_APP_PROXY	后端服务地址，Vite dev server 会把 /api 代理到这里
VITE_APP_ADMIN_LOGIN	后台登录页地址，保存组件接口 401 时会带 redirect 跳转到这里

启动

项目 .node-version 为 lts/*。Windows 下如别名不可用，先用 nvm ls 查看已安装 LTS，再切到具体版本。

pnpm install
pnpm dev

常用命令：

pnpm dev          # 本地 Playground 页面，默认端口 48090
pnpm typecheck    # 类型检查
pnpm build        # 构建库产物
pnpm build-preview
pnpm lint

URL 数据约定

Playground 同时使用 query 和 hash：

• query 保存组件业务信息：id、name、type、componentType。
• hash 保存 store.serialize() 生成的编辑器文件状态。
• 保存成功后会用 history.replaceState 同步 query 和最新 hash。

前台跳转示例：

http://localhost:48090/?id=xxx&name=基础折线图&type=1&componentType=1#...

保存流程

PlaygroundHeader.vue 是保存入口：

1. 从 query 读取组件信息。
2. 请求 /dict/getDictByKey 和 /dict/getComponentDictByType 初始化类型下拉。
3. 通过当前 iframe 预览内容生成截图。
4. 调用 /minio/upload 上传截图，获取返回的 url。
5. 组装 name、type、componentType、image、template。
6. 有 id 时调用 /component/update，没有 id 时调用 /component/save。
7. 新增成功后把后端返回的 id 写回 query。

接口约定

接口集中在 src/api：

• request.ts：axios 实例，统一处理 code !== 200 的错误，并在组件接口 401 时跳后台登录。
• auth.ts：复用后台登录态，持久化 accessToken、用户信息和权限码，支持通过刷新 token cookie 自动续期。
• component.ts：新增和编辑组件。
• dict.ts：组件类型字典。
• minio.ts：截图文件上传。

当前主要接口：

方法	地址	用途
GET	/dict/getDictByKey	查询一级类型
GET	/dict/getComponentDictByType	查询二级类型
POST	/minio/upload	上传预览截图
POST	/component/save	新增组件
POST	/component/update	编辑组件

保存组件需要后台登录态。请求层会先读取本地持久化的 accessToken；没有 token 时会通过 /auth/refresh 使用 cookie 刷新并持久化登录数据；接口返回 401 时会跳到 VITE_APP_ADMIN_LOGIN，登录成功后回到原页面继续保存流程。

开发约定

• 保持 query 和 hash 分工，不要让 store.serialize() 覆盖 location.search。
• 保存前必须先上传截图，image 字段使用 MinIO 返回的 URL。
• 业务请求新增时统一放到 src/api，组件里调用封装后的函数。
• 编辑器核心逻辑来自 @vue/repl，调整时优先保持原有 Store、Preview、Editor 分层。

轻量验证

常规改动优先执行：

pnpm typecheck

涉及保存或预览交互时再启动开发服务检查明显报错：

pnpm dev