# editor

富文本编辑器，可以对图片、文字格式进行编辑和混排。

在 web 开发时，可以使用contenteditable来实现内容编辑。但这是一个 dom API，在非 H5 平台无法使用。于是小程序提供了editor组件来实现这个功能.

注意:

因编辑功能的底层依赖较大，为了避免影响正常的包体积，选择了动态配置，故如果项目中需要使用editor组件，则需要在 pages.json 下新增配置如下

// pages.json
{
    "buildExtra": {
		"template": "quill"
	},
	...
}

1
2
3
4
5
6
7

编辑器导出内容支持带标签的 html和纯文本的 text，编辑器内部采用 delta 格式进行存储。

通过setContents接口设置内容时，解析插入的 html 可能会由于一些非法标签导致解析错误，建议开发者在应用内使用时通过 delta 进行插入。

富文本组件内部引入了一些基本的样式使得内容可以正确的展示，开发时可以进行覆盖。

图片控件仅初始化时设置有效。

# 属性说明

属性	类型	默认值	必填	说明
read-only	boolean	false	否	设置编辑器为只读
placeholder	string		否	提示信息
show-img-size	boolean	false	否	点击图片时显示图片大小控件
show-img-toolbar	boolean	false	否	点击图片时显示工具栏控件
show-img-resize	boolean	false	否	点击图片时显示修改尺寸控件
@ready	eventhandle		否	编辑器初始化完成时触发
@focus	eventhandle		否	编辑器聚焦时触发，event.detail = {html, text, delta}
@blur	eventhandle		否	编辑器失去焦点时触发，detail = {html, text, delta}
@input	eventhandle		否	编辑器内容改变时触发，detail = {html, text, delta}
@statuschange	eventhandle		否	通过 Context 方法改变编辑器内样式时触发，返回选区已设置的样式

编辑器内支持部分 HTML 标签和内联样式，不支持class和id

# 支持的标签

不满足的标签会被忽略，<div>会被转行为储存。

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

# 支持的内联样式

内联样式仅能设置在行内元素或块级元素上，不能同时设置。例如 font-size 归类为行内元素属性，在 p 标签上设置是无效的。

类型	样式
块级样式	`text-align` `direction` `margin` `margin-top` `margin-left` `margin-right` `margin-bottom` `padding` `padding-top` `padding-left` `padding-right` `padding-bottom` `line-height` `text-indent`
行内样式	`font` `font-size` `font-style` `font-variant` `font-weight` `font-family` `letter-spacing` `text-decoration` `color` `background-color`

注意事项

插入的 html 中事件绑定会被移除
formats 中的 color 属性会统一以 hex 格式返回
粘贴时仅纯文本内容会被拷贝进编辑器
插入 html 到编辑器内时，编辑器会删除一些不必要的标签，以保证内容的统一。例如xxx会改写为xxx
编辑器聚焦时页面会被上推，系统行为以保证编辑区可见
不能直接插入视频，编辑时可以采用视频封面占位，并在图片属性中保存视频信息，预览时再还原为视频。

# 示例代码

<template>
    <view class="container">
        <editor
            id="editor"
            class="ql-container"
            :placeholder="placeholder"
            @ready="onEditorReady"
        ></editor>
        <button type="warn">撤销</button>
    </view>
</template>

1
2
3
4
5
6
7
8
9
10
11

# editorContext 编辑器实例

editor 组件对应的 editorContext 实例，可通过 **bz.createSelectorQuery** 获取。

onEditorReady() {
		bz.createSelectorQuery().select('#editor').context((res) => {
			this.editorCtx = res.context
		}).exec()
}

1
2
3
4
5

# insertDivider() 插入分割线

editorContext.insertDivider(OBJECT)，在当前选区/光标位置，插入分割线

OBJECT 参数说明

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

# insertImage() 插入图片

editorContext.insertImage(OBJECT)，在当前选区/光标位置，插入图片。

OBJECT 参数说明

属性	类型	必填	说明
src	String	是	图片地址，仅支持 http(s)、base64、本地图片
alt	String	否	图像无法显示时的替代文本
width	String	否	图片宽度（pixels/百分比）
height	String	否	图片高度 (pixels/百分比）
extClass	String	否	添加到图片 img 标签上的类名
data	Object	否	data 被序列化为 name=value;name1=value2 的格式挂在属性 data-custom 上
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

# insertText() 设置一段文本

editorContext.insertText(OBJECT), 覆盖当前选区/光标位置，设置一段文本

OBJECT 参数说明

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

# setContents() 设置全内容

editorContext.setContents(OBJECT), 初始化编辑器内容，html 和 delta 同时存在时仅 delta 生效

OBJECT 参数说明

属性	类型	必填	说明
html	String	否	带标签的 HTML 内容
delta	Object	否	表示内容的 delta 对象
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

# getContents() 获取内容

editorContext.getContents(OBJECT) , 获取编辑器内容

OBJECT 参数说明

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

object.success 回调函数

属性	类型	说明
html	string	带标签的 HTML 内容
text	string	纯文本内容
delta	Object	表示内容的 delta 对象

# getSelectionText() 获取纯文本内容

editorContext.getSelectionText(OBJECT), 获取编辑器已选区域内的纯文本内容。当编辑器失焦或未选中一段区间时，返回内容为空。

OBJECT 参数说明

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

success 返回参数说明：

参数	类型	说明
errMsg	String	接口调用结果
text	String	纯文本内容

# clear() 清空内容

editorContext.clear(OBJECT), 清空编辑器内容

OBJECT 参数说明

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

# format() 修改选区样式

editorContext.format(name, value) 修改当前选区样式

参数	类型	说明
name	String	属性
value	String	值

支持设置的样式列表

name	value
bold
italic
underline
strike
ins
script	sub / super
header	H1 / H2 / h3 / H4 / h5 / H6
align	left / center / right / justify
direction	rtl
indent	-1 / +1
list	ordered / bullet / check
color	hex color
backgroundColor	hex color
margin/marginTop/marginBottom/marginLeft/marginRight	css style
padding/paddingTop/paddingBottom/paddingLeft/paddingRight	css style
font/fontSize/fontStyle/fontVariant/fontWeight/fontFamily	css style
lineHeight	css style
letterSpacing	css style
textDecoration	css style
textIndent	css style
wordWrap	css style
wordBreak	css style
whiteSpace	css style

注意：对已经应用样式的选区设置会取消样式。css style 表示 css 中规定的允许值。

# removeFormat() 移除样式

editorContext.removeFormat(OBJECT), 清除当前选区的样式

OBJECT 参数说明

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

# undo() 撤销

editorContext.undo(OBJECT), 撤销

OBJECT 参数说明

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

# redo() 恢复

editorContext.redo(OBJECT), 恢复

OBJECT 参数说明

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

# blur() 主动失焦

editorContext.blur(OBJECT), 编辑器失焦，同时收起键盘。

OBJECT 参数说明

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

# scrollIntoView() 滚动到可视区

editorContext.scrollIntoView(OBJECT), 使得编辑器光标处滚动到窗口可视区域内。

OBJECT 参数说明

属性	类型	必填	说明
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

← label picker-view →