微信小程序开发 – 第 47 页 – 微信小程序开发指南

editor

基础库 2.7.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

渲染框架支持情况：WebView

功能描述

富文本编辑器，可以对图片、文字进行编辑。

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

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

富文本组件内部引入了一些基本的样式使得内容可以正确的展示，开发时可以进行覆盖。需要注意的是，在其它组件或环境中使用富文本组件导出的html时，需要额外引入这段样式，并维护<ql-container><ql-editor></ql-editor></ql-container>的结构。

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

属性说明

属性	类型	默认值	必填	说明	最低版本
read-only	boolean	false	否	设置编辑器为只读	2.7.0
placeholder	string		否	提示信息	2.7.0
show-img-size	boolean	false	否	点击图片时显示图片大小控件	2.7.0
show-img-toolbar	boolean	false	否	点击图片时显示工具栏控件	2.7.0
show-img-resize	boolean	false	否	点击图片时显示修改尺寸控件	2.7.0
enable-formats	Array.`<string>`	所有格式	否	编辑器允许的名单内的格式	3.2.2
enterkeyhint	string	enter	否	定义虚拟键盘回车键的操作标签	3.7.11
confirm-hold	boolean	true	否	点击键盘回车键时是否保持键盘不收起	3.7.11
bindready	eventhandle		否	编辑器初始化完成时触发	2.7.0
bindfocus	eventhandle		否	编辑器聚焦时触发，event.detail = {html, text, delta}	2.7.0
bindblur	eventhandle		否	编辑器失去焦点时触发，detail = {html, text, delta}	2.7.0
bindinput	eventhandle		否	编辑器内容改变时触发，detail = {html, text, delta}	2.7.0
bindstatuschange	eventhandle		否	通过 Context 方法改变编辑器内样式时触发，返回选区已设置的样式	2.7.0

编辑器内支持部分 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`

enable-formats 属性列表

可以通过该参数控制以下属性是否被禁用。请注意，不在以下名单内的格式将固定开启。

name	version
bold	3.2.2
italic	3.2.2
underline	3.2.2

Bug & Tip

tip: 使用 catchtouchend 绑定事件则不会使编辑器失去焦点(2.8.3)
tip: 插入的 html 中事件绑定会被移除
tip: formats 中的 color 属性会统一以 hex 格式返回
tip: 粘贴时仅纯文本内容会被拷贝进编辑器
tip: 插入 html 到编辑器内时，编辑器会删除一些不必要的标签，以保证内容的统一。例如xxx会改写为xxx
tip: 编辑器聚焦时页面会被上推，系统行为以保证编辑区可见

示例代码

在开发者工具中预览效果

checkbox-group

基础库 1.0.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

多项选择器，内部由多个 checkbox 组成。

属性说明

属性	类型	默认值	必填	说明	最低版本
bindchange	EventHandle		否	checkbox-group 中选中项发生改变时触发 change 事件，detail = {value:[选中的 checkbox 的 value 的数组]}	1.0.0

checkbox

基础库 1.0.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

多选项目。

属性说明

属性	类型	默认值	必填	说明	最低版本
value	string		否	checkbox标识，选中时触发checkbox-group的 change 事件，并携带 checkbox 的 value	1.0.0
disabled	boolean	false	否	是否禁用	1.0.0
checked	boolean	false	否	当前是否选中，可用来设置默认选中	1.0.0
color	string	#09BB07	否	checkbox的颜色，同css的color	1.0.0

示例代码

在开发者工具中预览效果

button

基础库 1.0.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

相关文档: 聊天工具模式

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

按钮。

通用属性

属性类型默认值必填说明最低版本

size string default 否按钮的大小 1.0.0

合法值	说明
default	默认大小
mini	小尺寸

type string default 否按钮的样式类型 1.0.0

合法值	说明
primary	绿色
default	白色
warn	红色

plain boolean false 否按钮是否镂空，背景色透明 1.0.0

disabled boolean false 否是否禁用 1.0.0

loading boolean false 否名称前是否带 loading 图标 1.0.0

form-type string 否用于 form 组件，点击分别会触发 form 组件的 submit/reset 事件 1.0.0

合法值	说明	最低版本
submit	提交表单
reset	重置表单
submitToGroup	转发文本到聊天	3.7.8

open-type string 否微信开放能力 1.1.0

合法值	说明	最低版本
contact	打开客服会话，如果用户在会话中点击消息卡片后返回微信小程序，可以从 bindcontact 回调中获得具体信息，具体说明。鸿蒙 OS 暂不支持	1.1.0
liveActivity	通过前端获取新的一次性订阅消息下发机制使用的 code	2.26.2
share	触发用户转发，使用前建议先阅读使用指引	1.2.0
getPhoneNumber	手机号快速验证，向用户申请，并在用户同意后，快速填写和验证手机，具体说明（微信小程序插件中不能使用）	1.2.0
getRealtimePhoneNumber	手机号实时验证，向用户申请，并在用户同意后，快速填写和实时验证手机号。具体说明（微信小程序插件中不能使用）	2.24.4
getUserInfo	获取用户信息，可以从bindgetuserinfo回调中获取到用户信息（微信小程序插件中不能使用）	1.3.0
launchApp	打开APP，可以通过app-parameter属性设定向APP传的参数具体说明	1.9.5
openSetting	打开授权设置页	2.0.7
feedback	打开“意见反馈”页面，用户可提交反馈内容并上传日志，开发者可以登录微信小程序管理后台后进入左侧菜单“客服反馈”页面获取到反馈内容	2.1.0
chooseAvatar	获取用户头像，可以从bindchooseavatar回调中获取到头像信息	2.21.2
agreePrivacyAuthorization	用户同意隐私协议按钮。用户点击一次此按钮后，所有已声明过的隐私接口可以正常调用。可通过 bindagreeprivacyauthorization 监听用户同意隐私协议事件。隐私合规开发指南详情可见《微信小程序隐私协议开发指南》	2.32.3

hover-class string button-hover 否指定按钮按下去的样式类。当 hover-class="none" 时，没有点击态效果 1.0.0

hover-stop-propagation boolean false 否指定是否阻止本节点的祖先节点出现点击态 1.5.0

hover-start-time number 20 否按住后多久出现点击态，单位毫秒 1.0.0

hover-stay-time number 70 否手指松开后点击态保留时间，单位毫秒 1.0.0

lang string en 否指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文。 1.3.0

合法值	说明
en	英文
zh_CN	简体中文
zh_TW	繁体中文

session-from string 否会话来源，open-type=”contact”时有效，长度不超过 1024 个字符 1.4.0

send-message-title string 当前标题否会话内消息卡片标题，open-type=”contact”时有效 1.5.0

send-message-path string 当前分享路径否会话内消息卡片点击跳转微信小程序路径，open-type=”contact”时有效 1.5.0

send-message-img string 截图否会话内消息卡片图片，open-type=”contact”时有效 1.5.0

app-parameter string 否打开 APP 时，向 APP 传递的参数，open-type=launchApp时有效 1.9.5

show-message-card boolean false 否是否显示会话内消息卡片，设置此参数为 true，用户进入客服会话会在右下角显示”可能要发送的微信小程序“提示，用户点击后可以快速发送微信小程序消息，open-type=”contact”时有效 1.5.0

phone-number-no-quota-toast boolean true 否当手机号快速验证或手机号实时验证额度用尽时，是否对用户展示“申请获取你的手机号，但该功能使用次数已达当前微信小程序上限，暂时无法使用”的提示，默认展示，open-type=”getPhoneNumber” 或 open-type=”getRealtimePhoneNumber” 时有效 3.0.1

need-show-entrance boolean true 否转发的文本消息是否要带微信小程序入口 3.7.8

entrance-path string ” 否从消息微信小程序入口打开微信小程序的路径，默认为聊天工具启动路径 3.7.8

bindgetuserinfo eventhandle 否用户点击该按钮时，会返回获取到的用户信息，回调的detail数据与wx.getUserInfo返回的一致，open-type=”getUserInfo”时有效 1.3.0

bindcontact eventhandle 否客服消息回调，open-type=”contact”时有效。 1.5.0

createliveactivity eventhandle 否新的一次性订阅消息下发机制回调，open-type=liveActivity时有效 2.26.2

bindgetphonenumber eventhandle 否手机号快速验证回调，open-type=getPhoneNumber时有效。提示：在触发 bindgetphonenumber 回调后应立即隐藏手机号按钮组件，或置为 disabled 状态，避免用户重复授权手机号产生额外费用。 1.2.0

bindgetrealtimephonenumber eventhandle 否手机号实时验证回调，open-type=getRealtimePhoneNumber 时有效。提示：在触发 bindgetrealtimephonenumber 回调后应立即隐藏手机号按钮组件，或置为 disabled 状态，避免用户重复授权手机号产生额外费用。 2.24.4

binderror eventhandle 否当使用开放能力时，发生错误的回调，open-type=launchApp时有效 1.9.5

bindopensetting eventhandle 否在打开授权设置页后回调，open-type=openSetting时有效 2.0.7

bindlaunchapp eventhandle 否打开 APP 成功的回调，open-type=launchApp时有效 2.4.4

bindchooseavatar eventhandle 否获取用户头像回调，open-type=chooseAvatar时有效 2.21.2

bindagreeprivacyauthorization eventhandle 否用户同意隐私协议事件回调，open-type=agreePrivacyAuthorization时有效（提示：如果使用 onNeedPrivacyAuthorization 接口，需要在 bindagreeprivacyauthorization 触发后再调用 resolve({ event: "agree", buttonId })） 2.32.3

Bug & Tip

tip: button-hover 默认为{background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}
tip: bindgetphonenumber 从1.2.0 开始支持，但是在1.5.3以下版本中无法使用wx.canIUse进行检测，建议使用基础库版本进行判断。
tip: 在bindgetphonenumber 等返回加密信息的回调中调用 wx.login 登录，可能会刷新登录态。此时服务器使用 code 换取的 sessionKey 不是加密时使用的 sessionKey，导致解密失败。建议开发者提前进行 login；或者在回调中先使用 checkSession 进行登录态检查，避免 login 刷新登录态。
tip: 从 2.21.2 起，对getPhoneNumber接口进行了安全升级，bindgetphonenumber 返回的信息中增加code参数，code是一个动态的令牌，开发者拿到code后需调用微信后台接口换取手机号。详情新版接口使用指南
tip: 从 2.1.0 起，button 可作为原生组件的子节点嵌入，以便在原生组件上使用 open-type 的能力。
tip: 目前设置了 form-type 的 button 只会对当前组件中的 form 有效。因而，将 button 封装在自定义组件中，而 form 在自定义组件外，将会使这个 button 的 form-type 失效。

发送文本到群示例代码

需结合 form 和 textarea 组件使用。 button 需要设置 form-type="submitToGroup"，此时点击按钮将会发送 textarea 的内容到聊天。

<form bind:submitToGroup="onSubmitToGroup">
    <textarea value="{{shareText}}" />
    <button
    form-type="submitToGroup"
    need-show-entrance="{{true}}"
    entrance-path=""
    ></button>
</form>

示例代码

在开发者工具中预览效果

text

基础库 1.0.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

文本。

内联文本只能用 text 组件，不能用 view，如 <text> foo <text>bar</text> </text>
新增 span 组件用于内联文本和图片，如  <image> </image> <text>bar</text>

通用属性

	属性	类型	默认值	必填	说明	最低版本
	selectable	boolean	false	否	文本是否可选 (已废弃)	1.1.0
	user-select	boolean	false	否	文本是否可选，该属性会使文本节点显示为 inline-block	2.12.1

Skyline 特有属性

属性

类型

默认值

必填

说明

overflow

string

visible

是

文本溢出处理

合法值	说明
clip	修剪文本
fade	淡出
ellipsis	显示省略号
visible	文本不截断

max-lines

number

是

限制文本最大行数

select-on-gesture

boolean

true

是

是否允许通过手势选择文本，关闭后通常可以结合 SelectionContext.selectRange 接口使用

WebView 特有属性

属性

类型

默认值

必填

说明

最低版本

space

string

否

显示连续空格

1.4.0

合法值	说明
ensp	中文字符空格一半大小
emsp	中文字符空格大小
nbsp	根据字体设置的空格大小

decode

boolean

false

否

是否解码

1.4.0

Bug & Tip

tip: decode可以解析的有   < > & ' &ensp; &emsp;
tip: 各个操作系统的空格标准并不一致。
tip:text 组件内只支持 text 嵌套。
tip: 除了文本节点以外的其他节点都无法长按选中。
bug: 基础库版本低于 2.1.0 时， text 组件内嵌的 text style 设置可能不会生效。

示例代码

在开发者工具中预览效果

微信小程序选择

基础库 3.6.4 开始支持，低版本需做兼容处理。

渲染框架支持情况：WebView

功能描述

局部文本选区。

属性说明

属性	类型	默认值	必填	说明	最低版本
disable-context-menu	boolean	false	否	是否隐藏客户端原生文本选区按钮	3.6.4
bindselectionchange	eventhandle		否	当选区发生变化时触发 selectionchange 事件 event.detail = { isCollapsed, selectedString, firstNodeId, firstOffset, lastNodeId, lastOffset, firstRangeRect }	3.6.4

Bug & Tip

tip: 长按选区在 wx-selection 内才可以触发 disable-context-menu 的效果
tip: text 和 rich-text 组件需要设置 user-select 为 true。
tip: firstNodeId 和 lastNodeId 需要 text 和 rich-text 组件设置 id。
tip: 超出 wx-selection 的情况下 firstOffset 和 lastOffset 为空。

示例代码

在开发者工具中预览效果

rich-text

基础库 1.4.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

富文本。

自基础库 2.33.0 版本开始支持（3.0.0 除外）。
遵循 skyline 的样式和布局规则，html tag 被映射成类似 text/span/view 节点，因此存在 text 嵌套问题。
不支持 td/tr 等表格布局 tag，也不支持 bdo/bdi 等文字排版 tag。建议完全使用 flex 等 skyline 支持的布局方式来创建富文本内容。
提供了可选的兼容布局模式选项 mode，但仍不保证与 WebView 表现 100% 一致。
在 2.33.0 基础库下，请尽可能避免为 html tag 使用 wx-rich-text 开头的类名。

通用属性

属性

类型

默认值

必填

说明

最低版本

nodes

array/string

[]

否

节点列表/HTML String

1.4.0

space

string

否

显示连续空格

2.4.1

合法值	说明
ensp	中文字符空格一半大小
emsp	中文字符空格大小
nbsp	根据字体设置的空格大小

user-select

boolean

false

否

文本是否可选，该属性会使节点显示为 block

2.24.0

Skyline 特有属性

属性类型默认值必填说明

mode string default 否布局兼容模式

合法值	说明
default	完全遵循 skyline 的默认行为，不对节点树进行任何更改。
compat	尽可能将 tag 映射为 `<view><span></span></view>` 的形式。通常最接近 webview 的表现。
aggressive	所有 tag 均被映射为形如 `<view><span></span></view>` 的形式。
inline-block	实验性的 inline-block 布局策略，但无法实现折行。
web	使用 webview 渲染富文本，基础库 3.6.0 开始支持。
web-static	使用 webview 截图的方式渲染富文本，基础库 3.7.7 开始支持。

nodes

现支持两种节点，通过type来区分，分别是元素节点和文本节点，默认是元素节点，在富文本区域里显示的HTML节点

元素节点：type = node

属性	说明	类型	必填	备注
name	标签名	string	是	支持部分受信任的 HTML 节点
attrs	属性	object	否	支持部分受信任的属性，遵循 Pascal 命名法
children	子节点列表	array	否	结构和 nodes 一致

文本节点：type = text

属性	说明	类型	必填	备注
text	文本	string	是	支持entities

受信任的HTML节点及属性

全局支持class和style属性，不支持id属性。

节点	属性
a
abbr
address
article
aside
b
bdi
bdo	dir
big
blockquote
br
caption
center
cite
code
col	span，width
colgroup	span，width
dd
del
div
dl
dt
em
fieldset
font
footer
h1
h2
h3
h4
h5
h6
header
hr
i
img	alt，src，height，width
ins
label
legend
li
mark
nav
ol	start，type
p
pre
q
rt
ruby
s
section
small
span
strong
sub
sup
table	width
tbody
td	colspan，height，rowspan，width
tfoot
th	colspan，height，rowspan，width
thead
tr	colspan，height，rowspan，width
tt
u
ul

Bug 与提示

tip: nodes 不推荐使用 String 类型，性能会有所下降。
tip: rich-text 组件内屏蔽所有节点的事件。
tip: attrs 属性不支持 id ，支持 class 。
tip: name 属性大小写不敏感。
tip: 如果使用了不受信任的HTML节点，该节点及其所有子节点将会被移除。
tip: img 标签仅支持网络图片。
tip: 如果在自定义组件中使用 rich-text 组件，那么仅自定义组件的 wxss 样式对 rich-text 中的 class 生效。

示例代码

在开发者工具中预览效果

progress

基础库 1.0.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

渲染框架支持情况：WebView

功能描述

进度条。组件属性的长度单位默认为px，2.4.0起支持传入单位(rpx/px)。

属性说明

属性	类型	默认值	必填	说明	最低版本
percent	number		否	百分比0~100	1.0.0
show-info	boolean	false	否	在进度条右侧显示百分比	1.0.0
border-radius	number/string	0	否	圆角大小	2.3.1
font-size	number/string	16	否	右侧百分比字体大小	2.3.1
stroke-width	number/string	6	否	进度条线的宽度	1.0.0
color	string	#09BB07	否	进度条颜色（请使用activeColor）	1.0.0
activeColor	string	#09BB07	否	已选择的进度条的颜色	1.0.0
backgroundColor	string	#EBEBEB	否	未选择的进度条的颜色	1.0.0
active	boolean	false	否	进度条从左往右的动画	1.0.0
active-mode	string	backwards	否	backwards: 动画从头播；forwards：动画从上次结束点接着播	1.7.0
duration	number	30	否	进度增加1%所需毫秒数	2.8.2
bindactiveend	eventhandle		否	动画完成事件	2.4.1

示例代码

在开发者工具中预览效果

icon

基础库 1.0.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

渲染框架支持情况：WebView

功能描述

图标组件

属性说明

属性	类型	默认值	必填	说明	最低版本
type	string		是	icon的类型，有效值：success, success_no_circle, info, warn, waiting, cancel, download, search, clear	1.0.0
size	number/string	23	否	icon的大小，单位默认为px，2.4.0起支持传入单位(rpx/px)，2.21.3起支持传入其余单位(rem 等)。	1.0.0
color	string		否	icon的颜色，同css的color	1.0.0

示例代码

在开发者工具中预览效果

view

基础库 1.0.0 开始支持，低版本需做兼容处理。

微信 Windows 版：支持

微信 Mac 版：支持

微信鸿蒙 OS 版：支持

渲染框架支持情况：Skyline （使用最新 Nightly 工具调试）、WebView

功能描述

视图容器

属性说明

属性	类型	默认值	必填	说明	最低版本
hover-class	string	none	否	指定按下去的样式类。当 `hover-class="none"` 时，没有点击态效果	1.0.0
hover-stop-propagation	boolean	false	否	指定是否阻止本节点的祖先节点出现点击态	1.5.0
hover-start-time	number	50	否	按住后多久出现点击态，单位毫秒	1.0.0
hover-stay-time	number	400	否	手指松开后点击态保留时间，单位毫秒	1.0.0

Bug & Tip

tip: 如果需要使用滚动视图，请使用 scroll-view

示例代码

在开发者工具中预览效果