tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Tencent Cloud Mini Program Platform
    Documentation
    Download PDF

    Custom native component

    Last updated: 2024-03-04 22:45:22
    Download PDF
      Users of the Mini Program SDK can customize native client components to support the mini program. Mini program developers can create and manipulate native components on the mini program page and communicate with them through specific mini program APIs. There are two types of native client components for Android:
      Native components at different layers: These components are rendered above the mini program page, do not support zIndex, and are always positioned above other mini program components, obscuring the mini program content. These types of components are drawn in the form of a standard View.
      Same-layer native components: These components are rendered within the mini program page, supporting zIndex and the hierarchical relationship of components within the page. These types of components need to be drawn in the form of a Surface within the mini program page.
      
      To insert a client-customized component into the mini program page, an external-element node must first be introduced into the wxml:
      <external-element
          id="comp1"
          type="maTestView"
          _insert2WebLayer="true"
          style="width: 200px;height: 100px;"
          bindexternalelementevent="handleEvent"
      ></external-element>
      Here: "type" matches the agreed-upon component type name created with the application; "_insert2WebLayer" indicates whether the component is a same-layer component or different-layer component ("true" for same-layer component, requiring the client to implement a same-layer component proxy; "false" for different-layer component, requiring the client to implement a different-layer proxy); "bindexternalelementevent" can capture the "onExternalElementEvent" or "onXWebExternalElementEvent" passed by the native. The callback parameters include:
      {
          target,
          currentTarget,
          timeStamp,
          touches,
          detail, // Parameters passed by the native
      }
      Subsequently, the mini program creates a context associated with this node through its id:
      this.ctx = wx.createExternalElementContext('comp1');
      This method will notify the application to create the corresponding native component at the node's location. Subsequently, the mini program can send events to the native component through this context, thereby manipulating 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)
        }
      })
      Application developers need to implement specific proxies to create native components and respond to operations on native components when the mini program calls the custom component API. The following will explain separately for different-layer components and same-layer components.

      Custom different-layer native components

      By setting the override proxy as follows, the host can customize the creation of different-layer native components:
      @ProxyService(proxy = ExternalElementProxy.class)
      public class MyExternalElementProxy extends ExternalElementProxy{}
      The proxy needs to implement the following:
      1. Insert different-layer components. This method is called when the mini program inserts a different-layer 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 a different-layer component. This interface will be called when the mini program creates a custom different-layer native component.
 * 
 * @param widgetId: Unique ID of the component created by the mini program
 * @param widgetContext: Context of the mini program component, 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 carrying the native component
 * @param params: Parameters passed when the mini program creates the component
 */
public abstract void handleInsertElement(long widgetId, ExternalWidgetContext widgetContext,
                                         String type, ViewGroup parent, JSONObject params);
      2. Update different-layer components. This method is called to notify the application when the position or size of the native component in the mini program changes. The layout of the parent container of the native component will adapt according to the changed style, and the native component can adjust itself as needed.
      /**
 * Update the style of different-layer components. This interface will be called when the mini program updates the style of custom different-layer native components.
 *
 * @param widgetId: ID of the mini program component
 * @param widgetContext: Context of the mini program component, used to pass back content to the mini program
 * @param params: Parameters passed when the mini program updates the component
 */
public abstract void handleUpdateElement(long widgetId, ExternalWidgetContext widgetContext,
                                         JSONObject params);
      3. Operate different-layer components. This method is called when the mini program sends an event to the native component (such as button click, status change). The specific content of the event needs to be defined by the developer in the params.
      /**
 * Operate different-layer components. This interface will be called when the mini program needs to send instructions to the different-layer component or call unique methods.
 *
 * @param widgetId: ID of the mini program component
 * @param widgetContext: Context of the mini program component, used to pass back content to the mini program
 * @param params: Parameters passed when the mini program updates the component
 */
public abstract void handleOperateElement(long widgetId, ExternalWidgetContext widgetContext,
                                          JSONObject params);
      4. Delete different-layer components. This method is called to notify the application 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 different-layer components
 *
 * @param widgetId: ID of the mini program component
 * @param widgetContext: Context of the mini program component, used to pass back content to the mini program
 */
public abstract void handleRemoveElement(long widgetId, ExternalWidgetContext widgetContext);

      Mini program's different-layer native component context

      The context of the mini program component includes methods that allow the native component to send messages to the corresponding mini program component. The onExternalElementEvent method will directly send the onExternalElementEvent event to the mini program, which should capture and handle this event; callbackSuccess and callbackFail are callbacks to the success or fail methods passed in the current mini program API call when the mini program calls the API to send events to the application.
      /**
 * Send an onExternalElementEvent event to the mini program
 *
 * @param jsonObject: JSON data carried by the event
 */
public final void onExternalElementEvent(JSONObject jsonObject);

/**
 * Call the success callback method provided by the mini program
 *
 * @param jsonObject: JSON data carried by the callback, which can be null
 */
public final void callbackSuccess(JSONObject jsonObject);

/**
 * Call the fail callback method provided by the mini program
 *
 * @param jsonObject JSON data carried by the callback, can be null
 * @param message Error message description
 */
public final void callbackFail(JSONObject jsonObject, String message);

      Custom same-layer native components

      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 different-layer components, same-layer components involve the creation and destruction of the embedded page's Surface, thus providing additional component lifecycle callbacks. Developers can override these methods to handle lifecycle events of same-layer components:
      /**
 * Initialize the same-layer component DOM node
 *
 * @param context: Page context
 * @param widgetId: Same-layer component ID
 * @param tagName: Tag of the same-layer component in the DOM
 * @param attributes: Attributes of the same-layer component
 */
public abstract void onInit(Context context, long widgetId, String tagName, Map<String, String> attributes);

/**
 * Callback when the same-layer component Surface 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 same-layer component Surface 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: Touch event
 * @return: Whether the same-layer component consumes the 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);

/**
 * Request for the same-layer component to redraw
 *
 * @param widgetId: Same-layer component ID
 */
public abstract void onRequestRedraw(long widgetId);

/**
 * Callback when the visibility of the same-layer component changes
 *
 * @param widgetId: Same-layer component ID
 * @param visibility: Whether it is visible
 */
public abstract void onVisibilityChanged(long widgetId, boolean visibility);

/**
 * The same-layer component becomes active
 *
 * @param widgetId: Same-layer component ID
 */
public abstract void onActive(long widgetId);

/**
 * The same-layer component becomes inactive
 *
 * @param widgetId: Same-layer component ID
 */
public abstract void onDeActive(long widgetId);

/**
 * The 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 status
 *
 * @param widgetId: Same-layer component ID
 */
public abstract void webViewPause(long widgetId);

/**
 * The current mini program page enters the resume status
 *
 * @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);

/**
 * The mini program enters the resume status
 *
 * @param widgetId: Same-layer component ID
 */
public abstract void nativeResume(long widgetId);

/**
 * The mini program enters the pause status
 *
 * @param widgetId: Same-layer component ID
 */
public abstract void nativePause(long widgetId);

/**
 * The mini program is destroyed
 *
 * @param widgetId: Same-layer component ID
 */
public abstract void nativeDestroy(long widgetId);
      2. When the mini program actually inserts a same-layer component into the page, it will call the application's handleInsertXWebExternalElement interface. Client developers should implement this method and, based on the component type provided by type, draw the corresponding component on the Surface associated with widgetId.
      /**
 * Insert a same-layer component
 *
 * @param widgetId: Same-layer component ID
 * @param widgetContext: Mini program context associated with the same-layer component
 * @param type: Type of the same-layer component
 * @param req: Pass-through parameters of the same-layer component
 */
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 the style of the same-layer component
 *
 * @param widgetId: Same-layer component ID
 * @param widgetContext: 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 operate the native component when sending events to it, the application will be notified through this method:
      /**
 * Operate a same-layer component
 *
 * @param widgetId: Same-layer component ID
 * @param widgetContext: 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 component needs to delete the native component, the application will be notified through this method:
      /**
 * Remove the same-layer component
 *
 * @param widgetId: Same-layer component ID
 * @param widgetContext: Mini program context associated with the same-layer component
 */
public abstract void handleRemoveXWebExternalElement(long widgetId, XWebExternalWidgetContext widgetContext);

      Mini program's same-layer native component context

      Similar to different-layer components, same-layer components can send onXWebExternalElementEvent events to the mini program through the context of the mini program component, or call back the method provided by the API when the mini program calls the API to operate the native component.
      /**
 * Send an onXWebExternalElementEvent event to the mini program
 *
 * @param jsonObject: JSON data carried by the event
 */
public final void onXWebExternalElementEvent(JSONObject jsonObject);

/**
 * Call the success callback method provided by the mini program
 *
 * @param jsonObject: JSON data carried by the callback, which can be null
 */
public final void callbackSuccess(JSONObject jsonObject);

/**
 * Call the fail callback method provided by the mini program
 *
 * @param jsonObject JSON data carried by the callback, can be null
 * @param message Error message description
 */
public final void callbackFail(JSONObject jsonObject, String message);
      
      Contact Us

      Contact our sales team or business advisors to help your business.

      Contact Us
      Technical Support

      Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy