UEditor API 文档

版本:1.2.4

UE.Editor

依赖

editor.js, UE.Utils , UE.EventBase , UE.browser , core/dom/dtd.js, UE.dom.domUtils , UE.dom.Range , core/dom/Selection.js, plugins/serialize.js

编辑器主类,包含编辑器提供的大部分公用接口

Editor

UEditor编辑器类

创建一个跟编辑器实例

  • container 编辑器容器对象
  • iframe 编辑区域所在的iframe对象
  • window 编辑区域所在的window
  • document 编辑区域所在的document对象
  • body 编辑区域所在的body对象
  • selection 编辑区域的选区对象

ready

  • editor.ready(fn) fn是当编辑器渲染好后执行的function

当编辑器ready后执行传入的fn,如果编辑器已经完成ready,就马上执行fn,fn的中的this是编辑器实例。
大部分的实例接口都需要放在该方法内部执行,否则在IE下可能会报错。

var editor = new UE.ui.Editor();
editor.render("myEditor");
editor.ready(function(){
    editor.setContent("欢迎使用UEditor!");
})

destroy

  • editor.destroy();

销毁编辑器实例对象

render

  • editor.render(containerId); //可以指定一个容器ID
  • editor.render(containerDom); //也可以直接指定容器对象

渲染编辑器的DOM到指定容器,必须且只能调用一次

sync

  • editor.sync(); //从编辑器的容器向上查找,如果找到就同步数据
  • editor.sync(formID); //formID制定一个要同步数据的form的id,编辑器的数据会同步到你指定form下

同步编辑器的数据,为提交数据做准备,主要用于你是手动提交的情况

后台取得数据得键值使用你容器上得name属性,如果没有就使用参数传入的textarea

editor.sync();
form.sumbit(); //form变量已经指向了form元素

setHeight

  • editor.setHeight(number); //纯数值,不带单位

设置编辑器高度

getContent

  • editor.getContent() ⇒ String //若编辑器中只包含字符"<p><br /></p/>"会返回空。
  • editor.getContent(fn) ⇒ String

获取编辑器内容

getContent默认是会现调用hasContents来判断编辑器是否为空,如果是,就直接返回空字符串
你也可以传入一个fn来接替hasContents的工作,定制判断的规则
editor.getContent(function(){
    return false //编辑器没有内容 ,getContent直接返回空
})

getAllHtml

  • editor.getAllHtml() ⇒ String

取得完整的html代码,可以直接显示成完整的html文档

getPlainTxt

  • editor.getPlainTxt() ⇒ String

得到编辑器的纯文本内容,但会保留段落格式

getContentTxt

  • editor.getContentTxt() ⇒ String

获取编辑器中的纯文本内容,没有段落格式

setContent

  • editor.setContent(html)

将html设置到编辑器中, 如果是用于初始化时给编辑器赋初值,则必须放在ready方法内部执行

var editor = new UE.ui.Editor()
editor.ready(function(){
    //需要ready后执行,否则可能报错
    editor.setContent("欢迎使用UEditor!");
})

focus

  • editor.focus([toEnd]) //默认focus到编辑器头部,toEnd为true时focus到内容尾部

让编辑器获得焦点,toEnd确定focus位置

execCommand

  • editor.execCommand(cmdName) ⇒ {*}

执行编辑命令cmdName,完成富文本编辑效果

queryCommandState

  • editor.queryCommandState(cmdName) ⇒ (-1|0|1)

根据传入的command命令,查选编辑器当前的选区,返回命令的状态

  • -1 当前命令不可用
  • 0 当前命令可用
  • 1 当前命令已经执行过了

queryCommandValue

  • editor.queryCommandValue(cmdName) ⇒ {*}

根据传入的command命令,查选编辑器当前的选区,根据命令返回相关的值

hasContents

  • editor.hasContents() ⇒ (true|false)
  • editor.hasContents(tags) ⇒ (true|false) //若文档中包含tags数组里对应的tag,直接返回true

检查编辑区域中是否有内容,若包含tags中的节点类型,直接返回true

默认有文本内容,或者有以下节点都不认为是空

{table:1,ul:1,ol:1,dl:1,iframe:1,area:1,base:1,col:1,hr:1,img:1,embed:1,input:1,link:1,meta:1,param:1}
editor.hasContents(['span']) //如果编辑器里有这些,不认为是空

reset

  • editor.reset()

重置编辑器,可用来做多个tab使用同一个编辑器实例

  • 清空编辑器内容
  • 清空回退列表

enable

  • editor.enable()

设置当前编辑区域可以编辑

disable

  • editor.disable()
  • editor.disable(except) //例外的命令,也即即使设置了disable,此处配置的命令仍然可以执行

设置当前编辑区域不可编辑,except中的命令除外

//禁用工具栏中除加粗和插入图片之外的所有功能
editor.disable(['bold','insertimage']);//可以是单一的String,也可以是Array

show

  • editor.show()

显示编辑器

hide

  • editor.hide()

隐藏编辑器

getLang

  • editor.getLang(path) ⇒ (JSON|String) 路径根据的是lang目录下的语言文件的路径结构

根据制定的路径,获取对应的语言资源

editor.getLang('contextMenu.delete') //如果当前是中文,那返回是的是删除

getDialog

  • editor.getDialog(dialogName) ⇒ Object

得到dialog实例对象

var dialog = editor.getDialog("insertimage");
dialog.open();   //打开dialog
dialog.close();  //关闭dialog

UE.browser

UEditor中采用的浏览器判断模块

ie

  • UE.browser.ie ⇒ true|false

检测浏览器是否为IE

opera

  • UE.browser.opera ⇒ true|false

检测浏览器是否为Opera

webkit

  • UE.browser.webkit ⇒ true|false

检测浏览器是否为webkit内核

mac

  • UE.browser.mac ⇒ true|false

检测浏览器是否为mac系统下的浏览器

quirks

  • UE.browser.quirks ⇒ true|false

检测浏览器是否处于怪异模式

gecko

  • UE.browser.gecko ⇒ true|false

检测浏览器是否处为gecko内核

ie9Compat

  • UE.browser.ie9Compat ⇒ true|false

检测浏览器是否为 IE9 模式

ie8

  • UE.browser.ie8 ⇒ true|false

检测浏览器是否为 IE8 浏览器

ie8Compat

  • UE.browser.ie8Compat ⇒ true|false

检测浏览器是否为 IE8 模式

ie7Compat

  • UE.browser.ie7Compat ⇒ true|false

检测浏览器是否运行在 兼容IE7模式

ie6Compat

  • UE.browser.ie6Compat ⇒ true|false

检测浏览器是否IE6模式或怪异模式

chrome

  • UE.browser.chrome ⇒ true|false

检测浏览器是否为chrome

safari

  • UE.browser.safari ⇒ true|false

检测浏览器是否为safari

version

  • UE.browser.version ⇒ number

浏览器版本判断
IE系列返回值为5,6,7,8,9,10等
gecko系列会返回10900,158900等.
webkit系列会返回其build号 (如 522等).

if ( UE.browser.ie && UE.browser.version == 6 ){
    alert( "Ouch!居然是万恶的IE6!" );
}

isCompatible

  • UE.browser.isCompatible ⇒ true|false

是否是兼容模式的浏览器

if ( UE.browser.isCompatible ){
    alert( "你的浏览器相当不错哦!" );
}

UE.Utils

依赖

editor.js

UEditor封装使用的静态工具函数

each 1.2.4+

  • UE.utils.each(obj,iterator,[context])

遍历数组,对象,nodeList

  • obj 要遍历的对象
  • iterator 遍历的方法,方法的第一个是遍历的值,第二个是索引,第三个是obj
  • context iterator的上下文
UE.utils.each([1,2],function(v,i){
    console.log(v)//值
    console.log(i)//索引
})
UE.utils.each(document.getElementsByTagName('*'),function(n){
    console.log(n.tagName)
})

extend

  • UE.utils.extend(target,source) ⇒ Object //覆盖扩展
  • UE.utils.extend(target,source,true) =⇒ Object //保留扩展

将source对象中的属性扩展到target对象上

inherits

  • UE.utils.inherits(subClass,superClass) ⇒ subClass

模拟继承机制,subClass继承superClass

function SuperClass(){
    this.name = "小李";
}
SuperClass.prototype = {
    hello:function(str){
        console.log(this.name + str);
    }
}
function SubClass(){
    this.name = "小张";
}
UE.utils.inherits(SubClass,SuperClass);
var sub = new SubClass();
sub.hello("早上好!"); ==> "小张早上好!"

bind

  • UE.utils.bind(fn,context) ⇒ fn

用指定的context作为fn上下文,也就是this

defer

  • UE.utils.defer(fn,delay) ⇒fn //延迟delay毫秒执行fn,返回fn
  • UE.utils.defer(fn,delay,exclusion) ⇒fn //延迟delay毫秒执行fn,若exclusion为真,则互斥执行fn

创建延迟delay执行的函数fn

function test(){
    console.log("延迟输出!");
}
//非互斥延迟执行
var testDefer = UE.utils.defer(test,1000);
testDefer();   =>  "延迟输出!";
testDefer();   =>  "延迟输出!";
//互斥延迟执行
var testDefer1 = UE.utils.defer(test,1000,true);
testDefer1();   =>  //本次不执行
testDefer1();   =>  "延迟输出!";

indexOf

  • UE.utils.indexOf(array,item) ⇒ index|-1 //默认从数组开头部开始搜索
  • UE.utils.indexOf(array,item,start) ⇒ index|-1 //start指定开始查找的位置

查找元素item在数组array中的索引, 若找不到返回-1

removeItem

  • UE.utils.removeItem(array,item)

移除数组array中的元素item

trim

  • UE.utils.trim(str) ⇒ String

删除字符串str的首尾空格

listToMap

  • UE.utils.listToMap(list) ⇒ Object //Object形如{test:1,br:1,textarea:1}

将字符串list(以','分隔)或者数组list转成哈希对象

unhtml

  • UE.utils.unhtml(str); ⇒ String
  • UE.utils.unhtml(str,reg) ⇒ String

将str中的html符号转义,默认将转义&<">四个字符,可自定义reg来确定需要转义的字符

var html = '<body>You say:"你好!Baidu & UEditor!"</body>';
UE.utils.unhtml(html);   ==>  &lt;body&gt;You say:&quot;你好!Baidu &amp; UEditor!&quot;&lt;/body&gt;
UE.utils.unhtml(html,/[<>]/g)  ==>  &lt;body&gt;You say:"你好!Baidu & UEditor!"&lt;/body&gt;

html

  • UE.utils.html(str) ⇒ String //详细参见unhtml

将str中的转义字符还原成html字符

cssStyleToDomStyle

  • UE.utils.cssStyleToDomStyle(cssName) ⇒ String

将css样式转换为驼峰的形式。如font-size => fontSize

loadFile

  • UE.utils.loadFile(doc,obj)
  • UE.utils.loadFile(doc,obj,fn)

动态加载文件到doc中,并依据obj来设置属性,加载成功后执行回调函数fn

//指定加载到当前document中一个script文件,加载成功后执行function
utils.loadFile( document, {
    src:"test.js",
    tag:"script",
    type:"text/javascript",
    defer:"defer"
}, function () {
    console.log('加载成功!')
});

isEmptyObject

  • UE.utils.isEmptyObject(obj) ⇒ true|false

判断obj对象是否为空

UE.utils.isEmptyObject({}) ==>true
UE.utils.isEmptyObject([]) ==>true
UE.utils.isEmptyObject("") ==>true

fixColor

  • UE.utils.fixColor(name,value) ⇒ value

统一将颜色值使用16进制形式表示

rgb(255,255,255)  => "#ffffff"

clone

  • UE.utils.clone(source) ⇒ anthorObj 新的对象是完整的source的副本
  • UE.utils.clone(source,target) ⇒ target包含了source的所有内容,重名会覆盖

深度克隆对象,从source到target

transUnitToPx

  • UE.utils.transUnitToPx('20pt') ⇒ '27px'
  • UE.utils.transUnitToPx('0pt') ⇒ '0'

转换cm/pt到px

domReady

  • UE.utils.domReady(fn) ⇒ fn //返回一个延迟执行的方法

DomReady方法,回调函数将在dom树ready完成后执行

cssRule

  • UE.utils.cssRule('添加的样式的节点名称',['样式','放到哪个document上'])
  • UE.utils.cssRule('body','body{background:#ccc}') ⇒ null //给body添加背景颜色
  • UE.utils.cssRule('body') ⇒样式的字符串 //取得key值为body的样式的内容,如果没有找到key值先关的样式将返回空,例如刚才那个背景颜色,将返回 body{background:#ccc}
  • UE.utils.cssRule('body','') ⇒null //清空给定的key值的背景颜色

动态添加css样式

isString

  • UE.utils.isString(str) ⇒ true|false

判断str是否为字符串

isArray

  • UE.utils.isArray(obj) ⇒ true|false

判断array是否为数组

isFunction

  • UE.utils.isFunction(obj) ⇒ true|false

判断obj对象是否为方法

isNumber

  • UE.utils.isNumber(obj) ⇒ true|false

判断obj对象是否为数字


UE.EventBase

依赖

editor.js, UE.Utils

UE采用的事件基类,继承此类的对应类将获取addListener,removeListener,fireEvent方法。
在UE中,Editor以及所有ui实例都继承了该类,故可以在对应的ui对象以及editor对象上使用上述方法。

addListener

  • editor.addListener(types,fn) //types为事件名称,多个可用空格分隔

注册事件监听器

editor.addListener('selectionchange',function(){
     console.log("选区已经变化!");
})
editor.addListener('beforegetcontent aftergetcontent',function(type){
        if(type == 'beforegetcontent'){
            //do something
        }else{
            //do something
        }
        console.log(this.getContent) // this是注册的事件的编辑器实例
})

removeListener

  • editor.removeListener(types,fn) //types为事件名称,多个可用空格分隔

移除事件监听器

//changeCallback为方法体
editor.removeListener("selectionchange",changeCallback);

fireEvent

  • editor.fireEvent(types) //types为事件名称,多个可用空格分隔

触发事件

editor.fireEvent("selectionchange");

UE.dom.domUtils

依赖

editor.js, UE.Utils , UE.browser , core/dom/dtd.js

UEditor封装的底层dom操作库

getPosition

  • UE.dom.domUtils.getPosition(nodeA,nodeB) ⇒ Number

获取节点A相对于节点B的位置关系

 switch (returnValue) {
     case 0: //相等,同一节点
     case 1: //无关,节点不相连
     case 2: //跟随,即节点A头部位于节点B头部的后面
     case 4: //前置,即节点A头部位于节点B头部的前面
     case 8: //被包含,即节点A被节点B包含
     case 10://组合类型,即节点A满足跟随节点B且被节点B包含。实际上,如果被包含,必定跟随,所以returnValue事实上不会存在8的情况。
     case 16://包含,即节点A包含节点B
     case 20://组合类型,即节点A满足前置节点A且包含节点B。同样,如果包含,必定前置,所以returnValue事实上也不会存在16的情况
 }

getNodeIndex

  • UE.dom.domUtils.getNodeIndex(node) ⇒ Number //索引值从0开始

返回节点node在父节点中的索引位置

inDoc

  • UE.dom.domUtils.inDoc(node,doc) ⇒ true|false

检测节点node是否在节点doc的树上,实质上是检测是否被doc包含

findParent

  • UE.dom.domUtils.findParent(node) ⇒ Element // 直接返回node节点的父节点
  • UE.dom.domUtils.findParent(node,filterFn) ⇒ Element //filterFn为过滤函数,node作为参数,返回true时才会将node作为符合要求的节点返回
  • UE.dom.domUtils.findParent(node,filterFn,includeSelf) ⇒ Element //includeSelf指定是否包含自身

查找node节点的祖先节点

findParentByTagName

  • UE.dom.domUtils.findParentByTagName(node,tagNames) ⇒ Element //tagNames支持数组,区分大小写
  • UE.dom.domUtils.findParentByTagName(node,tagNames,includeSelf) ⇒ Element //includeSelf指定是否包含自身
  • UE.dom.domUtils.findParentByTagName(node,tagNames,includeSelf,excludeFn) ⇒ Element //excludeFn指定例外过滤条件,返回true时忽略该节点

通过tagName查找node节点的祖先节点

findParents

  • UE.dom.domUtils.findParents(node) ⇒ Array //返回一个祖先节点数组集合,不包含自身
  • UE.dom.domUtils.findParents(node,includeSelf) ⇒ Array //返回一个祖先节点数组集合,includeSelf指定是否包含自身
  • UE.dom.domUtils.findParents(node,includeSelf,filterFn) ⇒ Array //返回一个祖先节点数组集合,filterFn指定过滤条件,返回true的node将被选取
  • UE.dom.domUtils.findParents(node,includeSelf,filterFn,closerFirst) ⇒ Array //返回一个祖先节点数组集合,closerFirst为true的话,node的直接父亲节点是数组的第0个

查找节点node的祖先节点集合

insertAfter

  • UE.dom.domUtils.insertAfter(node,newNode) ⇒ newNode

在节点node后面插入新节点newNode

remove

  • UE.dom.domUtils.remove(node) ⇒ node
  • UE.dom.domUtils.remove(node,keepChildren) ⇒ node

删除节点node,并根据keepChildren指定是否保留子节点

getNextDomNode

  • UE.dom.domUtils.getNextDomNode(node) ⇒ Element

取得node节点在dom树上的下一个节点,即多叉树遍历

isBookmarkNode

  • UE.dom.domUtils.isBookmarkNode(node) ⇒ true|false

检测节点node是否属于bookmark节点

getWindow

  • UE.dom.domUtils.getWindow(node) ⇒ window对象

获取节点node所在的window对象

getCommonAncestor

  • UE.dom.domUtils.getCommonAncestor(nodeA,nodeB) ⇒ Element

得到nodeA与nodeB公共的祖先节点

clearEmptySibling

  • UE.dom.domUtils.clearEmptySibling(node)
  • UE.dom.domUtils.clearEmptySibling(node,ignoreNext) //ignoreNext指定是否忽略右边空节点
  • UE.dom.domUtils.clearEmptySibling(node,ignoreNext,ignorePre) //ignorePre指定是否忽略左边空节点

清除node节点左右兄弟为空的inline节点

<b></b><i></i>xxxx<b>bb</b> --> xxxx<b>bb</b>

split

  • UE.dom.domUtils.split(node,offset) ⇒ TextNode //返回从切分位置开始的后一个文本节点

将一个文本节点node拆分成两个文本节点,offset指定拆分位置

isWhitespace

  • UE.dom.domUtils.isWhitespace(node) ⇒ true|false

检测节点node是否为空节点(包括空格、换行、占位符等字符)

getXY

  • UE.dom.domUtils.getXY(element) ⇒ Object //返回坐标对象{x:left,y:top}

获取元素element相对于viewport的位置坐标

on

  • UE.dom.domUtils.on(element,type,handler) //type支持数组传入

为元素element绑定原生DOM事件,type为事件类型,handler为处理函数

UE.dom.domUtils.on(document.body,"click",function(e){
    //e为事件对象,this为被点击元素对戏那个
})
UE.dom.domUtils.on(document.body,["click","mousedown"],function(evt){
    //evt为事件对象,this为被点击元素对象
})

un

  • UE.dom.donUtils.un(element,type,handler) //参见on

解除原生DOM事件绑定

isSameElement

  • UE.dom.domUtils.isSameElement(nodeA,nodeB) ⇒ true|false

比较节点nodeA与节点nodeB是否具有相同的标签名、属性名以及属性值

<span  style="font-size:12px">ssss</span> and <span style="font-size:12px">bbbbb</span>   => true
<span  style="font-size:13px">ssss</span> and <span style="font-size:12px">bbbbb</span>   => false

isSameStyle

  • UE.dom.domUtils.isSameStyle(nodeA,nodeB) ⇒ true|false

判断节点nodeA与节点nodeB的元素属性是否一致

isBlockElm

  • UE.dom.domUtils.isBlockElm(node) ⇒ true|false

检查节点node是否为块元素

isBody

  • UE.dom.domUtils.isBody(node) ⇒ true|false

检测node节点是否为body节点

breakParent

  • UE.dom.domUtils.breakParent(node,parent) ⇒ node

以node节点为中心,将该节点的指定祖先节点parent拆分成2块

<b>ooo</b>是node节点
<p>xxxx<b>ooo</b>xxx</p> ==> <p>xxx</p><b>ooo</b><p>xxx</p>
<p>xxxxx<span>xxxx<b>ooo</b>xxxxxx</span></p>   =>   <p>xxxxx<span>xxxx</span></p><b>ooo</b><p><span>xxxxxx</span></p>

isEmptyInlineElement

  • UE.dom.domUtils.isEmptyInlineElement(node) ⇒ 1|0

检查节点node是否是空inline节点

<b><i></i></b> => 1
<b><i></i><u></u></b> => 1
<b></b> => 1
<b>xx<i></i></b> => 0

trimWhiteTextNode

  • UE.dom.domUtils.trimWhiteTextNode(node)

删除node节点下的左右空白文本子节点

mergeChild

合并node节点下相同的子节点

UE.dom.domUtils.mergeChild(node,tagName) //tagName要合并的子节点的标签

<p><span style="font-size:12px;">xx<span style="font-size:12px;">aa</span>xx</span></p>
==> UE.dom.domUtils.mergeChild(node,'span')
<p><span style="font-size:12px;">xxaaxx</span></p>

getElementsByTagName

  • UE.dom.domUtils.getElementsByTagName(node,tagName) ⇒ Array //节点集合数组

原生方法getElementsByTagName的封装

mergeToParent

  • UE.dom.domUtils.mergeToParent(node)

将节点node合并到父节点上

<span style="color:#fff"><span style="font-size:12px">xxx</span></span> ==> <span style="color:#fff;font-size:12px">xxx</span>

mergeSibling

  • UE.dom.domUtils.mergeSibling(node)
  • UE.dom.domUtils.mergeSibling(node,ignorePre) //ignorePre指定是否忽略左兄弟
  • UE.dom.domUtils.mergeSibling(node,ignorePre,ignoreNext) //ignoreNext指定是否忽略右兄弟

合并节点node的左右兄弟节点

<b>xxxx</b><b>ooo</b><b>xxxx</b> ==> <b>xxxxoooxxxx</b>

unSelectable

  • UE.dom.domUtils.unSelectable(node)

设置节点node及其子节点不会被选中

removeAttributes

  • UE.dom.domUtils.removeAttributes(node,attrNames)

删除节点node上的属性attrNames,attrNames为属性名称数组

//Before remove
<span style="font-size:14px;" id="test" name="followMe">xxxxx</span>
//Remove
UE.dom.domUtils.removeAttributes(node,["id","name"]);
//After remove
<span style="font-size:14px;">xxxxx</span>

createElement

  • UE.dom.domUtils.createElement(doc,tag,attrs) ⇒ Node //返回创建的节点

在doc下创建一个标签名为tag,属性为attrs的元素

setAttributes

  • UE.dom.domUtils.setAttributes(node,attrs) ⇒ node

为节点node添加属性attrs,attrs为属性键值对

getComputedStyle

  • UE.dom.domUtils.getComputedStyle(element,styleName) ⇒ String //返回对应样式名称的样式值

获取元素element的计算样式

getComputedStyle(document.body,"font-size")  =>  "15px"
getComputedStyle(form,"color")  =>  "#ffccdd"

removeClasses

  • UE.dom.domUtils.removeClasses(element,classNames)

在元素element上删除classNames,支持同时删除多个

//执行方法前的dom结构
<span class="test1 test2 test3">xxx</span>
//执行方法
UE.dom.domUtils.removeClasses(element,["test1","test3"])
//执行方法后的dom结构
<span class="test2">xxx</span>

addClass

  • UE.dom.domUtils.addClass(element,classNames)

在元素element上增加一个样式类className,支持以空格分开的多个类名
如果相同的类名将不会添加

hasClass

  • UE.dom.domUtils.hasClass(element,className) ⇒true|false

判断元素element是否包含样式类名className,支持以空格分开的多个类名,多个类名顺序不同也可以比较

getStyle

  • UE.dom.domUtils.getStyle(element,name) ⇒ String

获取元素element的某个样式值

setStyle

  • UE.dom.domUtils.setStyle(element,name,value)

为元素element设置样式属性值

setStyles

  • UE.dom.domUtils.setStyle(element,styles) //styles为样式键值对

为元素element设置样式属性值

filterNodeList 1.2.4+

  • UE.dom.domUtils.filterNodeList(nodelist,filter,onlyFirst) ⇒ 节点

对于nodelist用filter进行过滤

UE.dom.domUtils.filterNodeList(document.getElementsByTagName('*'),'div p') //返回第一个是div或者p的节点
UE.dom.domUtils.filterNodeList(document.getElementsByTagName('*'),function(n){return n.getAttribute('src')})
//返回第一个带src属性的节点
UE.dom.domUtils.filterNodeList(document.getElementsByTagName('*'),'i',true) //返回数组,里边都是i节点

UE.dom.Range

依赖

editor.js, UE.Utils , UE.browser , UE.dom.domUtils , core/dom/dtd.js

Range范围实现类,本类是UEditor底层核心类,统一w3cRange和ieRange之间的差异,包括接口和属性

Range

  • new UE.dom.Range(document) ⇒ Range 实例

创建一个跟document绑定的空的Range实例

  • startContainer 开始边界的容器节点,可以是elementNode或者是textNode
  • startOffset 容器节点中的偏移量,如果是elementNode就是childNodes中的第几个,如果是textNode就是nodeValue的第几个字符
  • endContainer 结束边界的容器节点,可以是elementNode或者是textNode
  • endOffset 容器节点中的偏移量,如果是elementNode就是childNodes中的第几个,如果是textNode就是nodeValue的第几个字符
  • document 跟range关联的document对象
  • collapsed 是否是闭合状态

cloneContents

  • range.cloneContents() ⇒ DocumentFragment

克隆选中的内容到一个fragment里,如果选区是空的将返回null

deleteContents

  • range.deleteContents() ⇒ Range

删除当前选区范围中的所有内容并返回range实例,这时的range已经变成了闭合状态

DOM Element :
<b>x<i>x[x<i>xx]x</b>
//执行方法后
<b>x<i>x<i>|x</b>
注意range改变了
range.startContainer => b
range.startOffset  => 2
range.endContainer => b
range.endOffset => 2
range.collapsed => true

extractContents

  • range.extractContents() ⇒ DocumentFragment

将当前的内容放到一个fragment里并返回这个fragment,这时的range已经变成了闭合状态

DOM Element :
<b>x<i>x[x<i>xx]x</b>
//执行方法后
返回的fragment里的 dom结构是
<i>x<i>xx
dom树上的结构是
<b>x<i>x<i>|x</b>
注意range改变了
range.startContainer => b
range.startOffset  => 2
range.endContainer => b
range.endOffset => 2
range.collapsed => true

setStart

  • range.setStart(node,offset) ⇒ Range

设置range的开始位置位于node节点内,偏移量为offset
如果node是elementNode那offset指的是childNodes中的第几个,如果是textNode那offset指的是nodeValue的第几个字符

setEnd

  • range.setEnd(node,offset) ⇒ Range

设置range的结束位置位于node节点,偏移量为offset
如果node是elementNode那offset指的是childNodes中的第几个,如果是textNode那offset指的是nodeValue的第几个字符

setStartAfter

  • range.setStartAfter(node) ⇒ Range

将Range开始位置设置到node节点之后

<b>xx<i>x|x</i>x</b>
执行setStartAfter(i)后
range.startContainer =>b
range.startOffset =>2

setStartBefore

  • range.setStartBefore(node) ⇒ Range

将Range开始位置设置到node节点之前

<b>xx<i>x|x</i>x</b>
执行setStartBefore(i)后
range.startContainer =>b
range.startOffset =>1

setEndAfter

  • range.setEndAfter(node) ⇒ Range

将Range结束位置设置到node节点之后

<b>xx<i>x|x</i>x</b>
setEndAfter(i)后
range.endContainer =>b
range.endtOffset =>2

setEndBefore

  • range.setEndBefore(node) ⇒ Range

将Range结束位置设置到node节点之前

<b>xx<i>x|x</i>x</b>
执行setEndBefore(i)后
range.endContainer =>b
range.endtOffset =>1

setStartAtFirst

  • range.setStartAtFirst(node) ⇒ Range

将Range开始位置设置到node节点内的开始位置

setStartAtLast

  • range.setStartAtLast(node) ⇒ Range

将Range开始位置设置到node节点内的结束位置

setEndAtFirst

  • range.setEndAtFirst(node) ⇒ Range

将Range结束位置设置到node节点内的开始位置

setEndAtLast

  • range.setEndAtLast(node) ⇒ Range

将Range结束位置设置到node节点内的结束位置

selectNode

  • range.selectNode(node) ⇒ Range

选中完整的指定节点,并返回包含该节点的range

selectNodeContents

  • range.selectNodeContents(node) ⇒ Range

选中node内部的所有节点,并返回对应的range

<b>xx[x<i>xxx</i>]xxx</b>
执行后
<b>[xxx<i>xxx</i>xxx]</b>
range.startContainer =>b
range.startOffset =>0
range.endContainer =>b
range.endOffset =>3

cloneRange

  • range.cloneRange() ⇒ Range

克隆一个新的range对象

collapse

  • range.collapse() ⇒ Range
  • range.collapse(true) ⇒ Range //闭合选区到头部

让选区闭合到尾部,若toStart为真,则闭合到头部

shrinkBoundary

  • range.shrinkBoundary() ⇒ Range //range开始位置和结束位置都调整,参见adjustmentBoundary
  • range.shrinkBoundary(true) ⇒ Range //仅调整开始位置,忽略结束位置

调整range的边界,使其"收缩"到最小的位置

<b>xx[</b>xxxxx] ==> <b>xx</b>[xxxxx]
<b>x[xx</b><i>]xxx</i> ==> <b>x[xx]</b><i>xxx</i>
[<b><i>xxxx</i>xxxxxxx</b>] ==> <b><i>[xxxx</i>xxxxxxx]</b>

getCommonAncestor

  • range.getCommonAncestor([includeSelf, ignoreTextNode]) ⇒ Element

获取当前range所在位置的公共祖先节点,当前range位置可以位于文本节点内,也可以包含整个元素节点,也可以位于两个节点之间

<b>xx[xx<i>xx]x</i>xxx</b> ==>getCommonAncestor() ==> b
<b>[<img/>]</b>
range.startContainer ==> b
range.startOffset ==> 0
range.endContainer ==> b
range.endOffset ==> 1
range.getCommonAncestor() ==> b
range.getCommonAncestor(true) ==> img
<b>xxx|xx</b>
range.startContainer ==> textNode
range.startOffset ==> 3
range.endContainer ==> textNode
range.endOffset ==> 3
range.getCommonAncestor() ==> textNode
range.getCommonAncestor(null,true) ==> b

trimBoundary

  • range.trimBoundary([ignoreEnd]) ⇒ Range //true忽略结束边界

调整边界容器,如果是textNode,就调整到elementNode上

DOM Element :
<b>|xxx</b>
startContainer = xxx; startOffset = 0
//执行后本方法后
startContainer = <b>;  startOffset = 0
Dom Element :
<b>xx|x</b>
startContainer = xxx;  startOffset = 2
//执行本方法后,xxx被实实在在地切分成两个TextNode
startContainer = <b>; startOffset = 1

txtToElmBoundary

如果选区在文本的边界上,就扩展选区到文本的父节点上

Dom Element :
<b> |xxx</b>
startContainer = xxx;  startOffset = 0
//本方法执行后
startContainer = <b>; startOffset = 0
Dom Element :
<b> xxx| </b>
startContainer = xxx; startOffset = 3
//本方法执行后
startContainer = <b>; startOffset = 1

insertNode

  • range.insertNode(node) ⇒ Range //node可以是textNode,elementNode,fragment

在当前选区的开始位置前插入一个节点或者fragment,range的开始位置会在插入节点的前边

Range :
xxx[x<p>xxxx</p>xxxx]x<p>sdfsdf</p>
待插入Node :
<p>ssss</p>
执行本方法后的Range :
xxx[<p>ssss</p>x<p>xxxx</p>xxxx]x<p>sdfsdf</p>

setCursor

  • range.setCursor([toEnd]) ⇒ Range //toEnd为true时,光标闭合到选区的末尾

设置光标闭合位置,toEnd设置为true时光标将闭合到选区的结尾

createBookmark

  • range.createBookmark([serialize]) ⇒ Object //{start:开始标记,end:结束标记,id:serialize} serialize为真时,开始结束标记是插入节点的id,否则是插入节点的引用

创建当前range的一个书签,记录下当前range的位置,方便当dom树改变时,还能找回原来的选区位置

moveToBookmark

  • range.moveToBookmark(bookmark) ⇒ Range //让当前的range选到给定bookmark的位置,bookmark对象是由range.createBookmark创建的

移动边界到书签位置,并删除插入的书签节点

enlarge

  • range.enlarge() ⇒ Range

调整range的边界,使其"放大"到最近的父block节点

<p><span>xxx</span><b>x[x</b>xxxxx]</p><p>xxx</p> ==> [<p><span>xxx</span><b>xx</b>xxxxx</p>]<p>xxx</p>

adjustmentBoundary

调整Range的边界,使其"缩小"到最合适的位置

<b>xx[</b>xxxxx] ==> <b>xx</b>[xxxxx]
<b>x[xx</b><i>]xxx</i> ==> <b>x[xx</b>]<i>xxx</i>

applyInlineStyle

  • range.applyInlineStyle(tagName) ⇒ Range //tagName为需要添加的样式标签名
  • range.applyInlineStyle(tagName,attrs) ⇒ Range //attrs为属性json对象

给range选区中的内容添加给定的标签,主要用于inline标签

<p>xxxx[xxxx]x</p>  ==>  range.applyInlineStyle("strong")  ==>  <p>xxxx[<strong>xxxx</strong>]x</p>
<p>xx[dd<strong>yyyy</strong>]x</p>  ==>  range.applyInlineStyle("strong")  ==>  <p>xx[<strong>ddyyyy</strong>]x</p>
<p>xxxx[xxxx]x</p>  ==>  range.applyInlineStyle("strong",{"style":"font-size:12px"})  ==>  <p>xxxx[<strong style="font-size:12px">xxxx</strong>]x</p>

removeInlineStyle

  • range.removeInlineStyle(tagNames) ⇒ Range //tagNames 为需要去掉的样式标签名,支持"b"或者["b","i","u"]

对当前range选中的节点,去掉给定的标签节点,但标签中的内容保留,主要用于处理inline元素

xx[x<span>xxx<em>yyy</em>zz]z</span>  => range.removeInlineStyle(["em"])  => xx[x<span>xxxyyyzz]z</span>

getClosedNode

  • range.getClosedNode() ⇒ node|null

得到一个自闭合的节点,常用于获取自闭和的节点,例如图片节点

<b>xxxx[<img />]xxx</b>

select

  • range.select(); ⇒ Range

根据当前range选中内容节点(在页面上表现为反白显示)

scrollToView

  • range.scrollToView([win,offset]) ⇒ Range //针对window对象,若不指定,将以编辑区域的窗口为准,offset偏移量

滚动条跳到当然range开始的位置


UE.ajax

依赖

UE.Utils

UEditor内置的ajax请求模块

request

  • UE.ajax.request(url,ajaxOpt);

发出ajax请求,ajaxOpt中默认包含method,timeout,async,data,onsuccess以及onerror等六个,支持自定义添加参数

UE.ajax.request('http://www.xxxx.com/test.php',{
    //可省略,默认POST
    method:'POST',
    //可以自定义参数
    content:'这里是提交的内容',
    //也可以直接传json,但是只能命名为data,否则当做一般字符串处理
    data:{
        name:'UEditor',
        age:'1'
    }
    onsuccess:function(xhr){
        console.log(xhr.responseText);
    },
    onerror:function(xhr){
        console.log(xhr.responseText);
    }
})

UE

UEditor的顶部命名空间

getEditor 1.2.4+

  • UE.getEditor(id,[opt]) ⇒ Editor实例

提供一个全局的方法得到编辑器实例

  • id 放置编辑器的容器id, 如果容器下的编辑器已经存在,就直接返回
  • opt 编辑器的可选参数
 UE.getEditor('containerId',{onready:function(){//创建一个编辑器实例
     this.setContent('hello')
 }});
 UE.getEditor('containerId'); //返回刚创建的实例

编辑器事件接口

ready

  • editor.addListener("ready",fn)

编辑器加载完成事件(核心),在编辑器准备好所有运行条件时触发,大部分场景可以使用editor.ready(fn)取代。

editor.addListener("ready",function(){
    //this为editor实例
    this.setContent("欢迎使用UEditor!");
})
//同如下接口方式调用
editor.ready(function(){
    this.setContent("欢迎使用UEditor!");
})

selectionChange

  • editor.addListener("selectionChange",fn)
  • editor.fireEvent("selectionChange")

选区变化事件(核心),当选区出现变化时触发。
在UEditor中,任何涉及到光标改变的操作都会触发选区变化事件,该事件主要用来实现工具栏状态反射。

editor.addListener("selectionChange",function(){
    //this为editor实例
})

contentChange

  • editor.addListener("contentChange",fn)
  • editor.fireEvent("contentChange")

内容变化事件(核心),当编辑区域中的文本内容出现变化时触发

(before|after)Paste

  • editor.addListener("beforePaste",fn)

粘贴事件(核心),当使用ctr+v快捷键粘贴(包括Chrome、FF浏览器的右键粘贴)时会触发本事件

  • beforePaste 在将粘贴的内容写到编辑器之前触发,这个事件触发时,粘贴的内容还未在编辑器内显示
  • afterPaste 粘贴的内容已经写到编辑器里边后触发
editor.addListener("beforePaste",function(type,data){
    //beforePaste事件监听区别于afterPaste事件监听最主要的一个方面是存在一个data参数,
    //该data参数是一个对象,包含属性html。
    //若用户在此处更改该html的值时,将会影响粘贴到编辑器中的内容,主要用于粘贴时需要特殊处理的一些场景。
    console.log(this.getContent) //this都是当前编辑器的实例
    //before事件才用这个参数,用来在写出编辑器之前对粘贴进来的内容进行最后的修改
    data.html = "我把粘贴内容改成了这句话";
})

(before|after)SetContent

  • editor.addListener("beforeSetContent",fn)

设置内容事件(核心),当调用setContent方法时触发

  • beforeSetContent 在内容写到编辑器之前触发
  • afterSetContent 内容已经写到编辑器里边后触发
editor.addListener("beforeSetContent",function(type,data){
    //beforeSetContent事件监听区别于afterSetContent事件监听最主要的一个方面是存在一个data参数,
    //该data参数是一个对象,包含属性html。
    //若用户在此处更改该html的值时,将会影响设置到编辑器中的内容,主要用于设置内容时需要特殊处理的一些场景。
    data.html = "我把设置内容改成了这句话";
})

getAllHtml

  • editor.addListener("getAllHtml",fn)

getAllHtml事件,当调用getAllHtml方法时触发

  • 主要用来对于生成的整个html代码中的head内容进行定制,比如你想插入你自己的样式,script标签等,用来在展示时使用
editor.addListener("getAllHtml",function(type,data){
    //data是document中head部分html的封装,可通过data.html来获取对应字符串。
    //需要修改的话得重新赋值data.html = '<style type="text/css"> body{margin:0;}</style>';
})

beforeSubmit

  • editor.addListener("beforeSubmit",fn) //若fn返回false,则阻止本次提交

内容提交事件(插件),当内容提交插件加载并调用了autosubmit命令时触发,多用于提交之前的验证

editor.addListener("beforeSubmit",function(){
    if(!editor.hasContents()){
        return false;
    }
})

catchRemoteError

  • editor.addListener("catchRemoteError",fn)

如果抓取远程的图片失败了,就触发

editor.addListener("catchRemoteError",function(){
    console.log("抓取失败了!")
})

catchRemoterSuccess

  • editor.addListener("catchRemoterSuccess",fn)

当抓取远程的图片成功并会返回生成图片的链接时触发

editor.addListener("catchRemoterSuccess",function(){
    console.log("抓取成功")
})

sourceModeChanged

  • editor.addListener("sourceModeChanged",fn)

编辑模式切换事件(插件),当源码模式和富文本模式发生切换时触发事件

editor.addListener("sourceModeChanged",function(type,mode){
    //mode代表了当前的编辑模式,true代表切换到了源码模式,false代表切换到了富文本模式
})

fullScreenChanged

  • editor.addListener("fullScreenChanged",fn)

全屏切换事件(插件),当执行全屏切换的时候触发事件

editor.addListener("fullScreenChanged",function(type,mode){
    //mode代表当前是否全屏,true代表切换到了全屏模式,false代表切换到了普通模式
})

wordCountOverflow

  • editor.addListener("wordCountOverflow",fn)

字数超出限制事件(插件),当输入的字符数超出配置项配置时触发

editor.addListener("wordCountOverflow",function(type,length){
    console.log(length)
})

编辑器命令接口

UEditor中执行命令的统一调用格式为

editor.execCommand("cmdName"[,opt]);

检测当前命令是否可用的方法是

editor.queryCommandState("cmdName");

部分命令可以返回命令值,其格式为

editor.queryCommandValue("cmdName");

anchor

  • editor.execCommand("anchor","name"); //锚点的名字

插入锚点

bold

  • editor.execCommand("bold");

为当前选中文字添加粗体效果

italic

  • editor.execCommand("italic");

为当前选中文字添加斜体效果

underline

  • editor.execCommand("underline");

为当前选中文字添加下划线效果

strikethrough

  • editor.execCommand("strikethrough");

为当前选中文字添加删除线效果

superscript

  • editor.execCommand("superscript");

将当前选中文字转换成上标

subscript

  • editor.execCommand("subscript");

将当前选中文字转换成下标

foreColor

  • editor.execCommand("foreColor","#ffffff");

为当前选中文字添加颜色

backColor

  • editor.execCommand("backColor","#dddddd");

为当前选中文字添加背景颜色

fontFamily

  • editor.execCommand("fontFamily","微软雅黑,Microsoft YaHei");

设置当前选中文字的字体

fontSize

  • editor.execCommand("fontSize","32px");

设置当前选中文字的字号

paragraph

  • editor.execCommand("paragraph","h1");

设置当前选区的段落格式,如p,h1,h2,h3,...

insert(Un)OrderedList

  • editor.execCommand("insertOrderedList");

将当前选区变换成有序或者无序列表

lineHeight

  • editor.execCommand("lineHeight");

设置当前选区的行间距

justify

  • editor.execCommand("justify",align); //align可为Left,Right,Center,Justify

设置当前选区中的字体对齐方式

toUppercase

  • editor.execCommand("toUppercase");

将当前选中文字中的字母转换成大写

toLowercase

  • editor.execCommand("toLowercase");

将当前选中文字中的字母转换成小写

blockquote

  • editor.execCommand("blockquote");

为当前选区所在的块级元素添加引用标记

directionality

  • editor.execCommand("directionality",dir); //dir可为LTR,RTL

设置当前选区所在块级元素的文字输入方向

removeFormat

  • editor.execCommand("removeFormat") //根据editor_config.js里的removeFormatTags,removeFormatAttributes两个属性作为规则
  • editor.execCommand("removeFormat",tags,style); //清除指定tags上的指定style

清除当前选中文字上的所有样式或者指定样式

editor.execCommand("removeFormat",'span,a','color,background-color')

pastePlain

  • ue.execCommand("pastePlain");

切换纯文本粘贴模式

formatMatch

  • editor.execCommand("formatMatch");

开启格式刷功能

clearDoc

  • editor.execCommand("clearDoc");

清空文档

delete

  • editor.execCommand("delete");

删除当前选中文本

selectAll

  • editor.execCommand("selectAll");

全部选择

undo

  • editor.execCommand("undo");

撤销操作

redo

  • editor.execCommand("redo");

恢复操作

autoTypeset

  • editor.execCommand("autoTypeset");

对整个编辑文档进行自动排版

insertHtml

  • editor.execCommand("insertHtml","欢迎使用UEditor!")

在当前选区位置插入一段html代码,最基本功能。大部分其他插入命令都会调用此命令完成最后的插入

  • editor.execCommand("link",linkObj);

在当前选区位置插入一个超链接

editor.execCommand("link",{
    href: "http://ueditor.baidu.com",         //超链地址,必选
    data_ue_src: "http://ueditor.baidu.com",  //UE内部使用参数,与href保持一致即可,可选
    target: "_self",                          //目标窗口,可选
    textValue: "UEditor",                     //链接显示文本,可选
    title: "百度开源富文本编辑器UEditor官网"     //标题,可选
})

insertImage

  • editor.execCommand("insertImage",imageObj);

在当前选区位置插入一个图片

editor.execCommand("insertImage",{
    src: "http://ueditor.baidu.com/logo.jpg",          //图片链接地址,必选
    data_ue_src: "http://ueditor.baidu.com/logo.jpg",  //UE内部使用参数,与src保持一致即可,可选
    width: 300,                                        //图片显示宽度,可选
    height: 400,                                       //图片显示高度,可选
    border: 2,                                         //图片边框,可选
    hspace: 5,                                         //图片左右边距,可选
    vspace: 2,                                         //图片上下边距,可选
    alt: 'UEditor-logo',                               //图片替换文字,可选
    title: "百度开源富文本编辑器UEditor官网"             //图片标题,可选
})

insertVideo

  • editor.execCommand("insertVideo",videoObj);

在当前选区位置插入一个视频

editor.execCommand("insertVideo",{
    url: "http://youku.com/id?id=1233122",   //视频地址,必选
    width: 420,                              //视频宽度,可选
    height: 280,                             //视频高度,可选
    align: "none"                            //对齐方式,支持right,left,center,none ,可选
})

date|time

  • editor.execCommand("date");

在当前选区位置插入一个日期或者时间

pageBreak

  • editor.execCommand("pageBreak");

在当前选区位置插入一个分页符标记

source

  • editor.execCommand("source");

切换源码编辑模式和富文本编辑模式

snapScreen

  • editor.execCommand("snapScreen");

IE下进入截屏模式

insertTable

  • editor.execCommand("insertTable",rows,cols);

插入表格

searchreplace

  • editor.execCommand("searchreplace",opt);

查找替换

opt是个json对象,属性如下

  • all true表示查找整个文档,false表示从上次的位置开始查找,默认是false
  • casesensitive 大小写铭感,true是铭感,默认是false
  • dir 1表示从前往后查,-1表示从后往前
  • searchStr 查找的字符串
  • replaceStr 替换用的字符串

GoTop