事件系统

UEditor Plus Designer 提供了完整的事件系统，用于监听编辑器状态变化。

事件列表

ready

编辑器初始化完成时触发。

• 参数: 无
• 触发时机: 编辑器和 UEditor 完全加载并准备就绪

// Vue
<UEditorPlusDesigner @ready="handleReady" />

// React
<UEditorPlusDesigner onReady={handleReady} />

// JavaScript
designer.on('ready', function() {
  console.log('Editor is ready')
})

change

编辑器内容发生变化时触发。

• 参数: content: string - 当前内容
• 触发时机: 用户编辑内容、插入素材等操作后

// Vue
<UEditorPlusDesigner @change="handleChange" />

const handleChange = (content: string) => {
  console.log('Content:', content)
}

// React
<UEditorPlusDesigner onChange={handleChange} />

const handleChange = (content: string) => {
  console.log('Content:', content)
}

// JavaScript
designer.on('change', function(content) {
  console.log('Content:', content)
})

confirm

确认操作时触发（仅 iframe 模式）。

• 参数: content: string - 当前内容
• 触发时机: 用户点击确认按钮

// Vue
<UEditorPlusDesigner 
  :isIframe="true"
  @confirm="handleConfirm"
/>

// React
<UEditorPlusDesigner 
  isIframe={true}
  onConfirm={handleConfirm}
/>

// JavaScript
designer.on('confirm', function(content) {
  console.log('Confirmed:', content)
})

监听事件

Vue 3

使用 @ 语法监听事件：

<template>
  <UEditorPlusDesigner
    @ready="handleReady"
    @change="handleChange"
    @confirm="handleConfirm"
  />
</template>

<script setup>
const handleReady = () => {
  console.log('Ready')
}

const handleChange = (content) => {
  console.log('Changed:', content)
}

const handleConfirm = (content) => {
  console.log('Confirmed:', content)
}
</script>

React

使用 on 前缀的 props：

function App() {
  const handleReady = () => {
    console.log('Ready')
  }

  const handleChange = (content: string) => {
    console.log('Changed:', content)
  }

  const handleConfirm = (content: string) => {
    console.log('Confirmed:', content)
  }

  return (
    <UEditorPlusDesigner
      onReady={handleReady}
      onChange={handleChange}
      onConfirm={handleConfirm}
    />
  )
}

原生 JavaScript

使用 on() 方法：

designer.on('ready', function() {
  console.log('Ready')
})

designer.on('change', function(content) {
  console.log('Changed:', content)
})

designer.on('confirm', function(content) {
  console.log('Confirmed:', content)
})

移除监听

移除特定处理函数

const handler = (content) => {
  console.log(content)
}

// 添加监听
designer.on('change', handler)

// 移除监听
designer.off('change', handler)

移除所有处理函数

// 移除 change 事件的所有处理函数
designer.off('change')

使用示例

自动保存

let saveTimer: number | undefined

const handleChange = (content: string) => {
  // 防抖保存
  clearTimeout(saveTimer)
  saveTimer = setTimeout(() => {
    localStorage.setItem('content', content)
    console.log('自动保存成功')
  }, 1000)
}

内容验证

const handleChange = (content: string) => {
  // 检查内容长度
  if (content.length > 100000) {
    alert('内容过长，请精简')
  }
  
  // 检查是否包含必要元素
  if (!content.includes('pb-section')) {
    console.warn('内容中没有 Section')
  }
}

状态同步

// Vue + Pinia
import { useEditorStore } from '@/stores/editor'

const editorStore = useEditorStore()

const handleChange = (content: string) => {
  editorStore.updateContent(content)
}

// React + Redux
import { useDispatch } from 'react-redux'
import { updateContent } from './store/editorSlice'

const dispatch = useDispatch()

const handleChange = (content: string) => {
  dispatch(updateContent(content))
}

离开提示

let hasUnsavedChanges = false

const handleChange = (content: string) => {
  hasUnsavedChanges = true
}

// 监听页面关闭
window.addEventListener('beforeunload', (e) => {
  if (hasUnsavedChanges) {
    e.preventDefault()
    e.returnValue = ''
  }
})

// 保存后重置标志
const handleSave = () => {
  // 保存逻辑...
  hasUnsavedChanges = false
}

最佳实践

1. 防抖处理

对于频繁触发的 change 事件，使用防抖：

import { debounce } from 'lodash-es'

const debouncedChange = debounce((content: string) => {
  // 处理内容变化
  console.log('Content changed:', content)
}, 300)

const handleChange = (content: string) => {
  debouncedChange(content)
}

2. 清理监听器

组件卸载时清理事件监听：

// Vue
import { onUnmounted } from 'vue'

onUnmounted(() => {
  designerRef.value?.off('change')
  designerRef.value?.off('ready')
})

// React
useEffect(() => {
  return () => {
    designerRef.current?.off('change')
    designerRef.current?.off('ready')
  }
}, [])

3. 错误处理

在事件处理函数中捕获错误：

const handleChange = (content: string) => {
  try {
    // 处理逻辑
    const parsed = JSON.parse(content)
  } catch (error) {
    console.error('处理内容时出错:', error)
  }
}

4. 条件监听

根据条件决定是否处理事件：

let isProcessing = false

const handleChange = (content: string) => {
  if (isProcessing) {
    return // 跳过处理
  }
  
  isProcessing = true
  
  try {
    // 处理内容
  } finally {
    isProcessing = false
  }
}

事件流程

用户操作
  ↓
UEditor 内部事件
  ↓
Designer 捕获
  ↓
触发 change 事件
  ↓
调用注册的回调函数

相关链接

• DesignerConfig
• 实例方法
• Vue 使用指南
• React 使用指南