跳到主要内容

实时预览

Schema Element Editor 提供实时预览功能，让您在编辑 Schema 时能够立即看到效果。

功能概述​

预览功能支持两种模式：

模式说明
宿主预览由宿主页面提供的自定义预览组件
内置预览插件内置的 Markdown 预览器（fallback）

使用方法​

打开预览​

  1. 在编辑器工具栏点击「预览」按钮
  2. 或使用快捷键 Alt + P

预览开启后：

  • 抽屉宽度会扩展到全屏
  • 左侧显示预览区域
  • 右侧显示编辑器

关闭预览​

  • 再次点击「预览」按钮
  • 或使用快捷键 Shift + Alt + P

调整布局​

预览和编辑器之间有一个可拖拽的分隔条：

  1. 将鼠标移到分隔条上（光标变为调整样式）
  2. 按住并拖动可调整左右比例
  3. 最小宽度为 20%

预览更新​

手动更新​

默认情况下，预览需要手动更新：

  • 点击预览区域的「刷新」按钮
  • 或使用快捷键 Alt + P

自动更新​

启用自动更新后，编辑器内容变化时预览会自动刷新（带防抖）。

在配置页面「实时预览」→「预览行为」中开启「自动更新预览」。

更新防抖​

为避免频繁渲染，预览更新有防抖延迟：

  • 默认延迟：500ms
  • 可配置范围：100ms - 2000ms

在「更新防抖」配置项中调整。

内置预览器​

当宿主页面未提供预览函数时，插件会使用内置的 Markdown 预览器。

支持的内容类型​

类型支持说明
AST (Elements[])✅渲染为格式化的结构视图
RawString (Markdown)✅渲染为 Markdown 预览
JSON (Object)❌不支持，请使用宿主预览

启用/禁用​

在配置页面「实时预览」→「预览行为」→「启用内置预览器」中设置。

默认开启。

宿主预览​

如果您需要自定义的预览效果，宿主页面可以提供预览函数。

实现方式​

postMessage 模式（推荐）：

import { useSchemaElementEditor } from '@schema-element-editor/host-sdk'

useSchemaElementEditor({
  getSchema: (params) => dataStore[params],
  updateSchema: (schema, params) => { /* ... */ },
  // 提供预览函数
  renderPreview: (schema, containerId) => {
    const container = document.getElementById(containerId)
    const root = ReactDOM.createRoot(container)
    root.render(<YourPreviewComponent data={schema} />)
    // 返回清理函数
    return () => root.unmount()
  },
})

详细说明请参阅 SDK 使用指南。

配置选项​

预览行为​

配置项说明默认值
启用内置预览器当宿主未提供预览函数时使用内置预览开启
自动更新预览内容变化时自动更新预览关闭
更新防抖编辑后多久更新预览500ms
预览区域宽度预览区域占抽屉的百分比40%

层级配置​

配置项说明默认值
默认 z-index非预览模式下的层级2147483646
预览模式 z-index预览容器的层级999

预览按钮显示​

如果不需要预览功能，可以隐藏预览按钮：

  1. 打开配置页面
  2. 找到「功能开关」→「工具栏按钮」
  3. 关闭「预览」开关

故障排除​

预览按钮灰色/禁用​

可能的原因：

  1. 宿主页面未提供预览函数
  2. 内置预览器已禁用
  3. 当前内容类型不支持预览（JSON 对象）

解决方案：

  • 添加预览函数
  • 在配置中启用内置预览器
  • 确认数据类型是 AST 或 RawString

预览显示空白​

可能的原因：

  1. 预览函数执行出错
  2. 容器 ID 获取失败

解决方案：

  • 检查浏览器控制台是否有错误
  • 确认预览函数正确获取容器

预览更新延迟​

如果预览更新太慢：

  1. 减小「更新防抖」时间
  2. 开启「自动更新预览」

如果预览更新太频繁导致卡顿：

  1. 增大「更新防抖」时间
  2. 关闭「自动更新预览」，改为手动刷新

预览样式异常​

预览容器是在宿主页面的 DOM 中创建的，可以正常使用宿主页面的样式。

如果预览样式显示异常，可能的原因：

  1. 预览组件缺少必要的样式依赖
  2. CSS 选择器优先级问题
  3. 预览组件使用了相对路径的资源

解决方案：

  • 确保预览组件引入了所需的样式文件
  • 在预览函数中显式导入样式或使用内联样式
  • 检查预览组件是否有 CSS-in-JS 等样式方案