tencent cloud

腾讯云超级应用服务

动态与公告
【2025年1月2日】关于腾讯云小程序平台更名为腾讯云超级应用服务的公告
控制台更新动态
Android SDK 更新动态
iOS SDK 更新动态
Flutter 更新动态
IDE 更新动态
基础库更新动态
产品简介
产品概述
产品优势
应用场景
购买指南
计费概述
按量计费(后付费)
续费指引
停服说明
快速入门
套餐管理
概述
控制台账号管理
存储配置
加速配置
品牌化配置
平台功能
控制台登录
用户和权限体系
小程序管理
小游戏管理
应用管理
商业化
平台管理
用户管理
团队管理
运营管理
安全中心
代码接入指引
Demo 及 SDK 获取
Android
iOS
Flutter
App 服务端接入指南
GUID 生成规则
小程序开发指南
小程序介绍与开发环境
小程序代码组成
指南
框架
组件
API
服务端
JS SDK
基础库
IDE 使用指南
小游戏开发指南
指南
API
服务端
实践教程
小程序登录实践教程
小程序订阅消息实践教程
支付相关实践教程
广告接入实践教程
小游戏订阅消息实践教程
相关协议
数据处理和安全协议

自定义小程序视图组件

PDF
聚焦模式
字号
最后更新时间: 2024-11-07 17:57:24

小程序视图组件扩展说明

小程序 SDK 的使用者可以自定义客户端原生组件为小程序提供支持。小程序开发者通过特定的小程序 API 能够在小程序页面中创建并操作原生组件以及与原生组件进行通信。Android 的客户端原生组渲染在小程序页面之上,不支持 zIndex,始终位于小程序其他组件上层并会遮挡小程序内容。该类型组件以普通 View 的形式进行绘制。
说明:
为了实现扩展组件,依赖于小程序开发者的在小程序中的改造和宿主应用开发者在宿主应用中的改造,二者结合才能实现小程序视图组件的扩展。

原生组件扩展实现

应用的开发者需要实现特定的代理,在小程序调用自定义组件 API 时创建原生组件以及响应对原生组件的操作。

原生组件扩展

通过如下设置覆写代理,宿主可以自定义创建原生组件:
@ProxyService(proxy = ExternalElementProxy.class)
public class MyExternalElementProxy extends ExternalElementProxy{}
代理需要实现以下内容:
1. 插入组件。当小程序向页面中插入原生组件时会调用此方法。开发者需要实现此方法,并将自定义组件作为子 View 加入到 parent 参数提供的容器中。
/** * 创建组件,当小程序创建自定义原生组件时将会调用此接口 * * @param widgetId 小程序创建的组件唯一ID * @param widgetContext 小程序组件的上下文,用于向小程序回传内容 * @param type 小程序创建的组件类型名称 * @param parent 承载原生组件的父容器 * @param params 小程序创建组件时传递的参数 */ public abstract void handleInsertElement(long widgetId, ExternalWidgetContext widgetContext, String type, ViewGroup parent, JSONObject params);
2. 更新组件。当原生组件在小程序中的位置以及大小发生变化时会调用此方法通知应用。原生组件的父容器布局会按照变化后的样式进行自适应,原生组件本身则可以根据需要对自身进行调整。
/** * 更新组件样式,当小程序更新自定义原生组件的样式时将会调用此接口 * * @param widgetId 小程序组件ID * @param widgetContext 小程序组件的上下文,用于向小程序回传内容 * @param params 小程序更新组件时传递的参数 */ public abstract void handleUpdateElement(long widgetId, ExternalWidgetContext widgetContext, JSONObject params);
3. 操作组件。当小程序向原生组件发送事件时会调用此方法(例如按钮点击,状态变更),事件的具体内容需要开发者自行在 params 中进行定义。
/** * 操作组件,当小程序需要向组件发送指令或者调用特有方法的时候将会调用此接口 * * @param widgetId 小程序组件ID * @param widgetContext 小程序组件的上下文,用于向小程序回传内容 * @param params 小程序更新组件时传递的参数 */ public abstract void handleOperateElement(long widgetId, ExternalWidgetContext widgetContext, JSONObject params);
4. 删除组件。当小程序删除已添加的原生组件时将调用此方法通知应用。此时组件的父容器将被移除,应用应当对组件进行销毁处理。
/** * 删除组件 * * @param widgetId 小程序组件ID * @param widgetContext 小程序组件的上下文,用于向小程序回传内容 */ public abstract void handleRemoveElement(long widgetId, ExternalWidgetContext widgetContext);

小程序原生组件上下文

小程序组件的上下文包含了使原生组件能够向对应的小程序组件发送消息的方法。onExternalElementEvent 方法会直接向小程序发送 onExternalElementEvent 事件,小程序应该捕获并处理该事件;callbackSuccess、callbackFail 则是在小程序调用 API 向应用发送事件时对当次小程序 API 调用传入的 success 或者 fail 方法进行回调。
/** * 向小程序发送 onExternalElementEvent 事件 * * @param jsonObject 事件携带的JSON数据 */ public final void onExternalElementEvent(JSONObject jsonObject); /** * 调用小程序提供的success回调方法 * * @param jsonObject 回调携带的JSON数据,可以为空 */ public final void callbackSuccess(JSONObject jsonObject); /** * 调用小程序提供的fail回调方法 * * @param jsonObject jsonObject 回调携带的JSON数据,可以为空 * @param message 错误信息描述 */ public final void callbackFail(JSONObject jsonObject, String message);

小程序扩展实现

小程序向页面中插入客户端自定义的组件需要先在 wxml 中引入一个 external-element 节点:
<external-element
id="comp1"
type="maTestView"
_insert2WebLayer="true"
style="width: 200px;height: 100px;"
bindexternalelementevent="handleEvent"
></external-element>
此处 type 为与应用约定创建的组件类型名称一致,_insert2WebLayer 表示该组件为同层组件或者非同层组件(true 为同层,需客户端实现同层组件代理;false 为非同层,需要客户端实现非同层代理),bindexternalelementevent 可捕获 native 传递的 onExternalElementEvent 或者onXWebExternalElementEvent,回调参数包括:
{
target,
currentTarget,
timeStamp,
touches,
detail, // native传递的参数
}
之后小程序通过 id 创建一个与该节点相关联的上下文:
this.ctx = wx.createExternalElementContext('comp1');
该方法会通知应用在节点的位置创建对应的原生组件。小程序后续可以通过该上下文向原生组件发送事件,对原生组件进行操作:
this.ctx.call({
params1: {
name: 'name1',
age: 11
},
params2: {
name: 'name2',
age: 22
},
success: (e) => {
console.log('====operate success=====', e)
},
fail: (e) => {
console.log('====operate fail=====', e)
},
complete: (e) => {
console.log('====operate complete=====', e)
}
})



帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈