Advanced Designer

Appearance

应用接入 ​

在任意前端或中台项目中，通过 iframe 嵌入已部署的设计器，再通过 postMessage 与设计器进行初始化、保存与关闭等通信，即可完成接入。本文介绍快速接入步骤与进阶用法（回显文档、AI 登录）。

前置条件 ​

快速接入 ​

1. 使用 iframe 嵌入设计器 ​

在业务页面中通过 iframe 加载设计器地址，并通过 postMessage 发送 init 事件完成初始化：

vue
<template>
  <iframe
    ref="iframeRef"
    :src="`https://designer.vvhrdesigner.com/?timestamp=${Date.now()}`"
    class="designer-frame"
    @load="handleIframeLoad"
  />
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'

const iframeRef = ref<HTMLIFrameElement | null>(null)

function handleIframeLoad() {
  setTimeout(() => {
    const doc = {
      createdAt: 0,
      updatedAt: 0,
      schemas: [],
      props: {}
    }
    iframeRef.value?.contentWindow?.postMessage(
      { type: 'init', data: JSON.stringify(doc), excontext: '{}' },
      '*'
    )
  }, 1000)
}
</script>

将 https://designer.vvhrdesigner.com 替换为您的设计器实际地址或直接使用我们的官方地址；timestamp 用于避免缓存。

2. 监听设计器的关闭与保存 ​

设计器为完整全屏页面，自带保存与关闭按钮。建议业务侧使用全屏/弹窗承载 iframe，并隐藏业务窗口的标题栏与关闭按钮，由设计器内部按钮触发关闭或保存后，通过 postMessage 通知业务页面。

业务页面监听 designer-close、designer-save，并在保存时回传 designer-save-success 或 designer-save-failed：

vue
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'

const iframeRef = ref<HTMLIFrameElement | null>(null)
const visible = ref(true)

function handleMessage(event: MessageEvent) {
  const { type, data } = event.data ?? {}
  if (type === 'designer-close') {
    visible.value = false // 关闭您的窗口/弹窗
  }
  if (type === 'designer-save') {
    if (data) {
      // 在此持久化 data，例如调用后端接口
      // 持久化成功后通知设计器
      iframeRef.value?.contentWindow?.postMessage({ type: 'designer-save-success' }, '*')
    } else {
      iframeRef.value?.contentWindow?.postMessage({ type: 'designer-save-failed' }, '*')
    }
  }
}

onMounted(() => {
  window.addEventListener('message', handleMessage)
})
onUnmounted(() => {
  window.removeEventListener('message', handleMessage)
})
</script>

3. 设计器文档结构（DesignDoc） ​

设计器在 导入 / 导出 / 初始化（init）/ 保存（designer-save） 等场景下，均使用同一份文档结构。业务侧初始化、回显或保存时，建议按该结构组织数据：

typescript
interface DesignDoc {
  /** 文档创建时间戳 */
  createdAt: number
  /** 文档更新时间戳 */
  updatedAt: number
  /** 表单组件配置（画布上的组件树） */
  schemas: any[]
  /** 表单自身配置（如布局、校验等） */
  props: any
  /** 环境版本信息（可选） */
  environment?: {
    elementPlus: string
    advancedEleUi: string
    vue: string
    designer: string
  }
}

进阶接入 ​

已有配置回显 ​

若您已有设计好的 JSON 配置或 DesignDoc 对象，希望在设计器中打开即回显，可在 iframe 加载完成后通过 init 传入该文档，并可按需传入扩展上下文 excontext（用于模拟生产环境等）：

js
const docJson = JSON.stringify(designDoc)      // 设计器文档
const excontextJson = JSON.stringify(excontext) // 扩展上下文，可选

iframeRef.value?.contentWindow?.postMessage(
  { type: 'init', data: docJson, excontext: excontextJson },
  '*'
)

接入 AI 助手 ​

若需在设计器内使用 AI 助手，需先获取 应用 ID 与 应用密钥，再通过登录事件传入。登录成功后，设计器内即可使用 AI 助手；否则打开 AI 助手时会提示未授权。

js
const loginData = {
  userId: '业务系统的用户标识',
  appId: 'app_xxx',      // 向设计器提供方获取
  appSecret: 'xxxx'      // 向设计器提供方获取
}

iframeRef.value?.contentWindow?.postMessage(
  { type: 'login', data: JSON.stringify(loginData) },
  '*'
)

通信事件速览 ​

方向事件类型说明
业务 → 设计器init初始化/回显文档，可带 data（DesignDoc JSON）、excontext
业务 → 设计器login传入 AI 助手所需的 userId、appId、appSecret
设计器 → 业务designer-close用户点击设计器内关闭，业务侧关闭窗口/弹窗
设计器 → 业务designer-save用户点击保存，携带 data（DesignDoc）
业务 → 设计器designer-save-success业务侧保存成功后通知设计器
业务 → 设计器designer-save-failed业务侧保存失败时通知设计器