Weex iOS SDK 集成指南

Weex iOS SDK 集成指南

如果需要集成weex sdk到现有的工程中，iOS提供两种常用方式：其一，源码依赖，可以在github上下载weex源码，然后迁移到工程中；其二，cocoapods依赖，这种方式相对比较简单，只需要在podfile中加入weex的版本依赖关系即可。现在就从零开始，为各位简述整个集成过程。

添加依赖（以pods依赖为例）

CocoaPods安装，如果您此前已安装，请跳过此步骤。

1. 移除现有的Ruby默认源
   gem sources --remove https://rubygems.org/
   使用新源
   gem sources -a https://ruby.taobao.org/
   验证新源替换是否成功
   gem sources -l
   安装CocoaPods
   sudo gem install cocoapods
   至此为止，整个CocoaPods就已安装成功了。

2. 在工程的Podfile文件中加入weex sdk的依赖。
   拷贝 ios/sdk下面目录到你的项目目录，在添加依赖之前，确保项目目录有Podfile，如果没有，创建一个，用文本编辑器打开，添加如下依赖

   如果使用正式版本如 0.6.1 的，就不需要做 拷贝ios/sdk 这个操作，直接引用cocoaPods的master repo 上就可以，这个需要在Podfile 最前面添加

source'https://github.com/CocoaPods/Specs.git'

target'YourTarget'do
    platform :ios, '7.0'# weex sdk 最低依赖的ios版本为7.0
    pod'WeexSDK', :path=>'./sdk/' # pod  'WeexSDK','0.6.1'  
end

1. 保存Podfile文件,在工程目录下执行pod install。执行完毕后，依赖就自动建立，您可以打开xcworkspace,正式进入Weex的开发环节了。

导入SDK集成

编译源码获得 weex framework SDK

1. clone Weex 项目
   可以用ssh 的方式

   git clone git@github.com:alibaba/weex.git

   
   

   或者直接使用https方式

2. git clone https://github.com/alibaba/weex.git

   
   

• 在XCode 中 打开 weex/ios/sdk 目录下的 WeexSDK.xcodeproj
  如下图切换 target
  

• 编译工程，或者直接使用XCode的快捷键 ? + b

• 最后你可以看到 weex/ios/sdk/Products 目录下生成了WeexSDK.framework 的包

• 你可以修改WeexSDK 然后打包生成你自己定制的Weex SDK

导入SDK到工程

• 并且导入系统的库，如下图
  
• 添加SocketRocket依赖：copy 这里 SRWebSocket.h/m 到自己的工程 （如果你的工程使用了cocoaPods，添加 pod 'SocketRocket' 到Podfie 中即可）

添加main.js(在WeexSDK.framework包中)

重要提示

添加 -ObjC 如下图(注意大小写)

环境初始化

weex运行环境的初始化，主要包括以下几个方面：应用配置（应用名、版本号、UA等）；注册自定义的Module和Component；注册SDK已有协议的实现类。所有初始化的步骤在AppDelegate中完成。

1、 头文件

#import<WeexSDK/WXSDKEngine.h>
#import<WeexSDK/WXLog.h>
#import<WeexSDK/WXDebugTool.h>
#import<WeexSDK/WXAppConfiguration.h>

WXSDKEngine：SDK开放的绝大多数接口都在此有声明。

WXLog: 控制Log输出的级别，包括Verbose、Debug、Info、Warning、Error，开发者可以按需来设置输出级别。

WXDebugTool: weex提供的对外调试工具。

WXAppConfiguration: 使用weex开发的业务性配置。

2、初始化

在appdelegate.m的didFinishLaunchingWithOptions回调中执行。

//业务配置，非必需
[WXAppConfiguration setAppGroup:@"AliApp"];
[WXAppConfiguration setAppName:@"WeexDemo"];
[WXAppConfiguration setAppVersion:@"1.0.0"];
 
//初始化SDK环境   
[WXSDKEngine initSDKEnviroment];
  
//注册自定义module和component，非必需
[WXSDKEngine registerComponent:@"MyView"withClass:[MyViewComponent class]];
[WXSDKEngine registerModule:@"event"withClass:[WXEventModule class]];
 
//注册协议的实现类，非必需
[WXSDKEngine registerHandler:[WXNavigationDefaultImpl new] withProtocol:@protocol(WXNavigationProtocol)];
 
//设置Log输出等级：调试环境默认为Debug，正式发布会自动关闭。   
[WXLog setLogLevel:WXLogLevelVerbose];

经过以上简单的配置，WeexSDK的环境初始化已完成，下面就进入Weex动态化页面渲染环节。

Weex页面渲染

weex支持全页面以及页面局部两种不同的渲染模式。在iOS中使用方法很简单，只需要将weex渲染所得的view添加到父容器中即可。下面会介绍如何在iOS最常用的容器viewController中渲染weex页面。

1、头文件

#import<WeexSDK/WXSDKInstance.h>

现在来介绍下WXSDKInstance究竟是什么，如何来使用它。

WXSDKInstance，简单来说，就是weex渲染的实例对象。它提供给开发者诸多跟页面渲染相关的接口，包括renderWithURL、refreshInstance以及destroyInstance等，提供了几个比较重要的回调接口，方便开发者根据不同的业务场景去处理他们的逻辑，如onfailed，还提供了性能监控相关的接口。

2、页面渲染

- (void)viewDidLoad
{
    [superviewDidLoad];
     
    _instance = [[WXSDKInstance alloc] init];
    _instance.viewController = self;
    _instance.frame = self.view.frame; //必需
    [_instance renderWithURL:self.url options:@{@"bundleUrl":[self.url absoluteString]} data:nil];
     
    __weak typeof(self) weakSelf = self;
    _instance.onCreate = ^(UIView *view) {
        [weakSelf.weexView removeFromSuperview];
        [weakSelf.view addSubview:weakSelf.weexView];
    };
     
    _instance.onFailed = ^(NSError *error) {
        //处理失败回调的逻辑。
    };
     
    _instance.renderFinish = ^ (UIView *view) {
        //处理页面渲染完成的逻辑。
    };
}

以上是通过weex实例来渲染页面的简单例子。其中有几点需要着重说明下：

instance.viewController: 一般情况下，iOS的运行环境都是基于不同viewController的，很多底层操作需要知晓当前所处的viewController对象，因此需要向instance知会当前的viewController。

instance.frame: 根据weex对instance的设计规范，需要渲染中知道最外层body的位置和尺寸。这个frame值的设置，跟最终在回调中获取的view.frame一致。

当然，在很多场景下，仅需要在一个native页面的局部渲染weex区块。很简单，您只需要将instance.frame设置为目标区块的位置尺寸即可。

renderWithURL：常用的渲染方式：其一，直接输入URL（可以是file://或 http(s)://）；其二，sourceCode，即JavaScript源码。options参数，表示开发者可以通过WeexSDK向前端透传的参数，如bundleURL。data参数，表示向weex的模板注入的页面数据，它一般来源于native的数据请求，当然也可以在前端逻辑中完成请求后将数据注入。

_instance.onCreate：weex页面最外层body渲染完成后的回调。在此回调中，weex渲染所得的rootView已确定，可以输出并添加到父容器中。

_instance.renderFinish：和onCreate不同，renderFinish表示所有weex的页面元素都已渲染完毕，整个渲染过程至此结束。

其他跟instance紧密相关的接口，请参见WXSDKInstance.h的详细说明。

3、页面销毁

切记在viewController的销毁的同时，将weex实例一并销毁，否则会出现内存泄露。

- (void)dealloc
{
    [_instance destroyInstance];
}

其他

在页面渲染这个部分，本文已向您详细介绍了成功接入WeexSDK后，如何通过加载URL的方式渲染得到视图。此外，您也可以通过我们的github下载最新的playground代码并编译，它可以提供二维码扫描预览以及在线debug等功能。

关于如何去编写自定义的module、component，如何去注册全新的协议实现类，我们会在后续的文档中为您讲述。

点击下载 WeexSample

FAQ

1、在集成WeexSDK时，编译中遇到 [warn]WXModuleFactory.m:49, The module class [(null)] doesn’t exit!是什么问题？

请在Build Settings的Other Link Flags加入-ObjC。

总结

Weex作为一种全新的动态化页面部署方案，备受关注。通过本文的介绍，相信不论你是前端还是客户端，都对如何在iOS平台下接入WeexSDK并使用有了全面的认识，如果您有任何问题想要和我们交流，欢迎加入weex讨论群，我们很高兴为您服务。