UEditor 1.4.3 使用教程
目录
- 什么是 UEditor？
- 第一步：下载与准备
- 第二步：配置与部署
- 服务器端配置 (PHP)
- 前端页面配置
- 第三步：基本集成与使用
- 第四步：常用功能与配置详解
ueditor.config.js配置项- 初始化编辑器实例
- 第五步：高级功能与自定义
- 自定义工具栏按钮
- 监听编辑器内容变化
- 从服务器获取内容
- 常见问题与解决方案
- 上传图片失败
- 样式不生效
- 总结与最佳实践
什么是 UEditor？
UEditor 是由百度「前端研发部」开发的所见即所得富文本编辑器，具有轻量，功能丰富，可定制等特点，它使用 MIT 协议开源,允许自由使用和修改。
（图片来源网络，侵删）
4.3 版本特点：
- 成熟稳定：1.4.3 是一个非常经典和稳定的版本,社区文档和解决方案非常丰富。
- 跨浏览器：兼容主流浏览器。
- 功能全面：支持图文混排、表格、代码高亮、视频插入等富文本编辑功能。
- 前后端分离：前端负责编辑，后端负责处理上传、图片管理等，通过 API 交互。
第一步：下载与准备
-
下载源码 访问 UEditor 官方 GitHub 仓库：https://github.com/fex-team/ueditor 在 Releases 页面找到
4.3版本，下载其源码包（ueditor1_4_3-utf8-php.zip），这里我们以 PHP 版本为例,因为它是最常见的。 -
解压并放置 将下载的 ZIP 包解压，你会得到一个名为
ueditor1_4_3-utf8-php的文件夹。 将这个文件夹重命名（ueditor），然后放置到你的 Web 项目的根目录下，或者一个方便访问的公共目录中，public/ueditor或assets/ueditor。 -
目录结构 了解目录结构对后续配置至关重要：
（图片来源网络，侵删）ueditor/ // 编辑器根目录 ├── _examples/ // 示例文件 ├── _src/ // 编辑器源码 ├── dialogs/ // 弹出对话框 ├── lang/ // 语言包 ├── themes/ // 样式主题 ├── third-party/ // 第三方库 ├── ueditor.config.js // **核心配置文件** ├── ueditor.all.js // 编辑器核心代码（包含所有模块） ├── ueditor.parse.js // 服务端解析内容用的JS └── php/ // **PHP后端处理目录** ├── action_cors.php // 跨域配置 ├── config.json // **后端核心配置文件** ├── controller.php // 后端入口文件 └── ... // 其他处理上传、图片等的PHP文件
第二步：配置与部署
UEditor 的配置分为前端配置和后端配置两部分。
服务器端配置
后端配置主要是告诉 UEditor 上传的文件存放在哪里,以及允许上传哪些类型的文件。
-
编辑
php/config.json这是后端最核心的配置文件，使用UTF-8编码打开它。{ "imageUrl": "/ueditor/php/upload/image/", // "图片上传保存目录", // 配置图片上传路径 "imagePath": "/ueditor/php/upload/image/", // "图片访问路径", // 配置图片访问路径 // ... 其他配置项 "imageFieldName": "upfile", // "图片上传参数名" "imageMaxSize": 2048000, // "图片大小限制，单位B", "imageAllowFiles": [".png", ".jpg", ".jpeg", ".gif", ".bmp"], // "上传图片格式显示", // ... 等等，还有文件、视频等配置项 }关键配置项解释：
（图片来源网络，侵删）imageUrl: 上传文件的保存目录，这是服务器上的一个物理路径，你需要确保这个目录存在并且有写入权限，如果你的网站根目录是/var/www/html/，那么这里的路径应该是/var/www/html/ueditor/php/upload/image/。imagePath: 上传文件的访问URL，这是通过浏览器访问图片时使用的URL路径，它通常与imageUrl对应，但需要是 Web 服务器可以公开访问的路径。http://your-domain.com/ueditor/php/upload/image/。imageMaxSize: 单位是字节，2048000表示 2MB。imageAllowFiles: 允许上传的图片文件后缀名列表。
重要提示：
- 路径问题：
imageUrl必须是服务器上的绝对路径或相对于网站根目录的路径。imagePath必须是以 开头的 Web 可访问路径。 - 权限问题：确保
ueditor/php/upload/目录及其子目录有写入权限（在 Linux 系统下，权限通常设置为755或775）。
-
检查
php/controller.php这个文件是后端的统一入口，通常不需要修改，它会根据前端请求，调用php/action/目录下的相应 PHP 文件来处理上传、列表等操作。
前端页面配置
前端配置主要是初始化编辑器时,传入一些参数。
-
创建 HTML 页面 在你的 Web 项目中创建一个 HTML 文件，
index.html。 -
引入 JS 和 CSS 文件 在 HTML 文件的
<head>中引入 UEditor 的 CSS 和 JS 文件,路径要正确。<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>UEditor 使用示例</title> <!-- 引入 UEditor 的 CSS 文件 --> <link rel="stylesheet" href="ueditor/themes/default/css/ueditor.min.css"> <!-- 引入 jQuery (UEditor 1.4.3 依赖 jQuery) --> <script src="https://cdn.bootcdn.net/ajax/libs/jquery/1.10.2/jquery.min.js"></script> </head> <body> <!-- 实例化编辑器 --> <script id="editor" type="text/plain" style="width:1024px;height:500px;"></script> <!-- 配置文件 --> <script type="text/javascript" src="ueditor/ueditor.config.js"></script> <!-- 编辑器源码文件 --> <script type="text/javascript" src="ueditor/ueditor.all.js"></script> <!-- 实例化编辑器 --> <script type="text/javascript"> // 1.4.3 版本推荐使用 UE.getEditor 来实例化 var ue = UE.getEditor('editor'); </script> </body> </html>
第三步：基本集成与使用
打开你创建的 index.html 文件，你应该能看到一个功能完整的富文本编辑器了，你可以直接在编辑器里输入文字、设置格式、插入图片等。
获取编辑器内容
这是最常用的操作，通常在表单提交时，需要获取编辑器里的 HTML 内容。
// UE.getEditor 返回的实例对象
var editor = UE.getEditor('editor');
// 监听编辑器“ready”事件，确保编辑器初始化完成
editor.ready(function() {
// 通过 getContent() 方法获取编辑器中的内容
function getContent() {
var content = editor.getContent();
console.log('获取到的编辑器内容是：', content);
// 这里可以将 content 发送到服务器
// $.post('/save-content', {content: content}, function(response){ ... });
}
// 假设有一个按钮来触发获取内容
// <button onclick="getContent()">获取内容</button>
});
第四步：常用功能与配置详解
ueditor.config.js 配置项
这个文件是前端的核心配置，默认配置项已经很全面,你可以根据需要进行修改。
// ueditor.config.js
window.UEDITOR_CONFIG = {
// 为编辑器实例添加一个路径，这个路径会被用到编辑器初始化的样式中
UEDITOR_HOME_URL: URL + 'ueditor/', // URL 即为你当前页面的路径，通常会自动计算
// 编辑器不自动被内容撑高
autoHeightEnabled: false,
// 初始高度
initialFrameHeight: 500,
// 初始宽度
initialFrameWidth: 1024,
// 关闭自动保存
enableAutoSave: false,
// 工具栏上的所有的功能按钮和下拉框，可以在new编辑器实例时选择自己需要的从新定义
, toolbars: [
['fullscreen', 'source', '|', 'undo', 'redo', '|',
'bold', 'italic', 'underline', 'fontborder', 'strikethrough', 'superscript', 'subscript', 'removeformat', 'formatmatch', 'autotypeset', 'blockquote', 'pasteplain', '|', 'forecolor', 'backcolor', 'insertorderedlist', 'insertunorderedlist', 'selectall', 'cleardoc', '|',
'rowspacingtop', 'rowspacingbottom', 'lineheight', '|',
'customstyle', 'paragraph', 'fontfamily', 'fontsize', '|',
'directionalityltr', 'directionalityrtl', 'indent', '|',
'justifyleft', 'justifycenter', 'justifyright', 'justifyjustify', '|',
'touppercase', 'tolowercase', '|',
'link', 'unlink', 'anchor', '|',
'imagenone', 'imageleft', 'imagecenter', 'imageright', 'imagefloatnone', '|',
'insertimage', 'emotion', 'scrawl', 'insertvideo', 'music', 'attachment', 'map', 'gmap', 'insertframe', 'insertcode', 'webapp', 'pagebreak', 'template', 'background', '|',
'horizontal', 'date', 'time', 'spechars', 'snapscreen', 'wordimage', '|',
'inserttable', 'deletetable', 'insertparagraphbeforetable', 'insertrow', 'deleterow', 'insertcol', 'deletecol', 'mergecells', 'mergeright', 'mergedown', 'splittocells', 'splittorows', 'splittocols', 'charts', '|',
'print', 'preview', 'searchreplace', 'help', 'drafts']
]
};
常用配置项：
UEDITOR_HOME_URL: 非常重要，必须指向 UEditor 文件夹的 URL 路径，如果页面和 UEditor 在同一级,通常默认即可。initialFrameHeight/initialFrameWidth: 设置编辑器的初始宽高。toolbars: 自定义工具栏，你可以通过增减数组中的元素来显示或隐藏按钮，如果你想简化工具栏：toolbars: [ ['source', 'undo', 'redo', '|', 'bold', 'italic', 'underline', 'fontfamily', 'fontsize', '|', 'justifyleft', 'justifycenter', 'justifyright', '|', 'insertimage', 'inserttable', 'link'] ]
初始化编辑器实例
UE.getEditor() 是官方推荐的实例化方法。
// 参数1: 容器的 id 或 name
// 参数2: 可选的配置对象，会覆盖 ueditor.config.js 中的配置
var editor = UE.getEditor('editor', {
initialContent: '欢迎使用 UEditor！', // 初始化内容
autoHeightEnabled: true, // 自动高度
toolbars: [['bold', 'italic']] // 只显示这两个按钮
});
// 使用回调函数
UE.getEditor('editor', {
onready: function () {
this.setContent('编辑器已经准备就绪，这是动态设置的内容。');
}
});
第五步：高级功能与自定义
自定义工具栏按钮
如果你想在工具栏上添加一个自定义按钮（插入一个特定的 HTML 片段）,可以这样做：
-
修改
toolbars配置，添加你的按钮名，mybutton。// 在 ueditor.config.js 中 window.UEDITOR_CONFIG.toolbars = [['mybutton', 'bold', 'italic']];
-
注册命令，在页面中，在实例化编辑器之前,注册你的按钮对应的命令。
<script type="text/javascript"> // 1. 注册命令 UE.commands['mybutton'] = { execCommand: function (cmd, name, opts) { // 当点击按钮时，这里面的代码会被执行 var html = '<div style="background-color: yellow; padding: 10px;">这是一个自定义插入的内容！</div>'; // 获取当前选区 var range = editor.selection.getRange(); // 插入 HTML range.insertNode(range.createContextualFragment(html)); } }; // 2. 实例化编辑器 var editor = UE.getEditor('editor'); </script>
监听编辑器内容变化
变化可以实现实时保存等功能。
var editor = UE.getEditor('editor');
editor.addListener('contentChange', function () {
console.log('编辑器内容已发生变化！');
var content = editor.getContent();
// 可以在这里执行 AJAX 请求，实现自动保存
// saveContent(content);
});
从服务器获取内容
编辑器初始化后,可以从服务器加载内容并显示。
var editor = UE.getEditor('editor');
editor.ready(function () {
// 模拟从服务器获取数据
$.ajax({
url: '/get-content-from-server',
type: 'GET',
success: function (data) {
// 使用 setContent 方法设置内容
// 'html' 表示传入的是 HTML 字符串
editor.setContent(data.content, 'html');
},
error: function () {
console.error('获取内容失败');
}
});
});
常见问题与解决方案
上传图片失败
这是最常见的问题,通常由以下几个原因导致：
- 路径错误：检查
php/config.json中的imageUrl和imagePath。imageUrl必须是服务器上存在的、有写权限的物理路径。 - 权限问题：确保
ueditor/php/upload/目录有 Web 服务器进程（如www-data,apache,nginx）的写入权限。- Linux/Mac:
chmod -R 755 /path/to/your/upload/dir - Windows: 右键文件夹 -> 属性 -> 安全 -> 编辑权限。
- Linux/Mac:
- 跨域问题：如果你的前端页面和 UEditor 后端不在同一个域下，可能会遇到跨域问题。
- 解决方案：编辑
php/action_cors.php文件,取消注释并根据你的域名进行配置。
- 解决方案：编辑
- PHP 配置问题：检查
php.ini文件中的以下配置项，确保上传的文件大小和类型被允许。file_uploads = Onupload_max_filesize = 32M(根据需要调整)post_max_size = 32M(通常需要大于或等于 upload_max_filesize)
- 网络请求被拦截：检查浏览器控制台（F12）的 Network 面板，查看上传请求是否发出，以及服务器返回了什么错误信息（通常是 500 或 404 错误）。
样式不生效
- CSS 路径错误：确保在 HTML 中正确引入了
ueditor/themes/default/css/ueditor.min.css。 - 自定义样式冲突：检查你的页面 CSS 是否意外覆盖了 UEditor 的样式，可以使用浏览器开发者工具（F12）检查元素的样式来源。
- 编辑器渲染问题：有时编辑器内容需要重新渲染，可以调用
editor.render()方法。
总结与最佳实践
- 版本选择：1.4.3 是一个稳定的选择，但如果你的项目是新开发的，可以考虑更新版本的 UEditor 或其他现代化的编辑器（如 TinyMCE, CKEditor 5, Quill.js）。
- 安全第一：从编辑器获取的内容是用户输入，绝对不能直接存入数据库并原样输出到页面，否则极易遭受 XSS（跨站脚本）攻击，必须对内容进行转义或过滤处理,大多数后端框架都提供了相应的安全函数。
- 前后端分离：UEditor 1.4.3 的后端是 PHP，如果你的后端是 Java, Node.js, Python 等，你需要使用 UEditor 官方提供的后端版本，或者自己根据其 API 规范来实现，后端的核心逻辑都是一样的：接收文件、验证、保存、返回 URL。
- 性能考虑：
ueditor.all.js文件较大，包含了所有功能，如果你的编辑器不需要某些功能（如代码高亮、图表等），可以考虑使用ueditor.custom.js来定制一个更小的版本。 - 调试技巧：遇到问题时，善用浏览器开发者工具的 Console 和 Network 面板，Console 可以显示 JS 错误，Network 可以显示与后端交互的请求和响应,这是定位问题的关键。
希望这份详细的教程能帮助你顺利地在项目中使用 UEditor 1.4.3！
