UEditor Plus Designer

主题

安装 ​

本章节详细介绍如何在不同项目类型中安装 UEditor Plus Designer。

NPM 安装 ​

对于 Vue 3 和 React 项目，推荐使用 npm、yarn 或 pnpm 安装：

bash
npm install ueditor-plus-designer
bash
yarn add ueditor-plus-designer
bash
pnpm add ueditor-plus-designer

Vue 3 项目 ​

1. 安装依赖 ​

bash
npm install ueditor-plus-designer

2. 在组件中引入 ​

vue
<script setup>
import { UEditorPlusDesigner } from 'ueditor-plus-designer'
import 'ueditor-plus-designer/style'
</script>

3. 全局注册（可选） ​

如果需要在多个组件中使用，可以全局注册：

javascript
// main.js
import { createApp } from 'vue'
import App from './App.vue'
import { UEditorPlusDesigner } from 'ueditor-plus-designer'
import 'ueditor-plus-designer/style'

const app = createApp(App)

// 全局注册组件
app.component('UEditorPlusDesigner', UEditorPlusDesigner)

app.mount('#app')

然后在任何组件中直接使用：

vue
<template>
  <UEditorPlusDesigner :config="config" />
</template>

React 项目 ​

React 项目需要额外的设置步骤，因为 UEditor Plus Designer 是基于 Vue 3 构建的。我们使用 Veaury 来桥接 Vue 和 React。

1. 安装依赖 ​

bash
npm install ueditor-plus-designer vue veaury

注意：需要同时安装 vue 和 veaury。

2. 配置 Vite ​

如果使用 Vite，需要同时添加 React 和 Vue 插件：

typescript
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    react(),
    vue()
  ]
})

3. 创建包装组件 ​

创建一个 React 包装组件：

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

export const UEditorPlusDesigner = applyVueInReact(VueDesigner.UEditorPlusDesigner)

4. 在 React 组件中使用 ​

tsx
import React from 'react'
import { UEditorPlusDesigner } from './UEditorPlusDesigner'
import 'ueditor-plus-designer/style'

function App() {
  const config = {
    ueditorPath: '/ueditor-plus'
  }

  return <UEditorPlusDesigner config={config} />
}

详细的 React 集成指南请参考 React 使用指南。

原生 HTML ​

对于原生 HTML 项目，使用独立构建版本：

1. 下载文件 ​

从 GitHub Releases 下载：

  • ueditor-plus-designer.standalone.js
  • ueditor-plus-designer.standalone.css

或者从项目构建：

bash
npm run build:standalone

文件将生成在 dist/standalone/ 目录。

2. 在 HTML 中引入 ​

html
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>UEditor Plus Designer</title>
    
    <!-- 引入样式 -->
    <link rel="stylesheet" href="path/to/ueditor-plus-designer.standalone.css">
</head>
<body>
    <!-- 容器 -->
    <div id="designer-container"></div>

    <!-- 引入脚本 -->
    <script src="path/to/ueditor-plus-designer.standalone.js"></script>
    
    <!-- 初始化 -->
    <script>
        const designer = UEditorPlusDesigner.createDesigner({
            ueditorPath: '/ueditor-plus'
        });
        
        designer.mount('#designer-container');
    </script>
</body>
</html>

详细的 HTML 集成指南请参考 HTML 使用指南。

准备 UEditor Plus ​

无论使用哪种安装方式，都需要准备 UEditor Plus 编辑器文件。

开发环境：使用 CDN 代理 ​

适合快速开发和测试：

javascript
// vite.config.js / vite.config.ts
export default {
  server: {
    proxy: {
      '/ueditor-plus': {
        target: 'https://unpkg.com/ueditor-plus-main@2.0.0/dist-min/',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/ueditor-plus/, ''),
      }
    }
  }
}

生产环境：本地部署 ​

推荐在生产环境中本地部署 UEditor Plus 文件：

步骤 1: 下载 UEditor Plus ​

从 UEditor Plus GitHub 下载最新版本。

步骤 2: 放置文件 ​

将解压后的文件放置到项目的 public/ueditor-plus/ 目录：

public/
└── ueditor-plus/
    ├── ueditor.config.js
    ├── ueditor.all.js
    ├── ueditor.all.min.js
    ├── themes/
    ├── lang/
    ├── dialogs/
    └── ... 其他文件

步骤 3: 配置路径 ​

在组件配置中指定路径：

javascript
const config = {
  ueditorPath: '/ueditor-plus'  // 对应 public/ueditor-plus/
}

TypeScript 支持 ​

UEditor Plus Designer 完全使用 TypeScript 编写，提供完整的类型定义。

自动类型推导 ​

安装后，TypeScript 会自动识别类型：

typescript
import { UEditorPlusDesigner } from 'ueditor-plus-designer'
import type { DesignerConfig, MaterialItem } from 'ueditor-plus-designer'

const config: DesignerConfig = {
  ueditorPath: '/ueditor-plus',
  categoryLoader: async () => {
    // TypeScript 会自动推导返回类型
    return []
  }
}

类型导入 ​

可以导入各种类型定义：

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

版本兼容性 ​

UEditor Plus DesignerVueReactUEditor PlusNode.js
0.1.x^3.4.0^18.0.0^2.0.0^20.0.0

CDN 引入 ​

也可以通过 CDN 直接引入（不推荐用于生产）：

html
<!-- 开发版本 -->
<script src="https://unpkg.com/ueditor-plus-designer@latest/dist/vue/vue.umd.js"></script>
<link rel="stylesheet" href="https://unpkg.com/ueditor-plus-designer@latest/dist/vue/vue-style.css">

<!-- 生产版本（推荐） -->
<script src="https://unpkg.com/ueditor-plus-designer@latest/dist/standalone/ueditor-plus-designer.standalone.js"></script>
<link rel="stylesheet" href="https://unpkg.com/ueditor-plus-designer@latest/dist/standalone/ueditor-plus-designer.standalone.css">

验证安装 ​

安装完成后，可以运行一个简单的测试来验证：

vue
<template>
  <div style="width: 100vw; height: 100vh;">
    <UEditorPlusDesigner
      :config="config"
      @ready="onReady"
    />
  </div>
</template>

<script setup>
import { UEditorPlusDesigner } from 'ueditor-plus-designer'
import 'ueditor-plus-designer/style'

const config = {
  ueditorPath: '/ueditor-plus'
}

const onReady = () => {
  console.log('✅ UEditor Plus Designer 安装成功！')
}
</script>

如果浏览器控制台输出 "✅ UEditor Plus Designer 安装成功！"，说明安装正确。

故障排除 ​

模块未找到 ​

如果出现 Cannot find module 'ueditor-plus-designer' 错误：

  1. 确认已正确安装依赖：npm install ueditor-plus-designer
  2. 删除 node_modules 和锁文件，重新安装
  3. 检查 package.json 中是否有该依赖

类型错误 ​

如果 TypeScript 报类型错误：

  1. 确认 TypeScript 版本 >= 5.0
  2. 检查 tsconfig.json 配置
  3. 重启 IDE/编辑器

UEditor 加载失败 ​

如果 UEditor 无法加载：

  1. 检查 ueditorPath 配置是否正确
  2. 确认 UEditor Plus 文件已正确放置
  3. 检查浏览器控制台的网络请求
  4. 验证文件路径是否可访问（如 http://localhost:3000/ueditor-plus/ueditor.config.js）

Released under the Apache License 2.0. 压缩版免费使用，商用或源码需授权。

Copyright © 2026-present