概述

扩展原生能力指的是将您原生开发的功能通过一定规范暴露给 uni小程序环境,然后即可在 uni小程序应用中调用您的原生功能。

扩展方式

uni 原生端是基于 WeexSDK 来实现扩展原生能力,扩展原生能力有两种方式:一种是不需要参与页面布局,只需要通过 API 调用原生功能,比如:获取当前定位信息、数据请求等功能,这种情况可通过扩展module的方式来实现;另一种是需要参与页面布局,比如:map、image,这种情况需要通过扩展component即组件的方法来实现;

开发环境

  • iOS开发环境,请使用 Xcode 11.0 及以上版本;
  • 已有集成 iOS uni小程序SDK 原生工程;集成文档
  • 安装 uni小程序开发工具 HBuilderX (注:版本需与您使用的 uni小程序SDK 版本保持一致)

扩展 module

下面以TestModule为例,源码请查看 uni小程序SDK 包中的示例 demo 工程;

1. 新建TestModule类,继承 NSObject,让该类遵循 WXModuleProtocol 的协议。

  1. #import <Foundation/Foundation.h>
  2. // 引入 WeexSDK.h 头文件
  3. #import "WeexSDK.h"
  4. @interface TestModule : NSObject <WXModuleProtocol>
  5. @end

2. 添加实现方法

异步方法实现

  1. /// 异步方法(注:异步方法会在主线程(UI线程)执行)
  2. /// @param options js 端调用方法时传递的参数
  3. /// @param callback 回调方法,回传参数给 js 端
  4. - (void)testAsyncFunc:(NSDictionary *)options callback:(WXModuleKeepAliveCallback)callback {
  5. // options 为 js 端调用此方法时传递的参数
  6. NSLog(@"%@",options);
  7. // 可以在该方法中实现原生能力,然后通过 callback 回调到 js
  8. // 回调方法,传递参数给 js 端 注:只支持返回 String 或 NSDictionary (map) 类型
  9. if (callback) {
  10. // 第一个参数为回传给js端的数据,第二个参数为标识,表示该回调方法是否支持多次调用,如果原生端需要多次回调js端则第二个参数传 YES;
  11. callback(@"success",NO);
  12. }
  13. }

通过宏 WX_EXPORT_METHOD 将异步方法暴露给 js 端,只有通过WX_EXPORT_METHOD暴露的原生方法才能被 js 端识别到

  1. // 通过宏 WX_EXPORT_METHOD 将异步方法暴露给 js 端
  2. WX_EXPORT_METHOD(@selector(testAsyncFunc:callback:))

同步方法实现

  1. /// 同步方法(注:同步方法会在 js 线程执行)
  2. /// @param options js 端调用方法时传递的参数
  3. - (NSString *)testSyncFunc:(NSDictionary *)options {
  4. // options 为 js 端调用此方法时传递的参数
  5. NSLog(@"%@",options);
  6. /*
  7. 可以在该方法中实现原生功能,然后直接通过 return 返回参数给 js
  8. */
  9. // 同步返回参数给 js 端 注:只支持返回 String 或 NSDictionary (map) 类型
  10. return @"success";
  11. }

通过宏 WX_EXPORT_METHOD_SYNC 将同步方法暴露给 js 端

  1. // 通过宏 WX_EXPORT_METHOD_SYNC 将同步方法暴露给 js 端
  2. WX_EXPORT_METHOD_SYNC(@selector(testSyncFunc:))

3. 注册 module

在初始化 DCUniMPSDKEngine 方法后,进行 module 的注册

  1. - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  2. ...
  3. // 初始化引擎
  4. [DCUniMPSDKEngine initSDKEnvironmentWihtLaunchOptions:options];
  5. // 注册 module 注:module的 Name 需要保证唯一, class:为 module 的类名
  6. [WXSDKEngine registerModule:@"TestModule" withClass:NSClassFromString(@"TestModule")];
  7. return YES;
  8. }

到此,我们已经完成了一个简单的 module 扩展

4. 在 uni小程序 中调用 module 方法

module 支持在 vue 和 nvue 中使用

  1. <template>
  2. <div>
  3. <button type="primary" @click="testAsyncFunc">testAsyncFunc</button>
  4. <button type="primary" @click="testSyncFunc">testSyncFunc</button>
  5. </div>
  6. </template>
  7. <script>
  8. // 获取 module
  9. var testModule = uni.requireNativePlugin("TestModule")
  10. export default {
  11. methods: {
  12. testAsyncFunc() {
  13. // 调用异步方法
  14. testModule.testAsyncFunc({
  15. 'name': 'unimp',
  16. 'age': 1
  17. },
  18. (ret) => {
  19. console.log(ret)
  20. })
  21. },
  22. testSyncFunc() {
  23. // 调用同步方法
  24. var ret = testModule.testSyncFunc({
  25. 'name': 'unimp',
  26. 'age': 1
  27. })
  28. }
  29. }
  30. }
  31. </script>

然后可以导出 uni小程序资源,导入到 App 中查看效果;

扩展组件 component

下面以TestComponent为例,源码请查看 uni小程序SDK 包中的示例 demo 工程;

1. 新建TestComponent类,继承WXComponent类。如果这个类里什么代码也不写,它和默认的的 view 组件能力是一致的

  1. #import "WXComponent.h"
  2. @interface TestComponent : WXComponent
  3. @end

2. 覆写 WXComponent 中的生命周期方法

- loadView 方法

一个组件默认对应于一个原生 view,如果未覆盖loadView提供自定义 view,基类会默认返回一个继承于 UIView 的实例。比如我们要实现一个组件支持地图功能,我们可以返回系统的 MKMapView

  1. - (UIView *)loadView {
  2. return [MKMapView new];
  3. }

- viewDidLoad

对组件 view 需要做一些配置,比如设置 delegate,可以在 viewDidLoad 生命周期做。如果当前 view 没有添加 subview 的话,不要设置 view 的 frame,WeexSDK 会根据 style 进行排版后设置。

  1. - (void)viewDidLoad {
  2. ((MKMapView*)self.view).delegate = self;
  3. }

3. 注册组件

在初始化 DCUniMPSDKEngine 方法后,进行 component 的注册

  1. - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  2. ...
  3. // 初始化引擎
  4. [DCUniMPSDKEngine initSDKEnvironmentWihtLaunchOptions:options];
  5. // 注册 component 注:component 的 Name 需要保证唯一, class:为 component 的类名
  6. [WXSDKEngine registerComponent:@"testmap" withClass:NSClassFromString(@"TestMapComponent")];
  7. return YES;
  8. }

4. 在uni小程序代码中使用组件

注意:扩展的 component 只能在 nvue 文件中使用

  1. <template>
  2. <div>
  3. <testmap style="width:200px;height:200px"></testmap>
  4. </div>
  5. </template>

自定义事件

1. 对于每个组件默认提供了一些事件能力,如点击等。假如想给我们的地图组件提供 mapLoaded 事件。

在uni小程序代码中,通过 @事件名="方法名" 添加事件,如下添加mapLoaded 事件

  1. <template>
  2. <div>
  3. <testmap style="width:200px;height:200px" @mapLoaded="onMapLoaded"></testmap>
  4. </div>
  5. </template>
  6. <script>
  7. export default {
  8. methods: {
  9. onMapLoaded:function(e) {
  10. console.log("map loaded"+JSON.stringify(e))
  11. }
  12. }
  13. }
  14. </script>
2. 原生端实现:覆盖组件生命周期方法,记录事件是否需要处理

我们需要额外添加一个 BOOL 成员 mapLoadedEvent 用来记录该事件是否生效。

  1. /// 前端注册的事件会调用此方法
  2. /// @param eventName 事件名称
  3. - (void)addEvent:(NSString *)eventName {
  4. if ([eventName isEqualToString:@"mapLoaded"]) {
  5. _mapLoadedEvent = YES;
  6. }
  7. }
  8. /// 对应的移除事件回调方法
  9. /// @param eventName 事件名称
  10. - (void)removeEvent:(NSString *)eventName {
  11. if ([eventName isEqualToString:@"mapLoaded"]) {
  12. _mapLoadedEvent = NO;
  13. }
  14. }
3. 给前端发送事件
  1. - (void)mapViewDidFinishLoadingMap:(MKMapView *)mapView {
  2. if (_mapLoadedEvent) {
  3. // 想前端发送事件 params:传给前端的数据
  4. [self fireEvent:@"mapLoaded" params:@{@"customKey":@"customValue"} domChanges:nil];
  5. }
  6. }

自定义属性

给我们的地图组件添加一个新的属性showTraffic。在前端代码里可以控制组件是否显示路况信息

  1. <template>
  2. <div>
  3. <testmap style="width:200px;height:200px" showTraffic="true"></testmap>
  4. </div>
  5. </template>
原生端实现

1. 覆盖组件初始化方法 initWithRef... 给组件添加一个成员变量记录 showTraffic 属性的值,并在 init 方法中初始化。

  1. - (instancetype)initWithRef:(NSString *)ref type:(NSString *)type styles:(NSDictionary *)styles attributes:(NSDictionary *)attributes events:(NSArray *)events weexInstance:(WXSDKInstance *)weexInstance {
  2. if(self = [super initWithRef:ref type:type styles:styles attributes:attributes events:events weexInstance:weexInstance]) {
  3. if (attributes[@"showsTraffic"]) {
  4. _showsTraffic = [WXConvert BOOL: attributes[@"showsTraffic"]];
  5. }
  6. }
  7. return self;
  8. }

2. 在生命期事件中记得将属性值同步给地图控件

  1. - (void)viewDidLoad {
  2. ((MKMapView*)self.view).showsTraffic = _showsTraffic;
  3. }

3. 当属性更新时,同步给地图控件

  1. /// 前端更新属性回调方法
  2. /// @param attributes 更新的属性
  3. - (void)updateAttributes:(NSDictionary *)attributes {
  4. // 解析属性
  5. if (attributes[@"showsTraffic"]) {
  6. _showsTraffic = [WXConvert BOOL: attributes[@"showsTraffic"]];
  7. ((MKMapView*)self.view).showsTraffic = _showsTraffic;
  8. }
  9. }

更多的组件生命期方法

组件是由框架管理的,比如创建、布局、渲染、销毁。组件的生命周期方法都是可以重写的,你可以在这些生命周期中去做自己的事情。

方法描述
initWithRef:type:…用给定的属性初始化一个component.
layoutDidFinish在component完成布局时候会调用.
loadView创建component管理的view.
viewWillLoad在component的view加载之前会调用.
viewDidLoad在component的view加载完之后调用.
viewWillUnload在component的view被释放之前调用.
viewDidUnload在component的view被释放之后调用.
updateStyles:在component的style更新时候调用.
updateAttributes:在component的attribute更新时候调用.
addEvent:给component添加event的时候调用.
removeEvent:在event移除的时候调用.

给组件添加方法

1.原生端实现

在组件代码中使用宏 WX_EXPORT_METHOD 暴露原生方法供前端调用

  1. @implementation TestMapComponent
  2. // 通过 WX_EXPORT_METHOD 将方法暴露给前端
  3. WX_EXPORT_METHOD(@selector(focus:))
  4. - (void)focus:(NSDictionary *)options {
  5. // options 为前端传递的参数
  6. NSLog(@"%@",options);
  7. }
  8. @end

2.在uni小程序代码 中调用 focus: 方法。

  1. <template>
  2. <testmap ref='mycomponent'></testmap>
  3. </template>
  4. <script>
  5. module.exports = {
  6. created: function() {
  7. this.$refs.mycomponent.focus("Hello");
  8. }
  9. }
  10. </script>

至此,您已完成组件扩展;

以上示例中的完整uni小程序代码

  1. <template>
  2. <div>
  3. <button type="primary" @click="testAsyncFunc">testAsyncFunc</button>
  4. <button type="primary" @click="testSyncFunc">testSyncFunc</button>
  5. <testmap ref='mycomponent' style="width:200px;height:200px" showTraffic="true" @mapLoaded="onMapLoaded"></testmap>
  6. </div>
  7. </template>
  8. <script>
  9. // 获取 module
  10. var testModule = uni.requireNativePlugin("TestModule")
  11. export default {
  12. onLoad() {
  13. // 调用组件方法
  14. this.$nextTick(()=>{
  15. this.$refs.mycomponent.focus("Hello")
  16. })
  17. },
  18. methods: {
  19. testAsyncFunc() {
  20. // 调用异步方法
  21. testModule.testAsyncFunc({
  22. 'name': 'unimp',
  23. 'age': 1
  24. },
  25. (ret) => {
  26. console.log(ret)
  27. })
  28. },
  29. testSyncFunc() {
  30. // 调用同步方法
  31. var ret = testModule.testSyncFunc({
  32. 'name': 'unimp',
  33. 'age': 1
  34. })
  35. },
  36. onMapLoaded(e) {
  37. console.log("map loaded" + JSON.stringify(e))
  38. }
  39. }
  40. }
  41. </script>

发现错误?想参与编辑?在 GitHub 上编辑此页面!