Custom Mini Program View Components

Last updated: 2025-05-26 15:23:48
Custom Mini Program View Components
Last updated: 2025-05-26 15:23:48
Mini program view component extension
Users of mini program SDK can customize client native components for the mini program. Mini program developers can create and operate native components on mini program pages and communicate with them by using specific mini program APIs. On Android, native client components are rendered above the mini-program page, do not support zIndex, and will always overlay other mini-program components, potentially obscuring mini-program content. These components are drawn as regular Views.
Notes:
To implement extended components, both the mini program developers and the host application developers need to make modifications. The combination of these modifications enables the extension of mini program view components.
Implementation of native component extensions
App developers need to implement specific proxies to create native components and respond to operations on them when the mini program calls custom component APIs.
Native component extensions
To customize the creation of native components, the host can override the proxy settings as follows:
@ProxyService(proxy = ExternalElementProxy.class)
public class MyExternalElementProxy extends ExternalElementProxy{}
The proxy needs to implement the following methods:
1. Insert a component. This method is called when the mini program inserts a native component into the page. Developers need to implement this method and add the custom component as a child View to the container provided by the parent parameter.
/** * Creates a component. This API is called when the mini program creates a custom native component. * * @param widgetId The unique ID of the component created by the mini program. * @param widgetContext The context of the mini program component, which is used to pass content back to the mini program. * @param type The type name of the component created by the mini program. * @param parent The parent container that carries the native component. * @param params The parameters passed when the mini program creates a component */ public abstract void handleInsertElement(long widgetId, ExternalWidgetContext widgetContext, String type, ViewGroup parent, JSONObject params);
2. Update a component. This method is called to notify the app when the position or size of the native component changes within the mini program. The layout of the parent container of the native component will be adapted to the new style, and the native component itself can be adjusted as needed.
/** * Updates component style. This API is called when the mini program updates the style of a custom native component. * * @param widgetId The ID of the mini program component. * @param widgetContext The mini program component context, which is used to pass content back to the mini program. * @param params The parameters passed when the mini program updates a component. */ public abstract void handleUpdateElement(long widgetId, ExternalWidgetContext widgetContext, JSONObject params);
3. Operate a component. This method is called when the mini program sends an event to a native component (e.g., button click, status change). The specific content of the event needs to be defined by the developer in params.
/** * Operates a component. This API is called when the mini program needs to send instructions to the component or call a specific method. * * @param widgetId The ID of the mini program component. * @param widgetContext The mini program component context, which is used to pass content back to the mini program. * @param params The parameters passed when the mini program updates the component. */ public abstract void handleOperateElement(long widgetId, ExternalWidgetContext widgetContext, JSONObject params);
4. Delete a component. This method is called to notify the app when the mini program deletes a native component. At this point, the component's parent container is removed and the app should destroy the component.
/** * Deletes a component. * * @param widgetId The ID of the mini program component. * @param widgetContext The mini program component context, which is used to pass content back to the mini program. */ public abstract void handleRemoveElement(long widgetId, ExternalWidgetContext widgetContext);
Mini program native component context
The context of mini program components contains methods that allow native components to send messages to the corresponding mini program components. The onExternalElementEvent method is used to send an onExternalElementEvent event directly to the mini program, and the mini program should capture and process the event. The callbackSuccess and callbackFail methods are used to call the success or fail callbacks respectively when the mini program calls an API to send an event to the app.
/** * Sends an onExternalElementEvent event to the mini program.* * @param jsonObject JSON data carried by the event. */ public final void onExternalElementEvent(JSONObject jsonObject); /** * Calls the success callback. * * @param jsonObject JSON data carried by the callback, which can be null. */ public final void callbackSuccess(JSONObject jsonObject); /** * Calls the fail callback. * * @param jsonObject jsonObject JSON data carried by the callback, which can be null. * @param message Error message description. */ public final void callbackFail(JSONObject jsonObject, String message);
Implementation of mini program extension
To insert a custom client-side component into a mini program page, you need to include an external-element node in the WXML:
<external-element
    id="comp1"
    type="maTestView"
    _insert2WebLayer="true"
    style="width: 200px;height: 100px;"
    bindexternalelementevent="handleEvent"
></external-element>
The type should match the component type name agreed upon with the app._insert2WebLayer  indicates whether the component is a same-layer component or a non-same-layer component (true for same-layer, which requires the client to implement a same-layer component proxy; false for non-same-layer, which requires the client to implement a non-same-layer proxy). The bindexternalelementevent can capture events passed from the native side, such as onExternalElementEvent or onXWebExternalElementEvent. The callback parameters include:
{
    target,
    currentTarget,
    timeStamp,
    touches,
    detail, // Parameters passed by native
}
Then, the mini program creates a context associated with this node using its ID.
this.ctx = wx.createExternalElementContext('comp1');
This method notifies the application to create the corresponding native component at the position of the node. Once the context is created, the mini program can send events to the native component and perform operations on it through this context:
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)
  }
})
﻿
﻿
﻿
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
Feedback
tencent cloud

Mini program view component extension

Implementation of native component extensions

Native component extensions

Mini program native component context

Implementation of mini program extension
