Custom mini program view components

Recent Pages

Custom mini program view components

Last updated: 2024-06-27 10:55:30
Mini program view component extension description
Users of the mini program SDK can customize native client components to support mini programs. Mini program developers can create and manipulate native components on mini program pages and communicate with them using specific mini program APIs. Android native client components are divided into two types:  
Non-layered native components: These components render above the mini program page, do not support zIndex, and always overlay other mini program components, potentially obscuring content. They are drawn as regular Views;
Layered native components: These components render within the mini program page, support zIndex, and respect the component hierarchy within the page. They need to be drawn as Surfaces within the mini program page.
Note：
To implement extended components, modifications are required both in the mini program by the mini program developer and in the host app by the host app developer. 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. The following sections describe the implementation for non-layered and layered components separately:
Non-layered native component extension
Override the proxy with the following settings to allow the host to customize the creation of non-layered native components:
@ProxyService(proxy = ExternalElementProxy.class)
public class MyExternalElementProxy extends ExternalElementProxy{}
The proxy needs to implement the following methods:
1. Insert non-layered component This method is called when the mini program inserts a non-layered 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.
/**
 * Create non-layered components. When the mini program creates custom non-layered native components, this API will be called. 
 * 
 * @param widgetId The unique ID of the component created by the mini program
 * @param widgetContext Context of the mini program component, which is used to pass back content to the mini program
 * @ param type Name of the component type created by the mini program
 * @param parent Parent container hosting native components
 * @param params: Arguments passed when the mini program creates the component
 */
public abstract void handleInsertElement(long widgetId, ExternalWidgetContext widgetContext,
                                         String type, ViewGroup parent, JSONObject params);
2. Update Non-layered Component This method is called to notify the app when the position or size of the native component changes within the mini program. The parent container layout of the native component will adapt to the new style, and the native component itself can adjust as needed.
/**
 * update with layer component style, when the applet to update the style of the custom layer with native components will call this interface
 *
 * @ param widgetId Mini program component ID
 * @param widgetContext Context of the mini program component, which is used to pass back content to the mini program
 * @param params Parameters passed when the mini program updates a component
 */
public abstract void handleUpdateElement(long widgetId, ExternalWidgetContext widgetContext,
                                         JSONObject params);
3. Operate non-layered component Operate Non-layered Component: This method is called when the mini program sends an event to the native component (e.g., button click, state change). The specific content of the event needs to be defined by the developer in the params.
/**
 * Operation with layer components, when the Mini programs need to send instructions to the different layer components or call the unique method will call this interface
 *
 * @param widgetId Mini program component ID
 * @param widgetContext Context of the mini program component, which is used to pass back content to the mini program
 * @param params Parameters passed when the mini program updates a component
 */
public abstract void handleOperateElement(long widgetId, ExternalWidgetContext widgetContext,
                                          JSONObject params);
4. Remove non-layered component This method is called to notify the app when the mini program deletes an added native component. At this point, the parent container of the component will be removed, and the application should destroy the component.
/**
 *Delete non-layered components
 *
 * @param widgetId Mini program component ID
 * @param widgetContext Context of the mini program component, which is used to pass back content to the mini program
 */
public abstract void handleRemoveElement(long widgetId, ExternalWidgetContext widgetContext);
Mini program non-layered native component context
The context for mini program components includes methods that allow native components to send messages to the corresponding mini program components. The onExternalElementEvent method sends an onExternalElementEvent event directly to the mini program, which should capture and handle this event. The callbackSuccess and callbackFail methods are used to call the success or fail callbacks provided by the mini program when it invokes an API to send events to the application.
/**
 * Sends onExternalElementEvent event to the mini program.
 *
 * @param jsonObject JSON data carried by the event.
 */
public final void onExternalElementEvent(JSONObject jsonObject);
 
/**
 * Calls the success callback provided by the mini program.
 *
 * @param jsonObject JSON data carried by the callback, which can be null.
 */
public final void callbackSuccess(JSONObject jsonObject);
 
/**
 *  Calls the `fail` callback provided by the mini program.
 *
 * @param jsonObject JSON data carried by the callback, which can be null.
 /// @param message Error message description
 */
public final void callbackFail(JSONObject jsonObject, String message);
Same-layer native component extensions
If the mini program requests the creation of a same-layer native component, the application needs to implement the following proxy:
@ProxyService(proxy = ExternalEmbeddedWidgetClient.class)
public class MyExternalEmbeddedElementProxy extends ExternalEmbeddedWidgetClient{}
1. Unlike non-layered components, same-layer components involve the creation and destruction of a Surface embedded in the page, thus providing additional lifecycle callbacks. Developers can override these methods to handle lifecycle events of same-layer components:
 * @param tagName Tag of same-layer component in DOM
 * @param attributes Attributes of same-layer components
 */
public abstract void onInit(Context context, long widgetId, String tagName, Map<String, String> attributes);
 
/**
 * Callback when the Surface of the same-layer component is created.
 *
 * @param widgetId Same-layer component ID
 * @param surface Surface associated with the same-layer component
 */
public abstract void onSurfaceCreated(long widgetId, Surface surface);
 
/**
 * Callback when the Surface of the same-layer component is destroyed.
 *
 * @param widgetId Same-layer component ID
 * @param surface Surface associated with the same layer component 
 */
public abstract void onSurfaceDestroyed(long widgetId, Surface surface);
 
/**
 * Callback for touch events on the same-layer component.
 *
 * @param widgetId Same-layer component ID
 * @param event The touch event
 * @return Whether the same-layer components consumed touch event
 */
public abstract boolean onTouchEvent(long widgetId, MotionEvent event);
 
/**
 * Callback when the drawing area of the same-layer component changes.
 *
 * @param widgetId Same-layer component ID
 * @param rect: New drawing area
 */
public abstract void onRectChanged(long widgetId, Rect rect);
 
/**
 * Requests a redraw of the same-layer component.
 *
 * @param widgetId Same-layer component ID
 */
public abstract void onRequestRedraw(long widgetId);
 
/**
 * The visibility of the same-layer component changes.
 *
 * @param widgetId Same-layer component ID
 Is * @param visibility Whether it is visible
 */
public abstract void onVisibilityChanged(long widgetId, boolean visibility);
 
/**
 * Same-layer components become available
 *
 * @param widgetId Same-layer component ID
 */
public abstract void onActive(long widgetId);
 
/**
 * Same-layer components become unavailable
 *
 * @param widgetId Same-layer component ID
 */
public abstract void onDeActive(long widgetId);
 
/**
 * Same-layer component node is destroyed
 *
 * @param widgetId Same-layer component ID
 */
public abstract void onDestroy(long widgetId);
 
/**
 * The current mini program page enters the pause state
 *
 * @param widgetId Same-layer component ID
 */
public abstract void webViewPause(long widgetId);
 
/**
 *The current mini program page enters the resume state.
 *
 * @param widgetId Same-layer component ID
 */
public abstract void webViewResume(long widgetId);
 
/**
 * The current mini program page is destroyed
 *
 * @param widgetId Same-layer component ID
 */
public abstract void webViewDestroy(long widgetId);
 
/**
 * Mini program enters resume state
 *
 * @param widgetId Same-layer component ID
 */
public abstract void nativeResume(long widgetId);
 
/**
 * Mini program enters pause state
 *
 * @param widgetId Same-layer component ID
 */
public abstract void nativePause(long widgetId);
 
/**
 * Mini program is destroyed
 *
 * @param widgetId Same-layer component ID
 */
public abstract void nativeDestroy(long widgetId);
2. When the mini program actually inserts an same-layer component into the page, it will call the application's handleInsertXWebExternalElement API. Client developers should implement this method to render the appropriate component type, as specified by type, onto the Surface associated with widgetId.
/**
 * Inserts a same-layer component.
 *
 * @param widgetId Same-layer component ID
 * @param widgetContext The mini program context associated with the same-layer component.
 * @ param type The type of the same-layer component.
 * @param req Parameters passed through by the mini program.
 */
public abstract void handleInsertXWebExternalElement(long widgetId, ExternalWidgetContext widgetContext, String type, JSONObject req);
3. When the size or style of the component changes, the application will be notified through this method: 
/**
 * Update same-layer component style
 *
 * @param widgetId Same-layer component ID
 * @param widgetContext The mini program context associated with the same-layer component.
 * @param req Parameters passed by the mini program.
 */
public abstract void handleUpdateXWebExternalElement(long widgetId, XWebExternalWidgetContext widgetContext, JSONObject req);
4. When the mini program component needs to send events to the native component for operations, it will notify the application through this method: 
/**
 * Operates on the same-layer component.
 *
 * @param widgetId Same-layer component ID
 * @param widgetContext The mini program context associated with the same-layer component.
 * @param req Parameters passed by the mini program.
 */
public abstract void handleOperateXWebExternalElement(long widgetId, XWebExternalWidgetContext widgetContext, JSONObject req);
5.  When the mini program deletes a same-layer native component, it will notify the application through this method:
/**
 * Remove same-layer components
 *
 * @param widgetId Same-layer component ID
 * @param widgetContext The mini program context associated with the same-layer component.
 
*/
public abstract void handleRemoveXWebExternalElement(long widgetId, XWebExternalWidgetContext widgetContext);
Mini program same-layer native component context
Similar to non-layered components, same-layer components can send onXWebExternalElementEvent events to the mini program through the component's context. Additionally, when the mini program calls APIs to operate on native components, it can use the provided callback methods.
/**
 * Sends onXWebExternalElementEvent event to the mini program.
 *
 * @param jsonObject JSON data carried by the event
 */
public final void onXWebExternalElementEvent(JSONObject jsonObject);
 
/**
 * Calls the success callback provided by the mini program.
 *
 * @param jsonObject JSON data carried by the callback, which can be null.
 */
public final void callbackSuccess(JSONObject jsonObject);
 
/**
 * Calls the `fail` callback provided by the mini program.
 *
 * @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);
Mini program extension implementation
To insert a custom client-side component into the page, the mini program first needs 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>
Here, type should match the component type name agreed upon with the application. _insert2WebLayer indicates whether the component is a same-layer component (true for same-layer, requiring client-side same-layer component proxy; false for non-layered, requiring client-side non-layered proxy). bindexternalelementevent can capture native onExternalElementEvent or onXWebExternalElementEvent events, with callback parameters including: OnXWebExternalElementEvent, callback parameters include:
{
    target,
    currentTarget,
    timeStamp,
    touches,
    detail, // Parameters passed by native
}
Next, 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 node's position. The mini program can then use this context to send events to and operate on the native component:
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)
  }
})
﻿
﻿
Contact Us
Contact our sales team or business advisors to help your business.
Technical Support
Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.
7x24 Phone Support
tencent cloud

Recent Pages

Custom mini program view components

Mini program view component extension description

Implementation of native component extensions

Non-layered native component extension

Mini program non-layered native component context

Same-layer native component extensions

Mini program same-layer native component context

Mini program extension implementation

Was this page helpful?

Was this page helpful?

tencent cloud

Sign Up

Log in

Recent Pages

Custom mini program view components

Mini program view component extension description

Implementation of native component extensions

Non-layered native component extension

Mini program non-layered native component context

Same-layer native component extensions

Mini program same-layer native component context

Mini program extension implementation

Was this page helpful?

Was this page helpful?
