针对普通的网站使用者
1.1完整版的部署和体验
1) 官网上下载完整源码包,解压到任意目录,解压后的源码目录结构如下所示:
- _examples:编辑器完整版的示例页面
- _demos:编辑器的各种使用案例
- dialogs:弹出对话框对应的资源和JS文件
- themes:样式图片和样式文件
- server:涉及到服务器端操作的PHP、JSP等文件
- third-party:第三方插件
- editor_all.js:_src目录下所有文件的打包文件
- editor_all_min.js:editor_all.js文件的压缩版,建议在正式部署时才采用
- editor_config.js:编辑器的配置文件,建议和编辑器实例化页面置于同一目录
2) 部署UEditor到实际项目(UETest)中的步骤:
-
第一步:在项目的任一文件夹中建立一个用于存放UEditor相关资源和文件的目录,此处在项目根目录下建立,起名为ueditor。
- 第二步:拷贝源码包中的dialogs、themes、third-party、editor_all.js和editor_config.js到ueditor文夹中。理论上,前端的所有文件除了编辑器实例化页面外此刻已经全部具备,此处为了体验图片上传等功能,将server文件夹一并拷贝到ueditor目录中。整体的项目结构如右图所示。其中,除了ueditor目录之外的其余文件均为具体项目文件,此处所列仅供示例。
- 第三步:为简单起见,此处将以根目录下的index.php页面作为编辑器的实例化页面,用来展示UEditor的完整版效果。在index.php文件中,首先导入编辑器需要的三个入口文件,示例代码如下: 需要注意的是,此处的editor_config.js最好先于editor_all.js加载,否则特定情况下可能会出现报错。
- 第四步:创建编辑器实例及其DOM容器。具体代码示例如下: 若希望给编辑器赋初值,此处的div可换成<script type="text/plain" id="myEditor">初始内容</script>来设置初始内容,编辑器自动完成两者之间的转换,完全不会影响最后的显示效果。
- 第五步:到此为止,编辑器所需的所有资源文件、代码、实例化操作、显示容器等等都已经准备完成。
还剩下最后一个操作——配置编辑器资源路径,也就是让编辑器中的代码能够正确找到对应的dialog、css、表情等资源文件。这里需要配置的是ueditor目录在当前网站中的相对路径。在正式开始配置之前首先需要弄明白一个关于相对路径的知识点:如果文件1被文件2导入,那么当在文件1中去获取其他文件的路径时,需要以文件2所处的相对路径作为当前路径,而并非是文件1自身所在的路径。
对应到当前的项目实例,editor_config.js被index.php导入,那么此时的editor_config.js实际上处于与index.php同级的目录结构中。于是,在editor_config.js中所配置的所有相对路径都需要以index.php所在的目录(此处是根目录)为基准。清楚了这点,ueditor目录的相对路径就一目了然了! 这就是我们最后需要配置的结果。从1.1.7.3版本开始,建议在此处配置的路径从相对于服务器根目录开始配置,形如"/mySite/ueditor/",或者采用源码包中editor_config.js中提供的配置方法,以达到最简的部署步骤。至此,一个完整的编辑器实例就已经部署到咱们的项目中了!在浏览器中输入http://localhost/UETest运行下试试UE强大的功能吧!
3) 注意事项
1.2自定义配置
1) 界面配置
- 工具栏配置
默认配置项中包含了编辑器的所有按钮,需要改变时,只要在初始化的时候传入对应参数即可。示例代码如下: 这个时候的编辑就只有四个工具按钮了。关于工具栏的更多高级配置,比如改变布局结构,双栏和单栏混排等等,下文还有专题章节进行完整地介绍,点此马上参观 。 - 初始化内容
上文曾经讲过,实例化的时候可以使用<textarea id="editor">初始内容</textarea>来为编辑器赋初始值。以PHP为例的话,可以将“初始内容”替换成<?=$content?>来动态从服务器去获取。当有些地方不适合使用textarea作为编辑器容器时,比如上文采用div作为容器时,那如何来初始化内容呢?很简单,一句话而已: - 初始化样式
由于编辑器的编辑框位于一个单独的iframe中,因此希望通过在编辑器实例化页面设置编辑框中的元素样式是行不通的。UEditor为大家提供了两种方式来改变编辑框中的元素样式:一种是通过修改initialStyle的内容来实现,另外一种是通过iframeCssUrl引用外部的CSS文件来实现。具体的代码例子如下: 需要注意的是,如果同时配置了这两个参数,那么initialStyle中的配置将优先于iframeCssUrl指向的CSS文件中的配置。另外,由于编辑器中的有些功能效果实现需要依赖于initialStyle中的默认配置,比如框选表格的蓝色背景效果,因此,一般情况下不建议用户删除默认配置项中的默认样式类,除非已经确认不需要对应的功能。 - ElementPath
编辑框下部的path部分。不需要的同学设置elementPathEnabled : false即可。 - 字数统计
编辑框下部的字数统计部分。不需要的同学设置wordCount:false 即可。当设置开启时,还可以通过maximumWords参数来控制允许的最大字符数、wordCountMsg参数来控制需要显示的提示文字、wordOverFlowMsg参数来控制超出最大字数限制时候的提示文字。 - 编辑器最小高度和自动长高
编辑器的最小高度由配置项minFrameHeight来确定,而autoHeightEnabled:true则让编辑器的编辑框部分可以随着编辑内容的增加而自动长高。 - 工具栏浮动
工具栏浮动是指当编辑框的顶部超出了浏览器顶部的时候,工具栏会一直浮动在浏览器的顶部,方便大家的编辑操作。在编辑框高度固定的编辑器实例页面中,建议关闭此项功能以获得最好的性能和体验:autoFloatEnabled: false
2) 功能配置
- 提交表单的域名
将编辑器的容器置于一个form表单之中,后台如何获取编辑器中的内容呢?UEditor内部做了自动处理,无需用户诸如再创建一个隐藏表单来放置编辑内容等操作,只需要在配置项中设置textarea : 'editorValue'即可,后台则可以直接通过$_POST['editorValue']或者request.getParameter("editorValue")等方式来获取编辑器中的内容。 - 图片相对路径
在1.1.7版本之前(包括1.1.7版),进入编辑器内的图片地址没有经过特殊处理,造成不同的浏览器中呈现出不一样的地址结果(绝对和相对),从而对后期的程序移植造成了一定程度的影响。1.1.7.3版开始可以通过开启本配置项来强制项目中所有的相对路径都以相对于根目录的相对路径来展示,方便了同学们的后期移植。 - 黑白名单
UEditor提供了功能强大的黑白名单过滤机制,简单的几个配置就可以拦截任何不安全因素于编辑器之外。黑白名单可以同时使用,也可以单独分开使用。黑名单中的标签将会被编辑器完整地过滤掉,包括标签本身以及标签之内的任何内容。而不在白名单之中的那些标签则仅被过滤了标签本身,其内容会继续走过滤流程。
具体的黑白名单配置示例如下所示,其中$表示元素的属性: - 表情本地化
鉴于有些内网用户不能访问外网而导致的编辑器表情功能不可用,从1.1.7正式版开始,UEditor提供了表情本地化功能。更改配置emotionLocalization:true 即可开启本地表情功能。当然,本地表情功能必须要确保dialogs/emotion/目录下存在官方提供的images文件夹及所有表情文件。表情本地化之后,大家更换起表情文件来也就相当方便了! - 自动清除编辑器初始化内容
很多时候,初始化之后的编辑器框中需要留下一句诸如“请在这里发表您的看法吧!”、“欢迎使用UEditor!”之类的提示或者问候语。如何在光标定位到编辑框的时候自动清除这些内容呢?尝试下autoClearinitialContent:true吧,会有惊喜哦!
1.3前后端数据整合
1) Editor实例下的API介绍
UEditor目前向外部提供了不包括构造函数在内的12个方法,具体的类图如下:
每个方法的使用方法和示例将会在API列表中给出,点此下载。
2) 前后端数据交互
- 第一种方式是将取出的内容放置到编辑器容器标签内,示例代码如下:
- 第二种方式是使用编辑器提供的方法setContent(str)来赋值,示例代码如下: 需要注意的是,此处的echo语句必须在页面已经完成了编辑器的初始化之后才能调用,否则会出现JS代码报错。因此一般推荐使用第一种方式来初始化从服务器返回的文档内容。
3)
首先来看前端部分的文件及其配置。打开dialogs/image文件夹,我们可以发现四个文件:
- callback.js:本上传模块支持的所有回调函数,同学们可以按需选用其中的内容。对于不需要做二次开发的同学来说,可以放心地直接删除。
- image.html:图片上传对话框的主体文件。前端的配置和修改基本在此处完成。
- imageUploader.swf:Flash上传文件。
- tangram.js:百度前端框架tangram封装的flash操作模块。一般无需修改。
PS:JSP版的图片上传采用了commons-fileupload包,请先下载commons-fileupload-1.2.2.jar,并将其加入到项目中的WEB-INF/lib/目录下方可正常使用
针对编辑器的二次开发者
2.1UEditor整体架构及核心API介绍
- UEditor的整体架构
UEditor的架构设计采用了传统的分层架构模式,从低到高依次分为核心层、命令插件层和UI层这样三个低耦合的层次。
核心层提供了编辑器底层的一些方法和概念,如DOM树操作、Selection、Range等。
在核心层之上覆盖的是命令插件层。之所以叫命令插件层,是因为UEditor中所有的功能型实现都是通过这一层中的命令和插件来完成的,并且各个命令和插件之间基本互不耦合——使用者需要使用哪个功能就导入哪个功能对应的命令或者插件文件,完全不用考虑另外那些杂七杂八的JS文件(极少数插件除外,关于这些插件到时候我们也会整理出一个依赖列表来供同学们参考)。理论上来讲,所有的命令都是可以用插件来代替的。两者最大的不同是,所有的命令都是静态的,无需随编辑器的实例化而实例化;而所有的插件必须在编辑器实例化之前加载,然后绑定到实例上去。插件相比命令能够完成更加复杂的功能,最主要的一个特点是在插件内部既可以为编辑器注册命令,也可以为编辑器绑定监听事件。这个特点使得为编辑器添加任何功能都可以在插件中独立完成。
在命令插件层之上则是UI层。UEditor的UI设计与核心层和命令插件层几乎完全解耦,简单的几个配置就可以为编辑器在界面上添加额外的UI元素和功能,具体的配置下文将有专题进行深入阐述和介绍,点此马上参观。 - 核心API介绍
此处的核心API泛指Selection、Range等编辑器核心底层提供的各种方法(整理中)
2.2UEditor的事件模型
-
事件列表
事件名 说明 ready 编辑器渲染完成 beforegetcontent 获得内容之前 aftergetcontent 获得内容之后 beforesetcontent 设置内容之前 aftersetcontent 设置内容之后 beforeselectionchange 在选区改变之前触发 selectionchange 改变选区触发 beforeexeccommand 在执行命令之前触发 afterexeccommand 执行命令之后触发 reset 重新初始化
2.3命令介绍和自定义命令开发
- UEditor命令介绍
点此查看 - 自定义命令开发
UEditor中的命令是指由编辑器实例来调用并完成对应编辑功能的一个函数集合。上文说过,所有的命令都是静态的,它们不随编辑器的实例化而实例化,因此所有的命令都是“后绑定”的,只有当执行到这个命令时,编辑器才会去调用这个方法并将自身作为对应的this对象传入到对应的命令之中去运行。 下面我们将会以源码包中一个具体的实例(行间距rowspacing.js)来开发一个完整的自定义命令。
一、命令内部结构
首先我们整体来看下rowspacing.js中的文档结构图。 需要注意的是,上述代码结构是一个完整的command结构图,实际情况可以选择其中的一个或者几个方法来使用,不会影响最后效果。
二、命令具体写法
A、首先来看queryCommandState方法。这个方法中只有一句: 其实质就是检测editor实例下的highlight变量,如果当前处于highlight(高亮)状态,也即光标处于代码编辑框内时,则返回-1表示不能执行行距设置操作,否则返回0表示可以设置。
B、其次来看execCommand方法。这个方法是整个command的核心,在其中实现了当前command的所有效果。来看代码: 此处的rowspacing命令没有自己的操作内容,仅仅是调用了编辑器的另外一个命令(paragraph)来对行间距进行修改。随后返回一个执行成功或者失败的标记即可。
C、最后来看queryCommandValue()方法。这个方法用来获取当前P元素最近的block型父元素的padding值,并返回给编辑器读取和使用。
至此,一个自定义的命令到此就开发完成了。接下来的工作就是将其集成到编辑器的toolbar或者编辑器中,这部分的教程同插件,具体请看这里。
2.4插件机制和自定义插件开发
- UEditor的插件机制
JQuery的插件机制为其最后的成功立下了汗马功劳,UEditor自然也会借鉴这种成功的系统架构模式。从根本上来说,除了核心提供的几个编辑器底层封装类之外,UEditor的全部功能都是通过外挂插件或者是命令(实质上也可以看成特殊的插件)来实现的。UEditor中插件的实质是在编辑器实例下面绑定的一个以插件名字命名的函数,然后通过编辑器实例化过程去执行这个函数,并将实例对象传递到插件内部作为其this对象来完成所有的功能操作。 - 自定义插件开发
下面我们仍然会以源码包中一个具体的实例(表格table.js)来开始一个完整的插件开发之旅。
一、插件内部结构
首先我们整体来看下table.js中的文档结构图。 这个文档结构图完整地描述了一个自定义插件的主要内容。这其中包括为编辑器注册监听事件和注册命令两个方面。其他任何新插件的添加方式都可照此格式书写即可。
二、插件具体写法
在table.js文件中,首先要做的就是在baidu.editor命名空间下的plugins中创建一个名为table的插件,其实质就是为编辑器绑定一个名为table的方法。插件名字一般情况下没有用处,只有当一个页面同时存在多个编辑器,并且这几个编辑器所引入的插件不一样时,它才会有一定的用处,此处暂时不提。注册插件方法如下例:
baidu.editor.plugins['table'] = function() {}
注册鼠标和键盘事件没有特殊的地方,此处略过不提,主要来看在插件中编写命令的方法。
在插件中写命令其实跟直接写命令没什么区别。首先通过在editor下的commands中设置命令名字,然后编写execCommandState(获取当前命令是否可用,用于toolbar中的状态反射,返回0时表示命令可以执行,-1时置灰, 1时高亮)、execCommand(命令执行主体)和queryCommandValue三个主要方法即可。这三个方法可以根据不同的插件有选择地选用,无需全部编写。所有方法的参数都可以省略,省略情况下默认传入command名称。但是如果参数没有省略,则第一个参数必须是command名称。在command中,获取当前range的方法是:
var range = this.selection.getRange();
在这个range的基础上可以完成所有的编辑器操作。
三、集成插件到UEditor
当完成table.js的编写之后,接下来要做的就是为其在toolbar中添加对应的操作按钮。
首先澄清下UE中操作按钮的一些注意事项。在UE中,toolbar里的操作按钮基本上可以分为三种不同的类型:命令型、下拉菜单型和对话框型。其中下拉菜单又可以分为iframe型和普通型,对话框又可分为需要确定和不需要确定两种类型。大部分的按钮都是命令型,如B,I,U等;下拉菜单型包括表格、列表、字体字号、表情等;对话框型包括表格、地图、图片、特殊字符等。具体的差别同学们可以自己尝试下看看。而这其中,表格和列表又是其中最为复杂的两个。表格综合了下拉菜单和对话框两种类型的按钮,列表综合了命令和下拉菜单两种类型的按钮。下面来看具体的添加过程。
首先打开editor_config.js配置文件,找到toolbars和labelMap两个配置项,分别在其中添加table插件中的命令名字(单词首字母需要大写)和命令描述。这里的配置主要用来让编辑器在初始化时将命令按钮显示到toolbar中,与具体的按钮功能无关。需要注意的是,这里的配置包含了编辑器的所有按钮,往往作为系统的默认配置。多数情况下,一个编辑器往往不会完整地用到demo中的所有功能,所以在实例化一个editor的时候,通常会在里面添加toolbars参数来覆盖默认配置,示例代码如下: 在完成toolbars的配置之后,编辑器在实例化时就会去尝试创建对应的ui实例。ui实例需要在_src/ui/editorui.js进行创建和配置。
然后打开editorui.js文件,在这里,我们很快就能发现上文所说的三种不同类型的操作按钮之间的区别。btnCmds,dialogNoButton,dialogCmds,分别代表了命令型按钮、不需要确定的弹出窗口和需要确定的弹出窗口三种集合的绑定实现,而其他众多零散的分别代表各种其他类型按钮的绑定实现。Inserttable有两种类型的实现方式,对应到代码中,就为其绑定了两个不同的ui实现方式,一个是dialog,另外一个是用popup来实现的下拉菜单。
2.5常见问题解答
整理中……
若干专题教程
3.1Wordpress中集成UEditor(适用WP3.2.1版)
集成步骤:
- 下载wp-ueditor.zip.解压后将ueditor文件夹复制到wp-content/plugins下
- 将general-template.php 覆盖到wp-includes下 (最好先备份之前的文件,不喜欢可以换回来)
- 修改ueditor/editor_config.js里的URL为网站的绝对路径
3.2织梦系统dedecms集成ueditor
集成步骤:
- 下载fordedecms.zip,这是我们为织梦系统做的一个插件,用于进行内部编辑器的切换
- 将解压后得到的ueditor文件夹拷贝到织梦系统中的include文件夹下(include文件夹里可以看到ckeditor文件夹,下左图),并用ueditor文件夹里的inc_fun_funAdmin.php文件覆盖include\inc\下的同名文件(下右图)
- 修改网站里的data\config.cache.inc.php文件里的“$cfg_html_editor = 'ckeditor'”为“$cfg_html_editor = 'ueditor'”(data目录与include同级):
3.3 phpcms集成ueditor
集成步骤:
- 下载最新的编辑器包
- 将解压后的dialogs,server,themes,third-party,editor_all.js,editor_all_min.js,editor_config.js 这几个文件放到新创建的ueditor目录下
- 将ueditor目录复制到phpcms里的install_package/statics/js下
- 修改install_package/phpcms/libs/classes/form.class.php里的editor方法。 下载form.class.php
将form.class.php里的editor方法,覆盖到对应文件里即可, 可到form.class.php里修改toolbar参数,可以配置工具栏的显示样式 - 当ueditor升级时,只需要重复前3步。
3.4自定义UI
整理中……