xhEditor技术手册

1。Xheditor

xhEditor 是一个基于 jQuery 开发的简单迷你并且高效的可视化 XHTML 编辑器，基于网络访问并且兼容 IE 6.0-8.0、Firefox 3.0、Opera 9.6、Chrome 1.0、Safari 3.22。

2. 获取xhEditor

可以从GitHub下载源码

3.初始化参数列表

初始化参数示例代码：

$(’#elm1’).xheditor({tools:‘full’,skin:‘default’,showBlocktag:true,internalScript:false,internalStyle:false,width:300,height:200,loadCSS:‘http://xheditor.com/test.css’,fullscreen:true,sourceMode:true,forcePtag:true,upImgUrl:“upload.php”,upImgExt:“jpg,jpeg,gif,png”});
初始化参数列表：

tools：自定义工具按钮
参数值：full(完全),mfull(多行完全),simple(简单),mini(迷你)
或者自定义字符串，例如：‘Cut,Copy,Paste,Pastetext,|,Source,Fullscreen,About’

完整按钮表：
|：分隔符
/：强制换行
Cut：剪切
Copy：复制
Paste：粘贴
Pastetext：文本粘贴
Blocktag：段落标签
Fontface：字体
FontSize：字体大小
Bold：粗体
Italic：斜体
Underline：下划线
Strikethrough：中划线
FontColor：字体颜色
BackColor：字体背景色
SelectAll：全选
Removeformat：删除文字格式
Align：对齐
List：列表
Outdent：减少缩进
Indent：增加缩进
Link：超链接
Unlink：删除链接
Img：图片
Flash：Flash动画
Media：Windows media player视频
Emot：表情
Table：表格
Source：切换源代码模式
Preview：预览当前代码
Print：打印
Fullscreen：切换全屏模式
About：关于xhEditor
skin：皮肤风格选择
参数值：default(默认风格),o2007blue(Office2007蓝色),o2007silver(Office2007银色),vista(Vista),nostyle(NoStyle)
layerShadow：阴影的深度(按钮面板和模式窗口的背景阴影)
参数值：0(不显示阴影),大于0的数值(显示阴影并设置阴影的深度)
clickCancelDialog：点击任意位置取消按钮面板功能
参数值：默认true(开启点击取消功能),false(关闭点击取消功能，必需要点击“取消”按钮才能关闭按钮面板)
showBlocktag：显示段落标签
参数值：true(显示段落标签),false(不显示)
linkTag：样式链接link标签保留状态
参数值：true(保留样式链接link标签),false(清理样式链接link标签)
internalScript：内部JS代码保留状态
参数值：true(保留内部JS代码),false(清理内部JS代码)
inlineScript：内联JS代码保留状态
参数值：true(保留内联JS代码),false(清理内联JS代码)
internalStyle：内部样式保留状态
参数值：true(保留内部样式),false(清理内部样式)
inlineStyle：内联样式保留状态
参数值：true(保留内联样式),false(清理内联样式)
width：编辑器宽度
参数值：不带单位的数字，例：300
height：编辑器高度
参数值：不带单位的数字，例：100
loadCSS：加载样式
参数值：URL地址、URL数组以及直接内部样式，例如：‘1.css’、[‘1.css’,‘2.css’]、‘‘
备注：1.0.0 RC3新添加加载内部样式功能
fullscreen：默认全屏显示
参数值：true(全屏大小),false(标准大小)
sourceMode：默认源代码模式
参数值：true(源代码模式),false(编辑模式)
forcePtag：强制P标签
参数值：true(强制使用P标签),false(不强制),默认true
forcePasteText：强制将粘贴的内容转换为文本
参数值：true(强制转文本),false(不转文本),默认false
备注：v1.1.0新添加
disableContextmenu：禁用编辑区的右键菜单
参数值：true(禁用右键菜单),false(不禁用),默认false
备注：v1.1.0新添加
editorRoot：编辑器JS文件所在的根路径
参数值：编辑器所在的根路径，用在某些特殊情况下定位编辑器的根路径，默认为空，读取默认的编辑器根路径
备注：v1.1.0新添加
shortcuts：自定义键盘快捷方式
参数：快捷键对应事件代码的对象数组
示例：{‘ctrl+enter’:function(){$(’#frmTest’).submit();}}
备注：1.0.0 beta2新添加
urlBase：相对URL地址的基地址
参数：字符串的URL地址，用以解决前后台不在同一路径的资源定位问题
备注：1.1.0新添加
urlType：本地URL地址强制转换方式选择
参数：abs(绝对路径),root(根路径),rel(相对路径)
备注：1.0.0 beta2新添加,v1.1.0版中名字由localUrl变更为urlType
emotPath：修改表情图片的URL根路径
参数：字符串的URL地址，默认为空，指向编辑器路径下的默认表情
备注：1.1.0新添加
emotMark：是否在表情img标签上标注emot属性
参数：true(标注),false(不标注),默认为false
说明：若使用了ubb插件，请设置此属性为true
备注：1.0.0 beta2新添加
emots：添加自定义表情
参数：可定义多个JSON对象数组，示例如下：{qq:{name:‘QQ’,count:55,width:25,height:25,line:11},msn:{name:‘MSN’,count:40,width:22,height:22,line:8}}
name：表情分组名
count：表情数量
list：表情列表，例：{test1:‘表情1’,test2:‘表情2’}，键名代表文件名，扩展名必需为gif，键值代表alt信息
width：单个表情区域宽度，必需大于或等于表情最大宽度
height：单表情区域高度，必需大于或等于表情最大高度
line：单行显示表情数量
说明：count和list必需选其中一个值，注意count模式插入表情img的alt为空
备注：1.0.0 beta2新添加
wordDeepClean：Word文档深入清理选项
参数：true(深入清理),false(不深入清理，保留style样式效果),默认为true
说明：若网站应用需要保留更多的Word样式效果，请设置此值为false，不过产生的HTML代码体积会大大增大
备注：1.0.0 beta2新添加
hoverExecDelay：悬停自动执行延迟的时间
参数：数值(单位毫秒)，默认为100，设置为-1关闭此功能
备注：1.0.0 rc2新添加
defLinkText：超链接的默认文字
参数值：字符串(默认值：“点击打开链接”)
说明：只在不选择任何内容的情况下才会用到这个参数值
modalWidth：showModal弹出窗口的默认宽度
参数值：数值，默认为350
说明：弹出窗口的默认宽度
modalHeight：showModal弹出窗口的默认高度
参数值：数值，默认为220
说明：弹出窗口的默认高度
modalTitle：showModal弹出窗口是否显示上方的标题栏
参数值：true(显示),false(不显示)
说明：控制弹出窗口是否显示上方的标题栏，默认为显示，若需要显示一个更定制个性化的iframe窗口，可通过此参数隐藏上方的标题栏
upBtnText：上传按钮的文字
参数值：任意字符串,默认值：“上传”
备注：1.0.0 beta2新添加
html5Upload：是否开启HTML5上传支持
参数值：true(允许),false(不允许),默认为true允许
说明：本功能需要浏览器支持HTML5上传
备注：1.0.0Final新添加
upMultiple：允许一次上传多少个文件
参数值：大于0的数值,默认：99,设置为1关闭多文件上传
说明：本功能需要浏览器支持HTML5上传
备注：1.0.0 RC3新添加
upLinkUrl：超链接文件上传接收URL
参数值：接收用户上传的服务器端程序URL，默认留空为禁用超链接上传功能，具体使用方法请参考demo8演示文件
注：可使用内置变量：{editorRoot}，代表当前编辑器的根路径，例：{editorRoot}upload.php
upLinkExt：超链接上传前限制本地文件扩展名
参数值：超链接上传前限制的文件扩展名列表，默认为：zip,rar,txt，建议与服务端扩展名检查列表一致
upImgUrl：图片文件上传接收URL
参数值：接收用户上传的服务器端程序URL，默认留空为禁用上传功能，具体使用方法请参考demo8演示文件
注：可使用内置变量：{editorRoot}，代表当前编辑器的根路径，例：{editorRoot}upload.php
upImgExt：图片上传前限制本地文件扩展名
参数值：图片上传前限制的文件扩展名列表，默认为：jpg,jpeg,gif,png，建议与服务端扩展名检查列表一致
upFlashUrl：动画文件上传接收URL
参数值：接收用户上传的服务器端程序URL，默认留空为禁用上传功能，具体使用方法请参考demo8演示文件
注：可使用内置变量：{editorRoot}，代表当前编辑器的根路径，例：{editorRoot}upload.php
upFlashExt：动画上传前限制本地文件扩展名
参数值：动画上传前限制的文件扩展名列表，默认为：swf，建议与服务端扩展名检查列表一致
upMediaUrl：视频文件上传接收URL
参数值：接收用户上传的服务器端程序URL，默认留空为禁用上传功能，具体使用方法请参考demo8演示文件
注：可使用内置变量：{editorRoot}，代表当前编辑器的根路径，例：{editorRoot}upload.php
upMediaExt：视频上传前限制本地文件扩展名
参数值：视频上传前限制的文件扩展名列表，默认为：avi，建议与服务端扩展名检查列表一致
onUpload：文件上传成功回调函数
参数值：成功后需要执行的函数
说明：这个函数执行时返回的值为上传程序返回的msg变量，可能为字符串或者数组，若为字符串则直接代表url，若是数组，则必需包含一个url的变量，其它可由可开发者自定义
备注：1.0.0 beta2新添加
plugins：自定义按钮之插件扩展
插件对象的属性解释：
c：样式表名称
t：插件名字(鼠标在按钮上方时显示)
s：快捷方式，例：“ctrl+enter”
h：是否鼠标悬停直接执行,1:直接执行(省略当前值代表不直接执行)
e：按钮点击后需要执行的代码(省略执行代码，则把当前的插件名作为参数，调用浏览器的execCommand函数)

特别说明：
如果您希望样式表存储在系统自带的模板目录ui.css中，请将插件对象的样式名留空，则会自动按照插件名来调用相应的样式，例如：xhEdtBtnCut、xhEdtBtnCopy，其中的Cut和Copy是插件名

具体调用方法请参考演示文件夹中的demo9

4. API函数接口列表

API接口示例代码：

var editor=$(’#elm1’).xheditor({tools:‘full’,skin:‘default’});
editor.focus();
editor.setSource(‘str’)
sHtml=editor.getSource()
editor.appendHTML(‘

aaa

’)
editor.pasteHTML(‘

aaa

’)
editor.pasteText(‘str’)
sHtml=editor.formatXHTML(‘ aaa’)
editor.toggleSource()
editor.toggleFullscreen()
alert(editor.settings.upImgExt);
editor.settings.upImgExt=‘txt,doc’;
API接口列表：

focus：使编辑器获得焦点
无参数
setSource：设置编辑器源代码
参数1：要设置的源代码内容，例：‘

aaa

’
getSource：返回编辑器格式后的源代码
无参数
appendHTML：粘贴HTML内容到编辑器结尾处
参数1：要粘贴的HTML代码，例：‘

uuu

’
注：0.9.5版添加
getSelect：返回当前选中的内容
参数1：返回格式，可选’text’返回文本格式，其它所有值都返回HTML格式
pasteHTML：粘贴HTML内容到编辑器当前光标处
参数1：要粘贴的HTML代码，例：‘

uuu

’
参数2：是否覆盖粘贴，留空(覆盖粘贴)、true(粘贴在光标选择区域之前)、false(粘贴在光标选择区域之后)
pasteText：粘贴文本到编辑器当前光标处
参数1：要粘贴的文本，例：‘这里的内容完全原样显示 aaa’
参数2：是否覆盖粘贴，留空(覆盖粘贴)、true(粘贴在光标选择区域之前)、false(粘贴在光标选择区域之后)
formatXHTML：格式化XHTML代码
参数1：需要格式化的HTML代码，例：‘ aaa’，返回’ aaa’
参数2：是否代码缩进换行,true(执行缩进格式化),false(不执行缩进格式化),默认为false
toggleSource：在源代码模式和编辑模式之间切换
参数1：空(切换),true(显示源代码模式),false(显示编辑模式)
toggleFullscreen：在全屏模式和标准大小之间切换
参数1：空(切换),true(显示全屏模式),false(显示标准模式)
toggleShowBlocktag：切换块标签显示状态
参数1：空(切换),true(切换为显示块标签),false(切换为不显示块标签)
addShortcuts：添加快捷键
参数1：快捷键值，例：‘ctrl+enter’
参数2：用户按下快捷键后需要响应的程序代码，例：function(){$(’#frmTest’).submit();}
说明：允许为某个相同快捷键值重复添加多个响应代码
备注：1.0.0 beta2新添加
delShortcuts：删除快捷键
参数1：快捷键值，例：‘ctrl+enter’

备注：1.0.0Final新添加
exec：立即执行按钮及插件
参数1：工具按钮名称(不区分大小写)，例：Link、img
说明：此函数可以在插件内部或者外部Javascript代码中进行调用
showModal：显示模式窗口
参数1：模式窗口的标题title
参数2：模式窗口的内容content
参数3：模式窗口的宽度w
参数4：模式窗口的高度h
参数5：模式窗口关闭时的回调函数onRemove
showIframeModal：显示iframe式的模式窗口
参数1：模式窗口的标题
参数2：iframe的地址ifmurl，可使用内置变量：{editorRoot}，代表当前编辑器的根路径，例：{editorRoot}xheditor_plugins/test.html
参数3：提供给目标iframe页面回调用的回调函数，可以在iframe页面中以这样的形式调用：callback(‘1.gif’);
参数4：模式窗口的宽度w
参数5：模式窗口的高度h
参数6：模式窗口关闭时的回调函数onRemove
settings：获取或者修改编辑器内部参数
internalScript:是否清除内部代码
inlineScript:是否清除内联代码
internalStyle:是否清除内部样式
inlineStyle:是否清除内联样式
forcePtag:强制使用P标签
upLinkUrl:超链接上传接口地址
upLinkExt:超链接本地上传扩展限制
upImgUrl:图片上传接口地址
upImgExt:图片本地上传扩展限制
upFlashUrl:动画上传接口地址
upFlashExt:动画本地上传扩展限制
upMediaUrl:视频上传接口地址
upMediaExt:视频本地上传扩展限制
beforeSetSource:在设置源代码到编辑器前调用此函数
beforeGetSource:从编辑器返回源代码前调用此函数
focus:编辑器获得焦点时回调此函数
blur:编辑器失去焦点时回调此函数

注：修改有效变量仅限以上，其它的变量都仅在编辑器初始化时使用

5.上传程序开发规范

上传接收程序开发必读：
上传程序分标准HTML4上传和HTML5上传两种情况处理：
1, HTML4上传使用标准的表单上传域，上传文件域的name为：filedata
2, HTML5上传的整个POST数据流就是上传的文件完整数据，而本地文件名等信息储存于HTTP_CONTENT_DISPOSITION这个服务器变量中
返回内容必需是标准的json字符串，结构可以是如下：{“err”:"",“msg”:“200906030521128703.gif”} 或者 {“err”:"",“msg”:{“url”:“200906030521128703.jpg”,“localfile”:“test.jpg”,“id”:“1”}} 注：若选择结构2，则url变量是必有
需了解更多细节，请参考发行包中的demos文件夹。其中upload.php、upload.asp、upload.aspx仅为演示参考代码，若您使用的是其它的服务器脚本语言，请自行对初始化参数中的upLinkUrl、upImgUrl、upFlashUrl和upMediaUrl进行修改，并开发相应服务器上传接收程序。若您希望在自己的项目中实际使用，请自行修改代码或者重新开发，开发过程中请注意上传文件的格式及大小限制，注意服务器脚本安全问题。

上传文件管理建议方案：
在编辑器初始化时在upload.php后面跟上一个服务器生成的绝对唯一的跟踪值，例如：upload.php?infoid=123
在服务器接收程序中以这个跟踪值保存到数据库中，同时也可以限制单个跟踪值下总上传文件数或者总文件大小，否则就是一个可以上传无限个文件的漏洞了
最终当前表单提交时，再根据编辑器提交的HTML内容和数据库中上传内容进行比较，删除所有没有使用的上传文件
定期由服务器脚本删除上传数据库中没提交的文件记录，这样就能防止别人将你的网站作为免费相册空间了

6.插件开发指南

标准插件开发流程：

设计插件图标并在页面中定义好CSS
定义插件参数并写入初始化参数plugins
编写插件调用时要执行的代码
下面我们就demo09中的一个最简单插件作介绍：

<styletype=“text/css”>
.testClassName {
background:transparent url(img/plugin.gif)no-repeat 20px20px;
background-position:3px3px;
}

test7:{c:‘testClassName’,t:‘测试7：showIframeModal (Ctrl+7)’,s:‘ctrl+7’,e:function(){
var _this=this;
_this.showIframeModal(‘测试showIframeModal接口’,‘uploadgui.html’,function(v){_this.loadBookmark();_this.pasteText(‘返回值：\r\n’+v);},500,300);
}}
这个插件实现的功能是打开一个iframe，并将iframe返回的参数字符串插入到当前编辑器光标处。

其中test7为插件的name，用来在tools初始化参数中调用
c:'testClassName’为插件的样式名称
t:'测试7：showIframeModal (Ctrl+7)'是鼠标放在按钮上显示的提示文字
s:'ctrl+7’是定义插件的快捷方式，在编辑器区域里按设置的快捷方式就会执行此插件事件；
e:function(){}为插件点击后要执行的代码
特别说明：

插件执行函数中可以用this.的方式调用2.3.章节中所有的API接口函数。如果使用回调函数，请将this变量保存在临时变量中，例如_this;
在某些浏览器下，打开会转移焦点的操作界面，会导致编辑区域焦点丢失。例如：showIframeModal，在回调函数中需先执行loadBookmark函数恢复焦点，之后才能调用pasteHTML等函数;
如果希望样式表存储在系统自带的模板目录ui.css中，请将插件对象样式名留空，则会自动按照插件名来调用相应的样式，例如：xhEdtBtnCut、xhEdtBtnCopy，其中的Cut和Copy是插件名;
若希望xhEditor开发团队为您定制特殊的功能、皮肤和插件，请参阅我们提供的商业服务页面。

7.皮肤设计指南

xhEditor的皮肤保存在xheditor_skin文件夹中，每个皮肤一个子文件夹，文件夹结构如下：

xheditor_skin
└─default
├─ui.css
├─iframe.css
└─img
├─icons.gif
├─…
└─loading.gif
编辑器按钮、面板、模式窗口等样式全部统一存储在ui.css文件中
编辑区域的样式存储在iframe.css文件中
编辑器内核用到的图片及css文件中用到的所有图片统一存储在img文件夹中
ui.css文件简单解析
xheLayout：编辑器table样式；xheTool：工具按钮所在区域的样式；xheButton：按钮样式；xhePanel：操作面板的样式；xheMenu：菜单样式；xheEmot：表情样式；xheColor：颜色选择器的样式；xheDialog：面板上的对话框样式；xheModal：模式窗口样式；

xhEditor皮肤结构相对非常简单，有一定的HTML和CSS设计基础即可完成设计工作。

若希望xhEditor开发团队为您定制特殊的功能、皮肤和插件，请参阅我们提供的商业服务页面。

2.7. 关于二次开发
由于二次开发相对复杂度较高，需要对xhEditor源代码结构熟悉，而开发者的水平有高有低，因此容易出现的问题也五花八门。鉴于这个原因，xhEditor开发团队对非商业授权用户不提供任何的技术文档和技术支持，希望大家理解。

若希望xhEditor开发团队为您定制特殊的功能、皮肤和插件，请参阅我们提供的商业服务页面。

8. 其它相关

3.1. 使用常见问题

3.1. 使用常见问题
xhEditor能兼容哪些jQuery版本？
我的网页是GB2312编码的，怎样才能使xhEditor编辑器没有乱码？
正常加载了xhEditor，读取textarea的value值，为什么读取不到最新编辑结果？
怎么添加自定义的表情？
怎么覆盖编辑器自带的默认表情？
当前页面设置了document.domain，如何让xhEditor工作正常？
textarea处在隐藏的区域中，如何初始化编辑器？
使用普通表单提交，怎么每次服务端取到的值总是之前旧的编辑结果？
xhEditor能兼容哪些jQuery版本？
xhEditor最初的版本是基于jQuery 1.3.2开发的，因此目前v1.0系列的所有版本都能最大的兼容1.3.2。为了获得更好的代码性能，目前xhEditor官方更建议使用最新的1.4.2版本。

虽然说v1.0版本系列能最大的兼容jQuery 1.3.2，但是在实际测试过程中，也发现一个不可修正的问题：在IE6下无法使用缩略图上传模式。如果你不需要使用缩略图模式，可以在jQuery 1.3.2基础上完美的运行xhEditor v1.0版本系列。

我的网页是GB2312编码的，怎样才能使xhEditor编辑器没有乱码？
如果使用最新版xhEditor的mini压缩版本，因为里面的文字完全utf-8编码化，可以直接调用，不会出现乱码现象。

如果使用的是源代码js文件或早期的xhEditor版本，在非utf-8编码的网页中使用就会出现乱码现象，只需将script的charset属性设置成utf-8即可完美解决：

<scripttype="text/javascript"charset="utf-8"src=“xheditor-zh-cn.js”>
正常加载了xhEditor，读取textarea的value值，为什么读取不到最新编辑结果？
目前网络中所有的在线编辑器都是利用新创建的iframe来实现可视化编辑功能，xhEditor也不例外，所以在提交前必需要将最新的编辑结果重新同步到原来的textarea。

xhEditor默认会在textarea所在的form对象中绑定onsubmit事件，当用户点击submit按钮时，xhEditor就会将最新结果同步回textarea，随后随表单中的其它表单项一同提交到服务端脚本。因此，如果不需要用Javascript额外处理，普通的表单式提交是没任何问题的。

如果网页中需要用Javascript额外处理编辑结果，比如ajax提交表单，则有三种解决方案：

使用jQuery的事件绑定或者标准DOM绑定方法在form上绑定submit事件(绑定代码必需在xhEditor初始化代码后面)，即是在xhEditor把值回传后再读取，在相应绑定的函数中读取textarea的value值即是最新编辑结果;
使用jQuery的标准取值方法:$(’#textarea_id’).val();
使用xhEditor提供的专用读值API接口：editor.getSource();