component.md

组件使用与开发 {#component-usage-development}

本节提供 Mpx RN 环境下的组件支持说明，详细列出了支持的基础组件及其可用属性、方法，以及自定义组件的相关配置。

目录概览 {#directory-overview}

• 基础组件

容器组件：view · scroll-view · swiper · swiper-item · movable-area · movable-view · page-container · root-portal · sticky-section · sticky-header · cover-view

媒体组件：image · video · canvas

表单组件：input · textarea · button · checkbox · checkbox-group · radio · radio-group · switch · picker · picker-view · picker-view-column · form · label

基础组件：text · icon · progress · navigator · rich-text · cover-image

其他组件：web-view

• 自定义组件

组件属性配置 · 生命周期钩子 · 实例属性和方法

使用原则 {#usage-principles}

[!important] 重要说明

• 支持范围：仅支持文档中明确列出的组件和属性
• 平台特性：某些属性和功能仅在 RN 环境下可用
• 性能考量：按需开启高级功能，避免不必要的性能开销

基础组件 {#basic-components}

目前 Mpx 输出 React Native 仅支持以下组件，文档中未提及的组件以及组件属性即为不支持，具体使用范围可参考如下文档

基础组件通用属性 {#basic-component-common-props}

属性名	类型	默认值	说明
enable-offset	boolean	false	设置是否要获取组件的布局信息，若设置了该属性，会在 e.target 中返回组件的 offsetLeft、offsetWidth 信息
enable-var	boolean	true	默认支持使用 css variable，若想关闭该功能可设置为 false
parent-font-size	number		父组件字体大小，主要用于百分比计算的场景，如 font-size: 100%
parent-width	number		父组件宽度，主要用于百分比计算的场景，如 width: calc(100% - 20px)，需要在外部传递父组件的宽度
parent-height	number		父组件高度，主要用于百分比计算的场景，如 height: calc(100% - 20px),需要在外部传递父组件的高度

以上基础组件的通用属性仅在 React Native 环境中支持。在跨平台输出到小程序或 Web 时，这些属性将无法使用。

由于 view、text、scroll-view、image 和 input 组件都是基于 React Native 原生组件实现的，因此这些组件默认继承原生组件支持的属性。

view

视图容器。 属性

属性名	类型	默认值	说明
hover-class	string		指定按下去的样式类。
hover-start-time	number	50	按住后多久出现点击态，单位毫秒
hover-stay-time	number	400	手指松开后点击态保留时间，单位毫秒
animation	object		传递动画的实例， 可配合mpx.createAnimation方法一起使用
enable-background	boolean	false	RN环境特有属性，是否要开启background-image、background-size和background-position的相关计算或渲染，请根据实际情况开启
enable-animation	boolean	false	RN环境特有属性，开启要开启动画渲染，请根据实际情况开启
enable-fast-image	boolean	false	RN环境特有属性，开启后将使用 react-native-fast-image 进行图片渲染，请根据实际情况开启
is-simple	-	-	RN环境特有标记，设置后将使用简单版本的 view 组件渲染，该组件不包含 css var、calc、ref 等拓展功能，但性能更优，请根据实际情况设置

事件

事件名	说明
bindtransitionend	动画结束时触发,event.detail = { elapsedTime, finished, current }

[!tip] 注意

• 如果从未使用背景图、动图或动画，请不要开启enable-background、enable-animation或enable-fast-image属性，会有一定的性能消耗。
• 若开启enable-background需要给当前 view 组件设置一个唯一 key。
• background-image、background-size、background-position 等背景图相关 css 属性，仅 view 组件支持
• 出于性能考虑，基础组件的样式增强能力（如 enable-var、enable-background、enable-animation）采用按需启用策略。view 组件仅在首次渲染时检测样式并决定是否开启对应能力。由于 React Hooks 的一致性约束，增强能力无法在后续更新阶段再动态启用，因此当组件生命周期内可能使用相关能力时，需在首次渲染时显式声明启用，比如 enable-animation="{{ true }}"。

text

文本。

属性

属性名	类型	默认值	说明
user-select	boolean	false	文本是否可选。
selectable	boolean	false	文本是否可选。该属性已废弃，请使用 user-select
decode	boolean	false	是否解码
is-simple	-	-	RN环境特有标记，设置后将使用简单版本的 text 组件渲染，该组件不包含 css var、calc、ref 等拓展功能，但性能更优，请根据实际情况设置

[!tip] 注意

• 未包裹 text 标签的文本，会自动包裹 text 标签。
• text 组件开启 enable-offset 后，offsetLeft、offsetWidth 获取时机仅为组件首次渲染阶段

scroll-view

可滚动视图区域。

属性

属性名	类型	默认值	说明
scroll-x	boolean	false	允许横向滚动
scroll-y	boolean	false	允许纵向滚动
upper-threshold	number	50	距顶部/左边多远时(单位 px),触发 scrolltoupper 事件
lower-threshold	number	50	距底部/右边多远时(单位 px),触发 scrolltolower 事件
scroll-top	number	0	设置纵向滚动条位置
scroll-left	number	0	设置横向滚动条位置
scroll-with-animation	boolean	false	在设置滚动条位置时使用动画过渡
enable-back-to-top	boolean	false	点击状态栏的时候视图会滚动到顶部，仅 iOS环境支持
enhanced	boolean	false	scroll-view 组件功能增强
bounces	boolean	true	iOS 下 scroll-view 边界弹性控制 (同时开启 enhanced 属性后生效)
refresher-enabled	boolean	false	开启自定义下拉刷新，iOS 下需要把 enhanced 和 bounces 都设置为 true
refresher-threshold	number	45	设置自定义下拉刷新阈值
scroll-into-view	boolean	false	值应为某子元素id（id不能以数字开头）
scroll-into-view-offset	number	0	跳转到 scroll-into-view 目标节点时的额外偏移
refresher-default-style	string	'black'	设置下拉刷新默认样式,支持 black、white、none，仅安卓支持
refresher-background	string	'#fff'	设置自定义下拉刷新背景颜色，仅安卓支持
refresher-triggered	boolean	false	设置当前下拉刷新状态,true 表示已触发
paging-enabled	number	false	分页滑动效果 (同时开启 enhanced 属性后生效)，当值为 true 时，滚动条会停在滚动视图的尺寸的整数倍位置
show-scrollbar	number	true	滚动条显隐控制 (同时开启 enhanced 属性后生效)
enable-trigger-intersection-observer	boolean	false	RN环境特有属性，是否开启intersection-observer
simultaneous-handlers	array<object>	[]	RN环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 scroll-view 组件
wait-for	array<object>	[]	RN环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 scroll-view 组件
scroll-event-throttle	number	0	RN环境特有属性，控制 scroll 事件触发频率
enable-sticky	boolean	false	RN环境特有属性，当使用 sticky 组件时，需要手动将此属性设置为 true

事件

事件名	说明
binddragstart	滑动开始事件，同时开启 enhanced 属性后生效
binddragging	滑动事件，同时开启 enhanced 属性后生效
binddragend	滑动结束事件，同时开启 enhanced 属性后生效
bindscrolltoupper	滚动到顶部/左边触发
bindscrolltolower	滚动到底部/右边触发
bindscroll	滚动时触发
bindscrollend	滚动结束时触发
bindrefresherrefresh	自定义下拉刷新被触发

[!tip] 注意

• 若使用 scroll-into-view 属性，需要 id 对应的组件节点添加 wx:ref 标记，否则无法正常滚动。另外组件节点需要是内置基础组件，自定义组件暂不支持。
• simultaneous-handlers 为 RN 环境特有属性，具体含义可参考react-native-gesture-handler
• wait-for 为 RN 环境特有属性，具体含义可参考react-native-gesture-handler
• scroll-view 组件在滚动过程中，不会触发其自身或子组件的 touchend 事件响应，这是 RN 底层实现导致的问题，手势系统识别当前是 scroll-view 的滚动，就会取消掉 touchend 事件的响应。
• 安卓上如果触发了 scroll-view 组件默认的下拉刷新，binddragend可能不触发，只会触发 binddragstart

swiper

滑块视图容器。

属性

属性名	类型	默认值	说明
indicator-dots	boolean	false	是否显示面板指示点
indicator-color	color	rgba(0, 0, 0, .3)	指示点颜色
indicator-active-color	color	#000000	当前选中的指示点颜色
indicator-width	number		指示点宽度
indicator-height	number		指示点高度
indicator-spacing	number		指示点间距
indicator-radius	number		指示点圆角
indicator-margin	number		指示点外边距
autoplay	boolean	false	是否自动切换
current	number	0	当前所在滑块的 index
interval	number	5000	自动切换时间间隔
duration	number	500	滑动动画时长
circular	boolean	false	是否采用衔接滑动
vertical	boolean	false	滑动方向是否为纵向
previous-margin	string	0	前边距，可用于露出前一项的一小部分，接受px
next-margin	string	0	后边距，可用于露出后一项的一小部分，接受px
scale	boolean	false	滑动时是否开启前后元素缩小,默认是缩放0.7倍, 暂不支持自定义
easing-function	string	linear	支持 linear、easeInCubic、easeOutCubic、easeInOutCubic
simultaneous-handlers	array<object>	[]	RN环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 swiper 组件
wait-for	array<object>	[]	RN环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 swiper 组件
disableGesture	boolean	false	RN 环境特有属性，禁用 swiper 滑动手势。若开启用户无法通过手势滑动 swiper，只能通过开启 autoPlay 进行自动轮播

事件

事件名	说明
bindchange	current 改变时会触发 change 事件，event.detail = {current, source}

swiper-item

仅可放置在swiper组件中，宽高自动设置为100%。

属性

属性名	类型	默认值	说明
item-id	string		该 swiper-item 的标识符

movable-area

movable-view的可移动区域。

movable-view

可移动的视图容器，在页面中可以拖拽滑动。movable-view 必须在 movable-area 组件中，并且必须是直接子节点，否则不能移动。

属性

属性名	类型	默认值	说明
direction	string	none	目前支持 all、vertical、horizontal、none
inertia	boolean	false	movable-view是否带有惯性
out-of-bounds	boolean	false	超过可移动区域后，movable-view是否还可以移动
x	number		定义x轴方向的偏移
y	number		定义y轴方向的偏移
disabled	boolean	false	是否禁用
animation	boolean	true	是否使用动画
damping	number	20	阻尼系数，用于控制x或y改变时的动画和过界回弹的动画，值越大移动越快
friction	number	2	摩擦系数，用于控制惯性滑动的动画，值越大摩擦力越大，滑动越快停止
simultaneous-handlers	array<object>	[]	RN 环境特有属性，主要用于组件嵌套场景，允许多个手势同时识别和处理并触发，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 movable-view 组件
wait-for	array<object>	[]	RN 环境特有属性，主要用于组件嵌套场景，允许延迟激活处理某些手势，这个属性可以指定一个或多个手势处理器，处理器支持使用 this.$refs.xxx 获取组件实例来作为数组参数传递给 movable-view 组件
disable-event-passthrough	boolean	false	RN 环境特有属性，有时候我们希望movable-view 在水平方向滑动，并且竖直方向的手势也希望被 movable-view 组件消费掉，不被其他组件响应，可以将这个属性设置为true）

事件

事件名	说明
bindchange	拖动过程中触发的事件，event.detail = {x, y, source}
htouchmove	初次手指触摸后移动为横向的移动时触发
vtouchmove	初次手指触摸后移动为纵向的移动时触发

[!tip] 注意

• simultaneous-handlers 为 RN 环境特有属性，具体含义可参考react-native-gesture-handler
• wait-for 为 RN 环境特有属性，具体含义可参考react-native-gesture-handler
• RN 环境 movable 相关组件暂不支持缩放能力

image

图片组件

属性

属性名	类型	默认值	说明
src	string	false	图片资源地址及 base64 格式数据
mode	string	scaleToFill	图片裁剪、缩放的模式，可选值为 scaleToFill、aspectFit、aspectFill、widthFix、heightFix、top、bottom、center、left、right、top left、top right、bottom left、bottom right
enable-fast-image	boolean	false	RN环境特有属性，开启后将使用 react-native-fast-image 进行图片渲染，请根据实际情况开启

事件

事件名	说明
binderror	当错误发生时触发，event.detail = { errMsg }
bindload	当图片载入完毕时触发，event.detail = { height, width }

[!tip] 注意

• image 组件默认宽度320px、高度240px
• image 组件进行缩放时，计算出来的宽高可能带有小数，在不同 webview 内核下渲染可能会被抹去小数部分

icon

图标组件

属性

属性名	类型	默认值	说明
type	string		icon 的类型，有效值：success、success_no_circle、info、warn、waiting、cancel、download、search、clear
size	string|number	23	icon 的大小
color	string		icon 的颜色，同 css 的 color

button

按钮。

属性

属性名	类型	默认值	说明
size	string	default	按钮的大小，default：默认大小，mini：小尺寸
type	string	default	按钮的样式类型，primary：绿色，default：白色，warn：红色
plain	boolean	false	按钮是否镂空，背景色透明
disabled	boolean	false	是否禁用
loading	boolean	false	名称前是否带 loading 图标
form-type	string		用于 form 组件，点击分别会触发 form 组件的 submit/reset 事件，有效值为 submit、reset
open-type	string		微信开放能力，当前仅支持 share 和 getUserInfo
hover-class	string		指定按钮按下去的样式类。当 hover-class="none" 时，没有点击态效果
hover-start-time	number	20	按住后多久出现点击态，单位毫秒
hover-stay-time	number	70	手指松开后点击态保留时间，单位毫秒

[!tip] 注意

• openType 需要在 mpx.config.rnConfig 中注册对应能力如 onShareAppMessage，onUserInfo 来配合使用。

label

用来改进表单组件的可用性

[!tip] 注意

• 当前不支持使用 for 属性找到对应 id，仅支持将控件放在该标签内，目前可以绑定的空间有：checkbox、radio、switch。

checkbox

多选项目

属性

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

checkbox-group

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

事件

事件名	说明
bindchange	checkbox-group 中选中项发生改变时触发 change 事件，detail = { value: [ 选中的 checkbox 的 value 的数组 ] }

radio

单选项目

属性

属性名	类型	默认值	说明
value	string		radio 标识，当该 radio 选中时，radio-group 的 change 事件会携带 radio 的 value
disabled	boolean	false	是否禁用
checked	boolean	false	当前是否选中，可用来设置默认选中
color	string	#09BB07	checkbox 的颜色，同 css 的 color

radio-group

单项选择器，内部由多个 radio 组成

事件

事件名	说明
bindchange	radio-group 中选中项发生改变时触发 change 事件，detail = { value: [ 选中的 radio 的 value 的数组 ] }

form

表单。

当点击 form 表单中 form-type 为 submit 的 button 组件时，会将表单组件中的 value 值进行提交，需要在表单组件中加上 name 来作为 key。

事件

事件名	说明
bindsubmit	携带 form 中的数据触发 submit 事件，event.detail = {value : {'name': 'value'} }
bindreset	表单重置时会触发 reset 事件

input

输入框。

属性

属性名	类型	默认值	说明
value	string		输入框的初始内容
type	string	text	input 的类型，可选值为 text、number、idcard、digit，不支持 safe-password、nickname
password	boolean	false	是否是密码类型
placeholder	string		输入框为空时占位符
placeholder-class	string		指定 placeholder 的样式类，仅支持 color 属性
placeholder-style	string		指定 placeholder 的样式，仅支持 color 属性
disabled	boolean	false	是否禁用
maxlength	number	140	最大输入长度，设置为 -1 的时候不限制最大长度
cursor-spacing	number	0	指定光标与键盘的距离，单位 px。取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离
auto-focus	boolean	false	(即将废弃，请直接使用 focus )自动聚焦，拉起键盘
focus	boolean	false	获取焦点
confirm-type	string	done	设置键盘右下角按钮的文字，仅在 type='text' 时生效，可选值为 send、search、next、go、done、return
confirm-hold	boolean	false	点击键盘右下角按钮时是否保持键盘不收起
hold-keyboard	boolean	false	输入框聚焦时，点击页面其他地方是否收起键盘
cursor	number		指定 focus 时的光标位置
cursor-color	string		光标颜色
selection-start	number	-1	光标起始位置，自动聚集时有效，需与 selection-end 搭配使用
selection-end	number	-1	光标结束位置，自动聚集时有效，需与 selection-start 搭配使用
adjust-position	boolean	true	键盘弹起时，是否自动上推页面
keyboard-type	string		RN环境特有属性，设置键盘类型

事件

事件名	说明
bindinput	键盘输入时触发，event.detail = { value, cursor }，不支持 keyCode
bindfocus	输入框聚焦时触发，event.detail = { value }，不支持 height
bindblur	输入框失去焦点时触发，event.detail = { value }，不支持 encryptedValue、encryptError
bindconfirm	点击完成按钮时触发，event.detail = { value }
bind:selectionchange	选区改变事件, event.detail = { selectionStart, selectionEnd }

textarea

多行输入框。

属性

属性名	类型	默认值	说明
value	string		输入框内容
placeholder	string		输入框为空时占位符
placeholder-class	string		指定 placeholder 的样式类，仅支持 color 属性
placeholder-style	string		指定 placeholder 的样式，仅支持 color 属性
disabled	boolean	false	是否禁用
maxlength	number	140	最大输入长度，设置为 -1 的时候不限制最大长度
cursor-spacing	number	0	指定光标与键盘的距离，单位 px。取 textarea 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离
auto-focus	boolean	false	(即将废弃，请直接使用 focus )自动聚焦，拉起键盘
focus	boolean	false	获取焦点
auto-height	boolean	false	是否自动增高，设置 auto-height 时，style.height不生效
confirm-type	string	return	设置键盘右下角按钮的文字，可选值为 send、search、next、go、done、return
confirm-hold	boolean	false	点击键盘右下角按钮时是否保持键盘不收起
hold-keyboard	boolean	false	输入框聚焦时，点击页面其他地方是否收起键盘
cursor	number		指定 focus 时的光标位置
cursor-color	string		光标颜色
selection-start	number	-1	光标起始位置，自动聚集时有效，需与 selection-end 搭配使用
selection-end	number	-1	光标结束位置，自动聚集时有效，需与 selection-start 搭配使用
adjust-position	boolean	true	键盘弹起时，是否自动上推页面
keyboard-type	string		RN环境特有属性，设置键盘类型

事件

事件名	说明
bindinput	键盘输入时触发，event.detail = { value, cursor }，不支持 keyCode
bindfocus	输入框聚焦时触发，event.detail = { value }，不支持 height
bindblur	输入框失去焦点时触发，event.detail = { value }，不支持 encryptedValue、encryptError
bindconfirm	点击完成按钮时触发，event.detail = { value }
bindlinechange	输入框行数变化时调用，event.detail = { height: 0, lineCount: 0 }，不支持 heightRpx
bind:selectionchange	选区改变事件, event.detail = {selectionStart, selectionEnd}

progress

进度条。

属性

属性名	类型	默认值	说明
percent	number	0	百分比进度，范围0-100
stroke-width	number|string	6	进度条线的宽度，单位px
color	string		进度条颜色（已废弃，请使用 activeColor）
activeColor	string	#09BB07	已选择的进度条的颜色
backgroundColor	string	#EBEBEB	未选择的进度条的颜色
active	boolean	false	进度条从左往右的动画
active-mode	string	backwards	动画播放模式，backwards: 从头开始播放；forwards: 从上次结束点接着播放
duration	number	30	进度增加1%所需毫秒数

事件

事件名	说明
bindactiveend	动画完成时触发，event.detail = { percent }

[!tip] 注意

• 不支持 show-info 属性，即不支持在进度条右侧显示百分比
• 不支持 border-radius 属性自定义圆角大小
• 不支持 font-size 属性设置右侧百分比字体大小

picker-view

嵌入页面的滚动选择器。其中只可放置 picker-view-column 组件，其它节点不会显示

属性

属性名	类型	默认值	说明
value	array<number>	[]	数组中的数字依次表示 picker-view 内的 picker-view-column 选择的第几项（下标从 0 开始），数字大于 picker-view-column 可选项长度时，选择最后一项。
indicator-style	string		设置选择器中间选中框的样式
indicator-class	string		设置选择器中间选中框的类名
mask-style	string		设置蒙层的样式
mask-class	string		设置蒙层的类名
enable-wheel-animation	boolean	true	RN环境特有属性，是否开启滚轮滚动动画效果

事件

事件名	说明
bindchange	滚动选择时触发 change 事件，event.detail = {value}，其中 value 为数组，表示 picker-view 内的 picker-view-column 当前选择的是第几项（下标从 0 开始）

触感反馈回调方法

通过在全局注册 mpx.config.rnConfig.onPickerVibrate 方法，在每次滚动选择时会调用该方法。

注册触感方法名	类型	说明
onPickerVibrate	Function	注册自定义触感反馈方法。调用时机：在每次滚动选择时会调用该方法。可以在方法内自定义实现类似 iOS 端原生表盘的振动触感。

picker-view-column

滚动选择器子项。仅可放置于 picker-view 中，其孩子节点的高度会自动设置成与 picker-view 的选中框的高度一致

picker

从底部弹起的滚动选择器。

属性

属性名	类型	默认值	说明
mode	string	selector	选择器类型，目前支持 selector、 multiSelector、 time、 date、 region
disabled	boolean	false	是否禁用
header-text	string		头部标题

公共事件

事件名	说明
bindcancel	取消选择时触发
bindchange	value 改变时触发 change 事件，event.detail = {value}

普通选择器：mode = selector {#mode-selector}

属性

属性名	类型	默认值	说明
range	array[object]/array	[]	mode 为 selector 或 multiSelector 时，range 有效
range-key	string	false	当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
value	number	0	表示选择了 range 中的第几个（下标从 0 开始）

多列选择器：mode = multiSelector {#mode-multiselector}

属性与事件

属性名	类型	默认值	说明
range	array[object]/array	[]	mode 为 selector 或 multiSelector 时，range 有效
range-key	string	false	当 range 是一个 Object Array 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容
value	array	[]	表示选择了 range 中的第几个（下标从 0 开始）
bindcolumnchange	function		列改变时触发

多列选择器：时间选择器：mode = time {#mode-time}

属性

属性名	类型	默认值	说明
value	string	[]	表示选中的时间，格式为"hh:mm"
start	string	false	表示有效时间范围的开始，字符串格式为"hh:mm"
end	string	[]	表示有效时间范围的结束，字符串格式为"hh:mm"

多列选择器：时间选择器：mode = date {#mode-date}

属性

属性名	类型	默认值	说明
value	string	当天	表示选中的日期，格式为"YYYY-MM-DD"
start	string	false	表示有效日期范围的开始，字符串格式为"YYYY-MM-DD"
end	string	[]	表示有效日期范围的结束，字符串格式为"YYYY-MM-DD"
fields	string	day	有效值 year,month,day，表示选择器的粒度

fields 有效值：

属性名	说明
year	选择器粒度为年
month	选择器粒度为月份
day	选择器粒度为天

省市区选择器：mode = region {#mode-region}

属性

属性名	类型	默认值	说明
value	array	[]	表示选中的省市区，默认选中每一列的第一个值
custom-item	string		可为每一列的顶部添加一个自定义的项
level	string	region	选择器层级

level 有效值：

属性名	说明
province	选省级选择器
city	市级选择器
region	区级选择器

switch

开关选择器。

属性

属性名	类型	默认值	说明
checked	boolean	false	是否选中
disabled	boolean	false	是否禁用
type	string	switch	样式，有效值：switch, checkbox
color	string	#04BE02	switch 的颜色，同 css 的 color

事件

事件名	说明
bindchange	点击导致 checked 改变时会触发 change 事件，event.detail = { value }

navigator

页面链接。

属性

属性名	类型	默认值	说明
hover-class	string	false	指定按下去的样式类。
hover-start-time	number	50	按住后多久出现点击态，单位毫秒
hover-stay-time	number	400	手指松开后点击态保留时间，单位毫秒
open-type	string	navigate	可支持navigateBack、redirect、switchTab、reLaunch、navigateTo
url	string		跳转链接
delta	number		当 open-type 为 'navigateBack' 时有效，表示回退的层数

rich-text

富文本。

属性

属性名	类型	默认值	说明
nodes	array|string	[]	节点列表

canvas

画布。

事件

属性名	说明
bindtouchstart	手指触摸动作开始
bindtouchmove	手指触摸后移动
bindtouchend	手指触摸动作结束
bindtouchcancel	手指触摸动作被打断
bindlongtap	手指长按 350ms 之后触发
binderror	当发生错误时触发 error 事件， detail = {errMsg}

API

方法名	说明
createImage	创建一个图片对象。 仅支持在 2D Canvas 中使用
createImageData	创建一个 ImageData 对象。仅支持在 2D Canvas 中使用
getContext	该方法返回 Canvas 的绘图上下文。仅支持在 2D Canvas 中使用
toDataURL	返回一个包含图片展示的 data URI

[!tip] 注意

• canvas 组件目前仅支持 2D 类型，不支持 webgl
• 通过 Canvas.getContext('2d') 接口可以获取 CanvasRenderingContext2D 对象，具体接口可以参考 HTML Canvas 2D Context 定义的属性、方法
• canvas 的实现主要借助于 PostMessage 方式与 webview 容器通信进行绘制，所以对于严格依赖方法执行时机的场景，如调用 drawImage 绘图，再通过 getImageData 获取图片数据的场景，调用时需要使用 await 等方式来保证方法的执行时机
• 通过 Canvas.createImage 画图，图片的链接不能有特殊字符，安卓手机可能会 load 失败

video

视频

属性

属性名	类型	默认值	说明
src	string		要播放视频的资源地址
controls	boolean	true	是否显示默认播放控件
autoplay	boolean	false	是否自动播放
loop	boolean	false	是否循环播放
muted	boolean	false	是否静音播放
initial-time	number	0	指定视频初始播放位置
object-fit	string	contain	当视频大小与 video 容器大小不一致时，视频的表现形式
poster	string		视频封面的图片地址
enable-auto-rotation	boolean	false	是否开启手机横屏时自动全屏，当系统设置开启自动旋转时生效，仅 ios 支持
preferred-peak-bit-rate	number	0	指定码率上界，单位为比特每秒
is-drm	boolean	false	是否为 drm 视频
provision-url	string		android 环境特有属性，drm 视频的 provision url
certificate-url	string		ios 环境特有属性，drm 视频的 certificate url
license-url	string		drm 视频的 license url

事件

事件名	说明
bindplay	当开始/继续播放时触发play事件
bindpause	当暂停播放时触发 pause 事件
bindended	当播放到末尾时触发 ended 事件
bindtimeupdate	播放进度变化时触发，event.detail = {currentTime, duration}
bindfullscreenchange	视频进入和退出全屏时触发，event.detail = {fullScreen }
bindwaiting	视频出现缓冲时触发
binderror	视频播放出错时触发
bindloadedmetadata	视频元数据加载完成时触发。event.detail = {width, height, duration}
bindcontrolstoggle	切换 controls 显示隐藏时触发。event.detail = {show}
bindseekcomplete	seek 完成时触发

[!tip] 注意

• 手动拖拽进度条场景，bindseekcomplete 事件，android 可以触发，ios 不支持
• video 组件基于第三方库 react-native-video 来实现，需要容器中安装此依赖包

web-view

承载网页的容器。会自动铺满整个 RN 页面

属性

属性名	类型	默认值	说明
src	string		webview 指向网页的链接，如果需要对跳转的URL设定白名单可跳转，需要在业务跳转之前处理该逻辑

事件

属性名	说明
bindmessage	网页向RN通过 postMessage 传递数据
bindload	网页加载成功时候触发此事件
binderror	网页加载失败的时候触发此事件

[!tip] 注意

• 被打开的 H5 页面需使用@mpxjs/webview-bridge@2.9.68 及以上版本与 RN 容器进行通信，具体通信方式参见Webview API

root-portal

使整个子树从页面中脱离出来，类似于在 CSS 中使用 position: fixed 的效果。主要用于制作弹窗、弹出层等。 属性

属性名	类型	默认值	说明
enable	boolean	true	是否从页面中脱离出来

[!tip] 注意

• style 样式不支持中使用百分比计算、css variable

page-container

页面内容容器，常用于实现“假页”弹层。容器展示期间会拦截页面返回行为（包含返回按钮与侧滑返回），并通过回调通知业务侧自行关闭容器。

属性

属性名	类型	默认值	说明
show	boolean	false	是否显示容器
overlay	boolean	true	是否显示遮罩层

事件

事件名	说明
bind:beforeleave	触发返回离开前回调，业务可在回调中更新 show=false 关闭容器

[!tip] 注意

• 当前仅支持 show、overlay 与 bind:beforeleave 三项能力。
• 容器显示时会自动禁用页面返回手势，并在隐藏时恢复，避免 native-stack 场景下手势返回与 JS 状态不一致。
• 该组件依赖导航上下文，仅在 RN 页面路由栈内生效。

sticky-section

吸顶布局容器，仅支持作为 <scroll-view> 的直接子节点

[!tip] 注意

• sticky-section 目前仅支持 RN 、web 以及微信小程序环境，其他环境暂不支持。微信小程序中使用需开启 skyline 渲染模式

sticky-header

吸顶布局容器，仅支持作为 <scroll-view> 的直接子节点或 sticky-section 组件直接子节点

属性

属性名	类型	默认值	说明
offset-top	number	0	吸顶时与顶部的距离
padding	array	[0, 0, 0, 0]	长度为 4 的数组，按 top、right、bottom、left 顺序指定内边距

事件

事件名	说明
bindstickontopchange	吸顶状态变化事件, event.detail = { isStickOnTop }，当 sticky-header 吸顶时为 true，否则为 false

[!tip] 注意

• sticky-header 目前仅支持 RN 、web 以及微信小程序环境，其他环境暂不支持。微信小程序中使用需开启 skyline 渲染模式
• RN 环境的 sticky-header 更适用于内容稳定，状态不常变更的场景使用，目前如果 sticky 还在动画过程中就触发组件更新（如在bindstickontopchange 回调中立刻更新 state）、scroll-view 内容高度由多变少、通过修改 scroll-into-view、scroll-top 让 scroll-view 滚动，以上场景在安卓上都可能会导致闪烁或抖动

cover-view

视图容器。 功能同 view 组件，在 cover-view 中只能嵌套 cover-view 或 cover-image 组件。

cover-image

视图容器。 功能同 image 组件

自定义组件 {#custom-component}

Mpx 完全支持自定义组件功能，组件创建、属性配置、生命周期、插槽使用等更多组件开发的详细指南和高级用法，请参考 自定义组件基础文档。

本节重点介绍在 RN 环境下的特殊注意事项和限制。

组件属性配置 {#component-props-config}

属性	支持状态	说明
properties	✅ 完全支持	组件外部属性声明
data	✅ 完全支持	组件内部数据
computed	✅ 完全支持	计算属性
watch	✅ 完全支持	数据监听
observers	✅ 完全支持	数据变化监听器
methods	✅ 完全支持	组件方法定义
mixins	✅ 完全支持	混入选项
externalClasses	⚠️ 需要配置	外部样式类，需配置构建选项
behaviors	❌ 不支持	小程序 behaviors 机制
options	❌ 不支持	组件选项（multipleSlots、virtualHost 等）
relations	❌ 不支持	组件关系定义

生命周期钩子 {#lifecycle-hooks}

生命周期	支持状态	说明
created	✅ 完全支持	组件实例创建
attached	✅ 完全支持	组件挂载到页面
ready	✅ 完全支持	组件布局完成
detached	✅ 完全支持	组件从页面卸载
lifetimes	✅ 完全支持	生命周期声明对象
pageLifetimes	✅ 完全支持	页面生命周期（show、hide、resize）

实例属性和方法 {#instance-props-methods}

功能	支持状态	说明
id, dataset	✅ 完全支持	节点基础属性
setData	✅ 完全支持	数据更新方法
triggerEvent	✅ 完全支持	事件触发
createSelectorQuery	✅ 有限制	返回一个 SelectorQuery 对象实例，用以查询基础节点位置等属性，需配合 wx:ref 使用
selectComponent	✅ 有限制	在父组件当中获取子组件的实例对象，返回匹配到的第一个组件实例，需配合 wx:ref 使用
selectAllComponents	✅ 有限制	在父组件当中获取子组件的实例对象，返回匹配到的全部组件实例对象组成的数组，需配合 wx:ref 使用
$set, $watch, $delete	✅ 完全支持	响应式数据操作
$refs, $forceUpdate, $nextTick	✅ 完全支持	组件实例方法
$rawOptions	✅ 完全支持	原始选项访问
$i18n	✅ 完全支持	国际化访问器
is	✅ 完全支持	动态组件

selectComponent / selectAllComponents 使用要点 {#select-component-usage}

在 RN 环境下使用 selectComponent 或 selectAllComponents 时

1. 必须在目标节点上标记 wx:ref
2. 选择器支持范围有限，仅支持以下方式

• id 选择器 #id
• class 选择器 .class 或连续指定 .a-class.b-class.c-class

<template>
  <!-- 必须添加 wx:ref 标记 -->
  <list wx:ref class="list"></list>
</template>

<script>
    import { createComponent } from '@mpxjs/core'

  createComponent({
    ready() {
      // 获取组件实例
      const instance = this.selectComponent('.list')
      console.log('selectComponent', instance)
    }
  })
</script>