docs/development/native-component.md
App 开发中有可能使用到大量的UI组件，Hippy SDK 已包括其中常用的部分，如View、Text、Image 等，但这极有可能无法满足你的需求，这就需要对 UI 组件进行扩展封装。支持 Android、iOS、Ohos、Flutter、Web(同构) 等平台。
我们将以MyView为例，从头介绍如何扩展组件。
扩展组件包括：
HippyViewController。createViewImpl方法、Props 设置方法。HippyViewController。HippyViewController 是一个视图管理的基类（如果是ViewGroup的组件，基类为 HippyGroupController）。
在这个例子中我们需要创建一个 MyViewController 类，它继承 HippyViewController<MyView>。MyView 是被管理的UI组件类型，它应该是一个 Android View 或者 ViewGroup。 @HippyController 注解用来定义导出给JS使用时的组件信息。
@HippyController(name = "MyView")
public class MyViewController extends HippyViewController<MyView>
{
...
}
当需要创建对视图时，引擎会调用 createViewImpl 方法。
@Override
protected View createViewImpl(Context context)
{
// context实际类型为HippyInstanceContext
return new MyView(context);
}
需要接收 JS 设置的属性，需要实现带有 @HippyControllerProps 注解的方法。
@HippyControllerProps 可用参数包括：
name（必须）：导出给JS的属性名称。defaultType（必须）：默认的数据类型。取值包括 HippyControllerProps.BOOLEAN、HippyControllerProps.NUMBER、HippyControllerProps.STRING、HippyControllerProps.DEFAULT、HippyControllerProps.ARRAY、HippyControllerProps.MAP。defaultBoolean：当 defaultType 为 HippyControllerProps.BOOLEAN 时，设置后有效。defaultNumber：当 defaultType 为 HippyControllerProps.NUMBER 时，设置后有效。defaultString：当 defaultType 为 HippyControllerProps.STRING 时，设置后有效。@HippyControllerProps(name = "text", defaultType = HippyControllerProps.STRING, defaultString = "")
public void setText(MyView textView, String text)
{
textView.setText(text);
}
Hippy手势处理，复用了 Android 系统手势处理机制。扩展组件时，需要在控件的 onTouchEvent 添加部分代码，JS才能正常收到 onTouchDown、onTouchMove、onTouchEnd 事件。事件的详细介绍，参考 Hippy 事件机制。
@Override
public NativeGestureDispatcher getGestureDispatcher()
{
return mGestureDispatcher;
}
@Override
public void setGestureDispatcher(NativeGestureDispatcher dispatcher)
{
mGestureDispatcher = dispatcher;
}
@Override
public boolean onTouchEvent(MotionEvent event)
{
boolean result = super.onTouchEvent(event);
if (mGestureDispatcher != null)
{
result |= mGestureDispatcher.handleTouchEvent(event);
}
return result;
}
需要在 HippyPackage 的 getControllers 方法中添加这个Controller，这样它才能在JS中被访问到。
@Override
public List<Class<? extends HippyViewController>> getControllers()
{
List<Class<? extends HippyViewController>> components = new ArrayList<>();
components.add(MyViewController.class);
return components;
}
在Hippy框架中，会将前端节点映射为终端的natvie view，view的显示尺寸和位置由框架自带的排版引擎根据前端设置的css计算得出，不需要走系统默认的measure和layout流程，所以我们在HippyRootView中对onMeasure和onLayout两个回调做了拦截：
@Override
protected void onLayout(boolean changed, int left, int top, int right, int bottom)
{
// No-op since UIManagerModule handles actually laying out children.
}
@Override
protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec)
{
setMeasuredDimension(MeasureSpec.getSize(widthMeasureSpec), MeasureSpec.getSize(heightMeasureSpec));
}
但一些业务场景中，自定义组件需要挂载一些非前端节点映射的纯native view，常见的比如video view，lottie view等，由于我们拦截了onMeasure和onLayout，这些视图无法获取到正确的显示尺寸和位置，导致显示异常，所以需要开发者自己手动调用measure和layout来解决这个问题，可以参考以下示例： 在自定义组件的Controller中Override onBatchComplete接口，在非前端节点映射的纯native view的父容器调用measure和layout
private final Handler mHandler = new Handler(Looper.getMainLooper());
@Override
public void onBatchComplete(@NonNull View view)
{
super.onBatchComplete(view);
mHandler.post(new Runnable() {
@Override
public void run()
{
view.measure(View.MeasureSpec.makeMeasureSpec(view.getWidth(), View.MeasureSpec.EXACTLY),
View.MeasureSpec.makeMeasureSpec(view.getHeight(), View.MeasureSpec.EXACTLY));
view.layout(view.getLeft(), view.getTop(), view.getRight(), view.getBottom());
}
});
}
在有些场景，JS需要调用组件的一些方法，比如 MyView 的 changeColor。这个时候需要在 HippyViewController重载 dispatchFunction 方法来处理JS的方法调用。
public void dispatchFunction(MyView view, String functionName, HippyArray var)
{
switch (functionName)
{
case "changeColor":
String color = var.getString(0);
view.setColor(Color.parseColor(color));
break;
}
super.dispatchFunction(view, functionName, var);
}
Hippy SDK 提供了一个基类 HippyViewEvent，其中封装了UI事件发送的逻辑，只需调用 send 方法即可发送事件到JS对应的组件上。比如我要在 MyView 的 onAttachedToWindow 的时候发送事件到前端的控件上面。
示例如下：
@Override
protected void onAttachedToWindow() {
super.onAttachedToWindow();
// this is show how to send message to js ui
HippyMap hippyMap = new HippyMap();
hippyMap.pushString("test", "code");
new HippyViewEvent(" onAttachedToWindow").send(this, hippyMap);
}
onAfterUpdateProps：属性更新完成后回调。onBatchComplete：一次上屏操作完成后回调（适用于 ListView 类似的组件，驱动 Adapter刷新等场景）。onViewDestroy：视图被删除前回调（适用于类似回收视图注册的全局监听等场景）。onManageChildComplete：在 HippyGroupController 添加、删除子视图完成后回调。扩展组件的 Controller 类名和属性设置方法名不能混淆，可以增加混淆例外。
-keep class * extends com.tencent.mtt.hippy.uimanager.HippyGroupController{ public *;}
-keep class * extends com.tencent.mtt.hippy.uimanager.HippyViewController{ public *;}
本文介绍如何在 iOS 端扩展自定义 UI 组件。我们以创建 MyView 为例，完整演示扩展流程。
注意：本文仅介绍 iOS 端工作，前端相关工作请查看对应的前端文档。
Hippy iOS 组件系统包含三个核心部分：
┌─────────────────────────────────────────────────────────┐
│ 组件架构 │
└─────────────────────────────────────────────────────────┘
JavaScript (前端)
↓ (属性/方法调用)
ViewManager (管理器)
↓ 创建和管理
├─ ShadowView (布局计算) ← 可选，复杂布局时需要
└─ UIView (实际显示)
HippyShadowView 即可）扩展一个 UI 组件需要完成以下步骤：
HippyViewManagerHIPPY_EXPORT_MODULE 导出ViewManager 是组件的管理类，负责创建组件实例和处理 JS 与原生的通信。
#import <hippy/HippyViewManager.h>
@interface MyViewManager : HippyViewManager
@end
#import "MyViewManager.h"
#import "MyView.h"
@implementation MyViewManager
// 导出模块，JS 中使用 "MyView" 作为组件名
HIPPY_EXPORT_MODULE(MyView)
// 创建并返回实际的 UIView 实例
- (UIView *)view {
return [[MyView alloc] init];
}
// 创建 ShadowView（可选）
// 大多数情况下返回默认的 HippyShadowView 即可
- (HippyShadowView *)shadowView {
return [[HippyShadowView alloc] init];
}
@end
HIPPY_EXPORT_MODULE(name)
name 是 JS 中使用的组件名称（可选）
HIPPY_EXPORT_MODULE(MyView) → JS 中用 <MyView />HIPPY_EXPORT_MODULE() → MyViewManager → <MyView />创建实际的原生视图组件。
#import <UIKit/UIKit.h>
@interface MyView : UIView
// 自定义属性
@property (nonatomic, copy) NSString *text;
@property (nonatomic, strong) UIColor *textColor;
@property (nonatomic, assign) CGFloat fontSize;
@end
#import "MyView.h"
@implementation MyView {
UILabel *_label;
}
- (instancetype)initWithFrame:(CGRect)frame {
if (self = [super initWithFrame:frame]) {
// 初始化 label
_label = [[UILabel alloc] init];
_label.textAlignment = NSTextAlignmentCenter;
[self addSubview:_label];
// 默认样式
self.textColor = [UIColor blackColor];
self.fontSize = 16.0;
}
return self;
}
- (void)layoutSubviews {
[super layoutSubviews];
_label.frame = self.bounds;
}
- (void)setText:(NSString *)text {
_text = [text copy];
_label.text = text;
}
- (void)setTextColor:(UIColor *)textColor {
_textColor = textColor;
_label.textColor = textColor;
}
- (void)setFontSize:(CGFloat)fontSize {
_fontSize = fontSize;
_label.font = [UIFont systemFontOfSize:fontSize];
}
@end
使用宏将 JS 属性映射到原生组件的属性。
HIPPY_EXPORT_VIEW_PROPERTY(name, type)
直接将 JS 属性映射到同名的原生属性。
@implementation MyViewManager
HIPPY_EXPORT_MODULE(MyView)
// JS: <MyView text="Hello World" />
// → 自动调用 [myView setText:]
HIPPY_EXPORT_VIEW_PROPERTY(text, NSString)
// JS: <MyView textColor="#FF0000" />
// → 自动调用 [myView setTextColor:]
HIPPY_EXPORT_VIEW_PROPERTY(textColor, UIColor)
// JS: <MyView fontSize={18} />
// → 自动调用 [myView setFontSize:]
HIPPY_EXPORT_VIEW_PROPERTY(fontSize, CGFloat)
// JS: <MyView backgroundColor="#F0F0F0" />
HIPPY_EXPORT_VIEW_PROPERTY(backgroundColor, UIColor)
// 其他常用类型示例
HIPPY_EXPORT_VIEW_PROPERTY(enabled, BOOL)
HIPPY_EXPORT_VIEW_PROPERTY(placeholder, NSString)
- (UIView *)view {
return [[MyView alloc] init];
}
@end
支持的类型：
BOOL, NSInteger, CGFloat, double 等NSString, NSNumber, NSArray, NSDictionary 等UIColor, UIFont, UIImage 等HIPPY_REMAP_VIEW_PROPERTY(jsName, nativeName, type)
当 JS 属性名与原生属性名不同时使用。
// JS 中使用 opacity，映射到原生的 alpha
// JS: <MyView opacity={0.5} />
// → 调用 [myView setAlpha:0.5]
HIPPY_REMAP_VIEW_PROPERTY(opacity, alpha, CGFloat)
// JS: <MyView color="#FF0000" />
// → 调用 [myView setTextColor:]
HIPPY_REMAP_VIEW_PROPERTY(color, textColor, UIColor)
支持 KeyPath：第二个参数可以使用 KeyPath 访问嵌套属性。
// JS: <MyView cornerRadius={10} />
// → 调用 [myView.layer setCornerRadius:10]
HIPPY_REMAP_VIEW_PROPERTY(cornerRadius, layer.cornerRadius, CGFloat)
HIPPY_CUSTOM_VIEW_PROPERTY(name, type, viewClass)
当需要自定义属性处理逻辑时使用。
// 自定义处理 fontWeight 属性
HIPPY_CUSTOM_VIEW_PROPERTY(fontWeight, NSString, MyView)
{
// 隐藏参数：
// - json: JS 传来的原始值
// - view: 当前要设置的视图实例（类型为 viewClass）
// - defaultView: 默认视图实例，用于获取默认值
if (json) {
// 有值时：解析并设置
NSString *weight = [HippyConvert NSString:json];
UIFont *currentFont = view.label.font;
CGFloat fontSize = currentFont.pointSize;
if ([weight isEqualToString:@"bold"]) {
view.label.font = [UIFont boldSystemFontOfSize:fontSize];
} else if ([weight isEqualToString:@"normal"]) {
view.label.font = [UIFont systemFontOfSize:fontSize];
}
} else {
// 无值时：使用默认值
view.label.font = defaultView.label.font;
}
}
使用 HippyConvert 类型转换：
#import <hippy/HippyConvert.h>
// 常用转换方法
UIColor *color = [HippyConvert UIColor:json];
CGFloat number = [HippyConvert CGFloat:json];
NSString *text = [HippyConvert NSString:json];
BOOL flag = [HippyConvert BOOL:json];
NSArray *array = [HippyConvert NSArray:json];
NSDictionary *dict = [HippyConvert NSDictionary:json];
对于影响布局的属性，使用 HIPPY_EXPORT_SHADOW_PROPERTY 导出到 ShadowView。
// 这些属性会传递给 ShadowView，参与布局计算
HIPPY_EXPORT_SHADOW_PROPERTY(numberOfLines, NSInteger)
HIPPY_EXPORT_SHADOW_PROPERTY(lineHeight, CGFloat)
使用 HIPPY_EXPORT_METHOD 导出供 JS 调用的方法。
// 无返回值的方法
// JS: callNative('MyView', 'clear', componentId)
HIPPY_EXPORT_METHOD(clear:(nonnull NSNumber *)hippyTag) {
// 注意：这里不在主线程执行
// hippyTag 是组件的唯一标识
// 需要在主线程操作 UI
dispatch_async(dispatch_get_main_queue(), ^{
MyView *view = (MyView *)[self.bridge.uiManager viewForHippyTag:hippyTag];
view.text = @"";
});
}
// 带回调的方法
// JS: callNativeWithPromise('MyView', 'getText', componentId).then(result => ...)
HIPPY_EXPORT_METHOD(getText:(nonnull NSNumber *)hippyTag
callback:(HippyPromiseResolveBlock)callback) {
dispatch_async(dispatch_get_main_queue(), ^{
MyView *view = (MyView *)[self.bridge.uiManager viewForHippyTag:hippyTag];
// 返回结果给 JS
NSDictionary *result = @{
@"text": view.text ?: @"",
@"length": @(view.text.length)
};
callback(result);
});
}
使用 addUIBlock: 在主线程安全地操作 UI。
HIPPY_EXPORT_METHOD(setText:(nonnull NSNumber *)hippyTag
text:(NSString *)text
animated:(BOOL)animated) {
// 使用 UIBlock 确保在主线程执行
[self.bridge.uiManager addUIBlock:^(__unused HippyUIManager *uiManager,
NSDictionary<NSNumber *, UIView *> *viewRegistry) {
// viewRegistry 是 tag -> view 的映射
MyView *view = (MyView *)viewRegistry[hippyTag];
if ([view isKindOfClass:[MyView class]]) {
if (animated) {
[UIView transitionWithView:view
duration:0.3
options:UIViewAnimationOptionTransitionCrossDissolve
animations:^{
view.text = text;
} completion:nil];
} else {
view.text = text;
}
}
}];
}
// 前端调用示例
// 无返回值
this.callNative('MyView', 'clear', this.myViewRef);
// 带参数
this.callNative('MyView', 'setText', this.myViewRef, 'New Text', true);
// 有返回值
const result = await this.callNativeWithPromise('MyView', 'getText', this.myViewRef);
console.log('Text content:', result.text, 'Length:', result.length);
何时需要自定义 ShadowView：
HippyShadowView 即可#import <hippy/HippyShadowView.h>
@interface MyShadowView : HippyShadowView
@property (nonatomic, assign) NSInteger numberOfLines;
@end
#import "MyShadowView.h"
@implementation MyShadowView
- (instancetype)init {
if (self = [super init]) {
_numberOfLines = 0;
}
return self;
}
// 重写布局方法，自定义布局逻辑
- (void)amendLayoutBeforeMount:(NSMutableSet<NativeRenderApplierBlock> *)blocks {
[super amendLayoutBeforeMount:blocks];
// 在这里可以根据 numberOfLines 等属性调整布局
// ...
}
@end
@implementation MyViewManager
HIPPY_EXPORT_MODULE(MyView)
- (HippyShadowView *)shadowView {
return [[MyShadowView alloc] init]; // 返回自定义的 ShadowView
}
- (UIView *)view {
return [[MyView alloc] init];
}
// 导出到 ShadowView 的属性
HIPPY_EXPORT_SHADOW_PROPERTY(numberOfLines, NSInteger)
@end
以下是一个完整的自定义组件示例：
#import <hippy/HippyViewManager.h>
@interface MyViewManager : HippyViewManager
@end
#import "MyViewManager.h"
#import "MyView.h"
@implementation MyViewManager
HIPPY_EXPORT_MODULE(MyView)
// 属性导出
HIPPY_EXPORT_VIEW_PROPERTY(text, NSString)
HIPPY_EXPORT_VIEW_PROPERTY(textColor, UIColor)
HIPPY_EXPORT_VIEW_PROPERTY(fontSize, CGFloat)
HIPPY_EXPORT_VIEW_PROPERTY(backgroundColor, UIColor)
HIPPY_REMAP_VIEW_PROPERTY(opacity, alpha, CGFloat)
HIPPY_CUSTOM_VIEW_PROPERTY(fontWeight, NSString, MyView) {
if (json) {
NSString *weight = [HippyConvert NSString:json];
UIFont *currentFont = view.label.font;
CGFloat fontSize = currentFont.pointSize;
if ([weight isEqualToString:@"bold"]) {
view.label.font = [UIFont boldSystemFontOfSize:fontSize];
} else {
view.label.font = [UIFont systemFontOfSize:fontSize];
}
} else {
view.label.font = defaultView.label.font;
}
}
// 方法导出
HIPPY_EXPORT_METHOD(clear:(nonnull NSNumber *)hippyTag) {
[self.bridge.uiManager addUIBlock:^(__unused HippyUIManager *uiManager,
NSDictionary<NSNumber *, UIView *> *viewRegistry) {
MyView *view = (MyView *)viewRegistry[hippyTag];
view.text = @"";
}];
}
HIPPY_EXPORT_METHOD(getText:(nonnull NSNumber *)hippyTag
callback:(HippyPromiseResolveBlock)callback) {
[self.bridge.uiManager addUIBlock:^(__unused HippyUIManager *uiManager,
NSDictionary<NSNumber *, UIView *> *viewRegistry) {
MyView *view = (MyView *)viewRegistry[hippyTag];
NSDictionary *result = @{
@"text": view.text ?: @"",
@"length": @(view.text.length)
};
callback(result);
}];
}
// 创建视图
- (UIView *)view {
return [[MyView alloc] init];
}
// 创建 ShadowView（使用默认）
- (HippyShadowView *)shadowView {
return [[HippyShadowView alloc] init];
}
@end
#import <UIKit/UIKit.h>
@interface MyView : UIView
@property (nonatomic, copy) NSString *text;
@property (nonatomic, strong) UIColor *textColor;
@property (nonatomic, assign) CGFloat fontSize;
@property (nonatomic, readonly) UILabel *label;
@end
#import "MyView.h"
@implementation MyView
- (instancetype)initWithFrame:(CGRect)frame {
if (self = [super initWithFrame:frame]) {
// 初始化 label
_label = [[UILabel alloc] init];
_label.textAlignment = NSTextAlignmentCenter;
[self addSubview:_label];
// 默认样式
self.textColor = [UIColor blackColor];
self.fontSize = 16.0;
self.backgroundColor = [UIColor whiteColor];
}
return self;
}
- (void)layoutSubviews {
[super layoutSubviews];
_label.frame = self.bounds;
}
- (void)setText:(NSString *)text {
_text = [text copy];
_label.text = text;
}
- (void)setTextColor:(UIColor *)textColor {
_textColor = textColor;
_label.textColor = textColor;
}
- (void)setFontSize:(CGFloat)fontSize {
_fontSize = fontSize;
_label.font = [UIFont systemFontOfSize:fontSize];
}
@end
扩展 Hippy iOS 组件的核心步骤：
HippyViewManagerHIPPY_EXPORT_MODULE 注册组件HIPPY_EXPORT_METHOD 导出方法完成以上步骤后，你的自定义组件就可以在 Hippy 前端中使用了！
我们将以ExampleViewA为例，从头介绍如何扩展组件。
详细代码参考 Demo
扩展组件包括：
HippyCustomComponentView，实现组件View ExampleViewA，以及组件的属性处理函数 setProp 和方法调用函数 callExampleComponentABuilder 函数关联组件View和组件，并配置到 ModuleLoadParams 参数ExampleViewA因为鸿蒙ArkUI是声明式组装组件的，ExampleViewA 相当于组件的数据模型，ExampleComponentA 是实际的声明式组件，通过 Builder 函数来构建组件，通过@ObjectLink 装饰器来绑定数据。
@Observed
export class ExampleViewA extends HippyCustomComponentView {
constructor(ctx: NativeRenderContext) {
super(ctx)
}
setProp(propKey: string, propValue: HippyAny): boolean {
return super.setProp(propKey, propValue)
}
call(method: string, params: Array<HippyAny>, callback: HippyRenderCallback | null): void {
}
}
@Component
export struct ExampleComponentA {
@ObjectLink renderView: ExampleViewA
@ObjectLink children: HippyObservedArray<HippyRenderBaseView>
build() {
Stack() {
Text("This is a custom component A.")
ForEach(this.children, (item: HippyRenderBaseView) => {
buildHippyRenderView(item, null)
}, (item: HippyRenderBaseView) => item.tag + '')
}
.applyRenderViewBaseAttr(this.renderView)
}
}
Builder 函数并配置实现：
@Builder
export function buildCustomRenderView($$: HippyRenderBaseView) {
if ($$ instanceof ExampleViewA) {
ExampleComponentA({ renderView: $$ as ExampleViewA, children: $$.children })
}
}
配置：
loadParams.wrappedCustomRenderViewBuilder = wrapBuilder(buildCustomRenderView)
继承 HippyAPIProvider 接口并注册自定义组件View：
export class ExampleAPIProvider extends HippyAPIProvider {
getCustomRenderViewCreatorMap(): Map<string, HRRenderViewCreator> | null {
let registerMap: Map<string, HRRenderViewCreator> =
new Map()
registerMap.set("ExampleViewA",
(ctx): HippyRenderBaseView => new ExampleViewA(ctx))
return registerMap
}
}
配置 ExampleAPIProvider 到 EngineInitParams 参数:
params.providers = new Array(new ExampleAPIProvider())
详细代码参考 Demo
实际应用开发中，我们经常会遇到需要展示二维码的场景，所以我们这里就以 QrImage 为例，从头介绍如何扩展组件。
本文主要介绍flutter侧工作，前端工作请查看对应的文档。
扩展一个 UI 组件需要包括以下工作：
Controller，ViewModelWidgetControllerimport 'package:flutter/material.dart';
import 'package:flutter/widgets.dart';
import 'package:qr_flutter/qr_flutter.dart';
import 'package:voltron_renderer/voltron_renderer.dart';
class QrController extends BaseViewController<QrRenderViewModel> {
static const String kClassName = "QrImage";
// 提供创建对应 Widget 的方法
@override
Widget createWidget(BuildContext context, QrRenderViewModel viewModel) {
return QrWidget(viewModel);
}
// 创建创建对应 ViewModel 的方法
@override
QrRenderViewModel createRenderViewModel(
RenderNode node,
RenderContext context,
) {
return QrRenderViewModel(
node.id,
node.rootId,
node.name,
context,
);
}
// 组件属性设置，将前端的 Props 对应设置到 ViewModel 中，可类比 Native Renderer 中的 View
@override
Map<String, ControllerMethodProp> get extendRegisteredMethodProp {
var extraMap = <String, ControllerMethodProp>{};
// 这里注意默认值的类型
extraMap[NodeProps.kText] = ControllerMethodProp<QrRenderViewModel, String>(setText, '');
extraMap[NodeProps.kLevel] = ControllerMethodProp<QrRenderViewModel, String>(setLevel, enumValueToString(QrErrorCorrectLevel.L));
return extraMap;
}
// 给 ViewModel 设置对应属性
@ControllerProps(NodeProps.kText)
void setText(QrRenderViewModel viewModel, String text) {
viewModel.text = text;
}
// 给 ViewModel 设置对应属性
@ControllerProps(NodeProps.kLevel)
void setLevel(QrRenderViewModel viewModel, String level) {
switch (level) {
case 'l':
viewModel.level = QrErrorCorrectLevel.L;
break;
case 'm':
viewModel.level = QrErrorCorrectLevel.M;
break;
case 'q':
viewModel.level = QrErrorCorrectLevel.Q;
break;
case 'h':
viewModel.level = QrErrorCorrectLevel.H;
break;
default:
viewModel.level = QrErrorCorrectLevel.L;
}
}
// 处理 UI 事件，类似于 this.$refs.input.focus(); 这里可以参考 TextInput 设计
@override
void dispatchFunction(
QrRenderViewModel viewModel,
String functionName,
VoltronArray array, {
Promise? promise,
}) {
super.dispatchFunction(viewModel, functionName, array, promise: promise);
}
@override
String get name => kClassName;
}
ViewModel这里重点关注对于属性的设置，类似于 text 和 level ， text 指的是二维码对应的数据，level 则可以参考 https://pub.dev/packages/qr_flutter
!> 千万注意要重写相等操作符，Voltron 底层使用了 Provider 来做状态管理，我们会根据 ViewModel 是否相等来判断当前 Widget 是否需要更新
import 'package:qr_flutter/qr_flutter.dart';
import 'package:voltron_renderer/voltron_renderer.dart';
class QrRenderViewModel extends GroupViewModel {
String? text;
int level = QrErrorCorrectLevel.L;
QrRenderViewModel(
int id,
int instanceId,
String className,
RenderContext context,
) : super(id, instanceId, className, context);
QrRenderViewModel.copy(
int id,
int instanceId,
String className,
RenderContext context,
QrRenderViewModel viewModel,
) : super.copy(id, instanceId, className, context, viewModel) {
text = viewModel.text;
level = viewModel.level;
}
@override
bool operator ==(Object other) {
return other is QrRenderViewModel &&
text == other.text &&
level == other.level;
}
@override
int get hashCode =>
text.hashCode |
level.hashCode |
super.hashCode;
}
Widget这里需要注意，如果你的组件需要参与 css 位置计算，那么需要包裹在 PositionedWidget 中（大部分的组件均是如此，例如 TextInput，View 等），如果只需要参与 css 宽高计算，则需要包裹在 BoxWidget 中（例如可以参考 ListView 中的 ListItem ），还有一部分不需要实际存在的组件，则可以自行定制（例如 Modal 组件，本身并不需要实际存在，打开之后是新的蒙层）。
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:qr_flutter/qr_flutter.dart';
import 'package:voltron_renderer/voltron_renderer.dart';
class QrWidget extends FRStatefulWidget {
final QrRenderViewModel _viewModel;
QrWidget(this._viewModel) : super(_viewModel);
@override
State<StatefulWidget> createState() {
return _QrWidgetState();
}
}
class _QrWidgetState extends FRState<QrWidget> {
@override
Widget build(BuildContext context) {
LogUtils.dWidget(
"ID:${widget._viewModel.id}, node:${widget._viewModel.idDesc}, build qr widget",
);
// 这里注意一定要使用 Provider，以实现数据变更驱动视图变更
return ChangeNotifierProvider.value(
value: widget._viewModel,
child: Consumer<QrRenderViewModel>(
builder: (context, viewModel, widget) {
return PositionWidget(
viewModel,
child: qrView(viewModel),
);
},
),
);
}
Widget qrView(QrRenderViewModel viewModel) {
LogUtils.dWidget(
"ID:${widget._viewModel.id}, node:${widget._viewModel.idDesc}, build qr inner widget",
);
var text = viewModel.text;
if (text != null && text.isNotEmpty) {
return QrImage(
data: text,
errorCorrectionLevel: viewModel.level,
padding: const EdgeInsets.all(0),
);
} else {
return Container();
}
}
}
上面的工作做完后，我们需要把组件注册进入 Voltron 应用，还记得初始化时的 MyAPIProvider 吗，这里我们要传入
class MyAPIProvider implements APIProvider {
// 这个是模块扩展
@override
List<ModuleGenerator> get nativeModuleGeneratorList => [];
// 这里是 JavaScript 模块生成器
@override
List<JavaScriptModuleGenerator> get javaScriptModuleGeneratorList => [];
// 这里是组件扩展，将我们扩展的组件按照对应格式写进即可，注意这里的 KClassName 要与前端注册保持一致
@override
List<ViewControllerGenerator> get controllerGeneratorList => [
ViewControllerGenerator(
QrController.kClassName,
(object) => QrController(),
)
];
}
在引擎初始化的时候传入即可
// ...
initParams.providers = [
MyAPIProvider(),
];
// ...
hippy-vue可以参考 hippy-vue/customize
hippy-reactVoltron 手势处理集成在 PositionWidget 或者 BoxWidget 中，无需用户手动处理，只要外层包裹在上述两种Widget下，则默认自带 onClick , onLongclick , onTouchDown, onTouchMove , onTouchEnd 等等一系列手势事件
在有些场景，JavaScript 需要调用组件的一些方法，比如 QrView 的 changeText。这个时候需要在 QrController重载 dispatchFunction 方法来处理JS的方法调用。对应的前端调用文档 hippy-react/customize
@override
void dispatchFunction(
QrRenderViewModel viewModel,
String functionName,
VoltronArray array, {
Promise? promise,
}) {
super.dispatchFunction(viewModel, functionName, array, promise: promise);
if (functionName == "changeText") {}
switch (functionName) {
case "changeText":
String? text = array.get<String>(0);
if (text != null) {
viewModel.text = text;
// 需要注意，如果在调用事件时涉及到界面更新，则需要调用 ViewModel 的 update 方法来触发更新，如果是类似于 input 的 focus()，不涉及 UI 更新，则不需要
viewModel.update();
}
break;
}
}
Voltron SDK 提供了 context.bridgeManager.sendComponentEvent(rootId, id, eventName, params);方法，封装了 UI 事件发送的逻辑，在任意地方找到 RenderContext 调用即可发送事件到 JavaScript 对应的组件上。比如我要在 QrView 的 build 的时候发送事件到前端的控件上面。
示例如下：
@override
Widget build(BuildContext context) {
var params = VoltronMap();
params.push("test", "code");
widget._viewModel.context.bridgeManager.sendComponentEvent(
widget._viewModel.rootId,
widget._viewModel.id,
"eventName",
params,
);
// return SomeWidget();
}
扩展组件主要包括：
HippyWebViewtagNamedomAPI 能力其中 HippyWebView 类，实现了一些 HippyBaseView 的接口和属性定义，在一个自定义组件中有几个比较重要的属性：
nativeName 属性上填写的值，用来关联自定义组件的 key注: tagName 用来和 React/Vue 注册的自定义组件的 nativeName 关联，可参考:
hippy-vue可以参考 hippy-vue/customize
hippy-react下面这个例子中，我们创建了 CustomView 的自定义组件，用来显示一个视频
import { HippyWebView, HippyWebEngine, HippyWebModule } from '@hippy/web-renderer';
// 继承自 `HippyWebView`
class CustomView extends HippyWebView {
// 实现构造方法
constructor(context, id, pId) {
super(context, id, pId);
// 设置自定义组件的 `tagName` 为 `CustomView`，
// 这样 JS 业务使用的时候就可以设置 `nativeName="CustomView"` 进行关联。
this.tagName = 'CustomView';
// 构造自定义组件的 dom，我们创建了一个 video 节点并赋值给 dom 成员变量。注意 dom 成员变量在构造方法结束前一定要设置上
this.dom = document.createElement('video');
}
}
第二步，实现自定义组件的 API 能力和相关属性
我们为 CustomView 实现了一个属性 src，当 JS 业务侧修改 src 属性时就会触发 set src() 方法并且获取到变更后的 value。
我们还实现了组件的两个方法 play 和 pause，当 JS 业务侧使用 callUIFunction(this.instance, 'play'/'pause', []); 的时就会调用到这两个方法。
在 pause() 方法中，我们使用 sendUiEvent 向 JS 业务侧发送了一个 onPause 事件，属性上设置的回调就会被触发。
import { HippyWebView, HippyWebEngine, HippyWebModule } from '@hippy/web-renderer';
class CustomView extends HippyWebView {
set src(value) {
this.dom.src = value;
}
get src() {
return this.props['src'];
}
play() {
this.dom.play();
}
pause() {
this.dom.pause();
this.context.sendUiEvent(this.id, 'onPause', {});
}
}
关于
props:HippyWebRenderer底层默认会将业务侧传递过来的原始props存储到组件的props属性上，然后针对更新的prop项逐个调用与之对应 key 的 set 方法，让组件获得一个更新时机，从而执行一些行为。props里面有一个对象style，承载了所有业务侧设置的样式。默认也是由HippyWebRenderer设置到自定义组件的dom上，中间会有一层转换，因为style中的有一些值是hippy特有的，需要进行一次翻译才可以设置到dom的style上。
关于
context: 自定义组件被构造的时候会传入一个context，它提供了一些关键的方法:
export interface ComponentContext {
sendEvent: (type: string, params: any) => void; // 向业务侧发送全局事件
sendUiEvent: (id: number, type: string, params: any) => void; // 向某个组件实例发送事件
sendGestureEvent: (e: HippyTransferData.NativeGestureEvent) => void; // 发送手势事件
subscribe: (evt: string, callback: Function) => void; // 订阅某个事件
getModuleByName: (moduleName: string) => any; // 获取模块实例，通过模块名
}
有的时候我们可能需要提供一个容器，用来装载一些已有的组件。而这个容器有一些特殊的形态或者行为，比如需要自己管理子节点插入和移除，或者修改样式和拦截属性等。那么这个时候就需要使用一些复杂的组件实现方式。
HippyWebRender 默认的组件 dom 插入和删除，是使用 Web 的方法：Node.insertBefore<T extends Node>(node: T, child: Node | null): T;
Node.removeChild<T extends Node>(child: T): T;
insertChild 和 removeChild 方法管理节点的插入和移除逻辑。class CustomView extends HippyWebView{
insertChild (child: HippyBaseView, childPosition: number) {
// ...
}
removeChild (child: HippyBaseView){
// ...
}
}
props 更新的拦截，需要实现组件的 updateProps 方法。例子中，
data是组件本次更新的props数据信息，defaultProcess()是HippyWebRenderer默认处理props更新的方法，开发者可以在这里拦截修改更新的数据后，依然使用默认的props进行更新，也可以不用默认的方法自行进行属性更新的遍历操作。
class CustomView extends HippyWebView{
updateProps (data: UIProps, defaultProcess: (component: HippyBaseView, data: UIProps) => void) {
// ...
}
}