tencent cloud

Tencent Cloud Super App as a Service

Customizing Mini Program View Components

Download
Focus Mode
Font Size
Last updated: 2026-08-14 17:29:15

Use custom native components

Custom UI components are supported. The custom component on the mini program side is <external-element>. If you want to use the custom UI component, please follow these steps:
1. After integrating the SDK into the client, create a new class that inherits from UIView, for example, QMATestView. Import the TMAExternalJSPlugin.h file and make QMATestView conform to the TMAExternalElementView protocol.
2. Call the TMARegisterExternalElement method to register the QMATestView class as maTestView.
3. Implement the createWithParams and operateWithParams methods in the TMAExternalElementView protocol.
#import "QMATestView.h"
#import <TCMPPSDK/TCMPPSDK.h>

@interface QMATestView () <TMAExternalElementView>

@end

@implementation QMATestView {
UILabel *_textLabel;
UIButton *_clickButton;
id<TMAExternalJSContextProtocol> _context;
}

TMARegisterExternalElement(maTestView);
+ (UIView *)createWithParams:(NSDictionary *)params context:(id<TMAExternalJSContextProtocol>)context {
QMATestView *testView = [[QMATestView alloc] initWithFrame:CGRectZero];
NSDictionary *testViewParams = QQ_Dict_DictValue(params, @"params");
[testView setText:QQ_Dict_StringValue(testViewParams, @"text")];
testView->_context = context;
return testView;
}

// Receive and process the invocation events from the mini program
- (void)operateWithParams:(NSDictionary *)param context:(id<TMAExternalJSContextProtocol>)context {
NSDictionary *data = QQ_Dict_DictValue(param, @"data");
NSDictionary *params1 = QQ_Dict_DictValue(data, @"params1");
NSInteger age = [QQ_Dict_NumberValue(params1, @"age") integerValue];
NSString *name = QQ_Dict_StringValue(params1, @"name");
qq_weakify(self);
[MAUtils executeOnThread:[NSThread mainThread] block:^{
qq_strongify(self);
if (self) {
self->_textLabel.text = [NSString stringWithFormat:@"name = %@ , age = %ld",name,(long)age];
// Return the result to the mini program
TMAExternalJSPluginResult *result = [TMAExternalJSPluginResult new];
result.result = @{@"result":@"success"};
[context doCallback:result];
}
}];
}

Send events to the mini program

To send events from the custom native component to the mini program, first record the context in the createWithParams:context: method:
_context = context;
When sending events, do it like this:
- (void)onClickButton:(UIButton *)button {
_textLabel.text = @"What do you want me to do";
// Assemble data and send the event
NSString *data = [MAUtils JSONStringify:@{@"externalElementId":_elementId,@"type": @"elvisgao callback"}];
[_context doSubscribe:kTMAOnExternalElementEvent data:data];
}

Usage in the mini program

1. Include the mini program WXML:
<external-element
id="comp1"
type="maTestView"
_insert2WebLayer
style="width: 200px;height: 100px;"
bindexternalelementevent="handleEvent"
></external-element>
Note:
The type must be agreed upon with the native side. If not in the same layer, do not set the _insert2WebLayer attribute.
The bindexternalelementevent can listen for operations passed from native, with callback parameters including:

{
target,
currentTarget,
timeStamp,
touches,
detail, // parameters passed from native
}
2. Create an instance in the mini program JS.

this.ctx = wx.createExternalElementContext('comp1');
Note:
The parameter of wx.createExternalElementContext is the ID of the element in the WXML.
3. Call the instance method in the mini program:
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)
}
})
Note:
The instance provides a call method with success, fail, and complete callbacks. The parameters distinguish the method calls, and the base library will invoke the method to pass parameters to native.



Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback