自定义小程序视图组件

Recent Pages

自定义小程序视图组件

最后更新时间：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)
  }
})
﻿
﻿

联系我们

联系我们，为您的业务提供专属服务。

技术支持

如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。

7x24 电话支持

tencent cloud

Recent Pages

自定义小程序视图组件

小程序视图组件扩展说明

原生组件扩展实现

原生组件扩展

小程序原生组件上下文

小程序扩展实现

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

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

tencent cloud

注册

登录

Recent Pages

自定义小程序视图组件

小程序视图组件扩展说明

原生组件扩展实现

原生组件扩展

小程序原生组件上下文

小程序扩展实现

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

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