常见问题 (FAQ)

安装和配置

Q: 如何选择合适的版本？

A: 根据您的项目类型选择：

• Vue 3 项目: 直接安装 npm 包
• React 项目: 安装 npm 包 + Veaury 桥接
• 原生 HTML: 使用独立构建版本

Q: UEditor Plus 文件放在哪里？

A:

• 开发环境: 可以使用 CDN 代理
• 生产环境: 建议放在 public/ueditor-plus/ 目录

// Vite 开发环境代理配置
server: {
  proxy: {
    '/ueditor-plus': {
      target: 'https://unpkg.com/ueditor-plus-main@2.0.0/dist-min/',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/ueditor-plus/, '')
    }
  }
}

Q: 如何配置 TypeScript？

A: 确保 tsconfig.json 包含以下配置：

{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

类型定义会自动从包中导入。

使用问题

Q: 编辑器不显示或加载失败？

A: 检查以下几点：

1. UEditor 路径配置是否正确

   const config = {
     ueditorPath: '/ueditor-plus' // 确保路径正确
   }

2. UEditor 文件是否可访问

   • 打开浏览器控制台查看网络请求
   • 访问 http://localhost:3000/ueditor-plus/ueditor.config.js 确认可访问

3. 容器是否有明确高度

   .container {
     height: 100vh; /* 必须有明确的高度 */
   }

4. 是否正确导入样式

   import 'ueditor-plus-designer/style'

Q: 如何获取和设置内容？

A: 使用实例方法：

// Vue
const designerRef = ref(null)

const getContent = () => {
  const content = designerRef.value?.getContent()
  console.log(content)
}

const setContent = () => {
  designerRef.value?.setContent('<div>content</div>')
}

注意

确保在 @ready 事件触发后再调用方法。

Q: 如何监听内容变化？

A: 使用 @change 事件：

<UEditorPlusDesigner
  @change="handleChange"
/>

<script setup>
const handleChange = (content) => {
  console.log('Content:', content)
  // 自动保存等操作
}
</script>

Q: 如何自定义素材？

A: 实现自定义加载器：

const config = {
  categoryLoader: async () => {
    const res = await fetch('/api/categories')
    return res.json()
  },
  
  styleLoader: async (params) => {
    const res = await fetch('/api/materials', {
      method: 'POST',
      body: JSON.stringify(params)
    })
    return res.json()
  }
}

详见 自定义加载器。

React 特定问题

Q: React 项目如何使用？

A: 需要使用 Veaury 桥接：

npm install ueditor-plus-designer vue veaury

创建包装组件：

// src/components/UEditorPlusDesigner.tsx
import { applyVueInReact } from 'veaury'
import VueDesigner from 'ueditor-plus-designer'

export const UEditorPlusDesigner = applyVueInReact(
  VueDesigner.UEditorPlusDesigner
)

详见 React 使用指南。

Q: React 中如何访问实例方法？

A: 通过 ref 访问，确保在 onReady 后调用：

const designerRef = useRef(null)

const handleReady = () => {
  // 现在可以安全地访问方法
  if (designerRef.current) {
    const content = designerRef.current.getContent()
  }
}

<UEditorPlusDesigner
  ref={designerRef}
  onReady={handleReady}
/>

Q: React 项目 Bundle 太大？

A: 由于需要同时包含 Vue 和 React 运行时，会增加约 100KB（gzip 后约 40KB）。

优化方案：

1. 使用代码分割按需加载
2. 将 Vue 通过 CDN 引入
3. 考虑完全用 React 重写（需要更多开发时间）

样式问题

Q: 如何自定义样式？

A: 覆盖 CSS 类：

<style>
/* 修改素材面板背景 */
.material-panel {
  background: #f9f9f9 !important;
}

/* 修改激活状态边框 */
.pb-section-active {
  outline: 2px solid #42b983 !important;
}

/* 修改工具栏样式 */
.section-tools {
  background: rgba(0, 0, 0, 0.8) !important;
}
</style>

详见 样式定制。

Q: 编辑器高度不正确？

A: 确保父容器有明确的高度：

/* ❌ 错误 - 没有高度 */
.container {
  width: 100%;
}

/* ✅ 正确 - 明确的高度 */
.container {
  width: 100%;
  height: 100vh;
}

或者使用 flex 布局：

.page {
  display: flex;
  flex-direction: column;
  height: 100vh;
}

.editor-container {
  flex: 1; /* 占据剩余空间 */
}

性能问题

Q: 如何优化性能？

A:

1. 防抖保存: 避免频繁的保存操作

   const debouncedSave = debounce((content) => {
     saveContent(content)
   }, 1000)

2. 按需加载: 使用代码分割

   const UEditorPlusDesigner = lazy(() => 
     import('ueditor-plus-designer')
   )

3. 虚拟滚动: 对于大量素材列表

Q: 内容变化事件触发太频繁？

A: 使用防抖处理：

import { debounce } from 'lodash-es'

const debouncedChange = debounce((content) => {
  // 处理内容
}, 300)

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

部署问题

Q: 生产环境 UEditor 加载失败？

A:

1. 确保 UEditor 文件已部署到服务器
2. 检查路径配置是否正确
3. 确认静态文件服务配置正确

// 使用环境变量
const config = {
  ueditorPath: import.meta.env.PROD 
    ? 'https://cdn.example.com/ueditor-plus'
    : '/ueditor-plus'
}

Q: 打包后样式丢失？

A: 确保构建配置包含 CSS：

// vite.config.js
export default {
  build: {
    cssCodeSplit: false, // 或 true，根据需要
    rollupOptions: {
      output: {
        assetFileNames: 'assets/[name].[hash][extname]'
      }
    }
  }
}

类型问题

Q: TypeScript 报类型错误？

A:

1. 确保使用 import type 导入类型

   import type { DesignerConfig } from 'ueditor-plus-designer'

2. 检查 TypeScript 版本 (推荐 5.0+)

   npm list typescript

3. 重启 IDE/编辑器

Q: 如何导入所有类型？

A:

import type {
  DesignerConfig,
  DesignerInstance,
  MaterialCategory,
  MaterialItem,
  MaterialQueryParams,
  StyleListData,
  SectionData
} from 'ueditor-plus-designer'

浏览器兼容性

Q: 支持哪些浏览器？

A: 支持现代浏览器：

• ✅ Chrome 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Edge 90+
• ❌ 不支持 IE 11

Q: 如何支持旧浏览器？

A: 需要添加 polyfills，但不推荐。建议提示用户升级浏览器。

获取帮助

如果您的问题未在此列出：

1. 查看 完整文档
2. 搜索 GitHub Issues
3. 在 GitHub Discussions 提问
4. 创建新的 Issue

相关链接

• 快速开始
• 安装指南
• API 参考
• 贡献指南