Editor 富文本编辑器

# 介绍

Editor 富文本编辑器动态库提供了支持富文本编辑的editor组件和操作editor组件的createEditorContext方法,通过使用该动态库,用户可以对图片、文本进行编辑。编辑器导出内容支持带标签的html和纯文本的text,编辑器内部采用delta格式进行存储。

富文本编辑器组件中设置了一些基本样式使得内容可以正确展示,在开发过程中可以进行覆盖,在其他组件或者环境中使用富文本编辑器导出的html时,需要额外维护以下DOM结构:

<ql-container>
    <ql-editor></ql-editor>
</ql-container>

# 使用方法

# 1. 在项目中引用动态库

参考使用动态库中提供的方法,在 app.json 中增添一项 dynamicLib,与 pages 同级。

"dynamicLib": {
    "editorLib": {
        "provider": "swan-editor"
    }
},

# 2. 在使用到富文本编辑器组件的页面配置动态库

在每个使用到富文本编辑器组件的页面,配置 *.json 文件如:

{
    "usingSwanComponents": {
        "editor": "dynamicLib://editorLib/editor"
    }
}

# 3. 编写 *.swan 文件

<editor
    read-only="{{readOnly}}"
    placeholder="{{placeholder}}"
/>

这是一种最基本的使用方式,其中readOnlyplaceholder的值可以在 *.js 文件中设置。

Page({
    data: {
        readOnly: false,
        placeholder: '请输入...'
    }
});

# Editor 组件属性列表

属性 类型 默认值 必填 说明
read-only Boolean false 设置编辑器为只读
placeholder String 编辑器提示信息
show-img-size Boolean false 点击图片时显示图片大小控件
show-img-resize Boolean false 点击图片时显示图片缩放控件
show-img-toolbar Boolean false 点击图片时显示图片工具栏控件
bindready EventHandle 编辑器初始化完成时触发
bindfocus EventHandle 编辑器聚焦时触发,event.detail = { html, text, delta }
bindblur EventHandle 编辑器失去焦点时触发,event.detail = { html, text, delta }
bindinput EventHandle 编辑器内容改变时触发,event.detail = { html, text, delta }
bindstatuschange EventHandle 编辑器内容或样式通过EditorContext中的方法改变时触发,返回选区已设置的样式

编辑器内支持部分HTML标签和内联样式,但不支持classid

# 支持的标签

不满足的标签会被忽略,div标签会被转换为p标签存储。

类型 节点
行内元素 <span> <strong> <b> <em> <i> <u> <a> <s> <sub> <sup> <img>
块级元素 <br> <hr> <ol> <ul> <li> <h1> <h2> <h3> <h4> <h5> <h6>

# 支持的内联样式

内联样式仅支持设置在行内元素或块级元素上,不能同时设置,如 text-align 归类为块级样式,在 span 标签上设置是无效的。

类型 样式
块级样式 text-align direction
行内样式 color background-color

# EditorContext 实例

Editor 富文本编辑器动态库提供了 createEditorContext 的方法来获取某个 editor 组件的实例,EditorContext 通过 id 和 一个 editor 组件绑定,操作对应的 editor 组件。

# 使用方法

Page({
    onEditorReady() {
        this.editorCtx = requireDynamicLib('editorLib').createEditorContext('editorId');
    }
});

# EditorContext.blur(Objec object)

解释: 编辑器失焦

参数: Object object

属性 类型 默认值 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

# EditorContext.clear(Objec object)

解释: 清空编辑器内容

参数: Object object

属性 类型 默认值 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

# EditorContext.format(string name, string value)

解释: 修改格式

对已经应用样式的选区设置会取消样式。

参数

string name: 属性

string value: 值

支持设置的样式列表

name value
bold
italic
underline
strike
ins
script sub / super
header H1 / H2 / H3 / H4 / H5 / H6
align center / right / justify
direction rtl
indent -1 / +1
list ordered / bullet / check
color hex color
backgroudColor hex color

# EditorContext.getContents(Objec object)

解释: 获取编辑器内容

参数: Object object

属性 类型 默认值 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

object.success 回调函数

参数: Object res

属性 类型 说明
html String 带标签的html内容
text String 纯文本内容
delta Object 描述内容的delta对象

# EditorContext.getSelectionText(Objec object)

解释: 获取编辑器内选区的纯文本内容。当编辑器失焦或未选中一段区间时,返回内容为空

参数: Object object

属性 类型 默认值 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

object.success 回调函数

参数: Object res

属性 类型 说明
text String 纯文本内容

# EditorContext.insertDivider(Objec object)

解释: 插入分隔符

参数: Object object

属性 类型 默认值 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

# EditorContext.insertImage(Objec object)

解释: 插入图片

参数: Object object

属性 类型 默认值 必填 说明
src String 图片地址,目前仅支持 http(s)、base64、本地图片
alt String 图片无法显示时的替代文本
extClass String 添加到图片 img 标签上的类名
data Object data 会被序列化为 name1=value1&name2=value2 的格式挂在属性 data-custom 上
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

# EditorContext.insertText(Objec object)

解释: 覆盖当前选区,设置一段文本

参数: Object object

属性 类型 默认值 必填 说明
text String 文本内容
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

# EditorContext.removeFormat(Objec object)

解释: 清除当前选区的样式

参数: Object object

属性 类型 默认值 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

# EditorContext.setContents(Objec object)

解释: 初始化编辑器内容,htmldelta同时存在时仅delta生效

需要注意的是,通过setContents设置编辑器内容时,由于支持的html标签和内联样式有限,建议开发者在小程序内通过delta进行插入。

参数: Object object

属性 类型 默认值 必填 说明
html String 带标签的html内容
delta Object 描述内容的delta对象
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

# EditorContext.scrollIntoView()

解释: 将编辑器光标处滚动到窗口可视区域内

# EditorContext.redo(Objec object)

解释: 恢复

参数: Object object

属性 类型 默认值 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)

# EditorContext.undo(Objec object)

解释: 撤销

参数: Object object

属性 类型 默认值 必填 说明
success Function 接口调用成功的回调函数
fail Function 接口调用失败的回调函数
complete Function 接口调用结束的回调函数(调用成功、失败都会执行)