通過Stage模型開發iOS端應用指南

簡介

本文介紹將ArkUI框架擴展到iOS平臺所需要的必要類及其使用說明，開發者基于OpenHarmony，可復用大部分的應用代碼（生命周期等）并可以部署到iOS平臺，降低跨平臺應用開發成本。

ArkUI-X和iOS平臺集成所用關鍵類

開發前請熟悉鴻蒙開發指導文檔：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

StageViewController

StageViewController是Stage模型iOS端視圖控制器基類，若要實現跨平臺基礎能力及觸發對應ability生命周期，所有iOS端應用級別的視圖控制器均要繼承于StageViewController。

公共屬性

instanceName：StageViewController唯一標識，拼接規則為 bundleName:moduleName:abilityName ，其中bundleName的值來自于OpenHarmony應用中app.json5配置文件，moduleName、abilityName的值來自于OpenHarmony應用中的module.json5配置文件。

@property (nonatomic, readonly) NSString *instanceName;

params：StageViewController外部屬性，用于startAbility時傳遞的want參數。

@property (nonatomic, strong) NSString *params;

初始化方法

- (instancetype)initWithInstanceName:(NSString *_Nonnull)instanceName;

StageApplication

StageApplication本質上是一個調度類，主要用于觸發內部相關類實現路徑解析與配置、注冊應用相關的configuration信息、觸發ability部分生命周期事件等。

公共方法

配置本地hap包路徑。

+ (void)configModuleWithBundleDirectory:(NSString *_Nonnull)bundleDirectory;

iOS應用觸發StartAbility、配置進程id、本地化信息、configuration等。

+ (void)launchApplication;

觸發ability進入前臺生命周期事件。

+ (void)callCurrentAbilityOnForeground;

觸發ability進入后臺生命周期事件。

+ (void)callCurrentAbilityOnBackground;

處理單/多實例ability。

+ (BOOL)handleSingleton:(NSString *)bundleName moduleName:(NSString *)moduleName abilityName:(NSString *)abilityName;

釋放導航視圖棧內的所有viewController，觸發OnDestory事件。

+ (void)releaseViewControllers;

獲取導航視圖棧最頂層viewController。

+ (StageViewController *)getApplicationTopViewController;

AppDelegate內關鍵實現參考

ArkUI應用啟動及初始化

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 配置hap包路徑
    [StageApplication configModuleWithBundleDirectory:@"arkui-x"];
    // 啟動ability
    [StageApplication launchApplication];
    
    // APP自啟動,初始化StageViewController子類VC，并設置為APP根視圖控制器
    if (!launchOptions.count) { 
        NSString *instanceName = [NSString stringWithFormat:@"%@:%@:%@",@"com.example.iosabilitystage", @"entry", @"MainAbility"];
        EntryMainViewController *mainView = [[EntryMainViewController alloc] initWithInstanceName:instanceName];
    UINavigationController *navi = [[UINavigationController alloc]initWithRootViewController:mainView];
        self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
        self.window.rootViewController = navi;
        [self.window makeKeyAndVisible];
    }
    return YES;
}

ArkUI應用實現頁面跳轉

當在iOS平臺上使用[startability]接口實現頁面跳轉時，需要參考下述示例進行開發。

通過路由模式（openURL:）實現的iOS應用頁面跳轉回調，獲取傳遞參數

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary< NSString *,id > *)options {

    // 根據規則截取URL相應參數
    NSString *bundleName = url.scheme;
    NSString *moduleName = url.host;
    NSString *abilityName, *params;

    NSURLComponents *urlComponents = [NSURLComponents componentsWithString:url.absoluteString];
    NSArray < NSURLQueryItem * > *array = urlComponents.queryItems;
    for (NSURLQueryItem * item in array) {
        if ([item.name isEqualToString:@"abilityName"]) {
            abilityName = item.value;
        } else if ([item.name isEqualToString:@"params"]) {
            params = item.value;
        }
    }
    // 單實例ability處理
    if ([StageApplication handleSingleton:bundleName moduleName:moduleName abilityName:abilityName] == YES) {
        return YES;
    }
    [self handleOpenUrlWithBundleName:bundleName
                           moduleName:moduleName
                          abilityName:abilityName
                               params:params, nil];
    return YES;
}

通過解析url得到的參數，映射ability對應的viewController

- (BOOL)handleOpenUrlWithBundleName:(NSString *)bundleName
                         moduleName:(NSString *)moduleName
                        abilityName:(NSString *)abilityName
                             params:(NSString *)params, ...NS_REQUIRES_NIL_TERMINATION {
                                               
    NSString *instanceName = [NSString stringWithFormat:@"%@:%@:%@",bundleName, moduleName, abilityName];
    
    // 根據moduleName和abilityName映射對應的viewController
    // 注意：傳入的moduleName或者abilityName錯誤，則無法找到對應的viewController，此時無法打開頁面。
    if ([moduleName isEqualToString:@"entry"] && [abilityName isEqualToString:@"MainAbility"]) {
        EntryMainAbilityViewController *entryMainVC = [[EntryMainAbilityViewController alloc] initWithInstanceName:instanceName];
        entryMainVC.params = params;
    } else if ([moduleName isEqualToString:@"entry"] && [abilityName isEqualToString:@"Other"]) {
        EntryOtherViewController *entryOtherVC = [[EntryOtherViewController alloc] initWithInstanceName:instanceName];
        entryOtherVC.params = params;
    }

    return YES;
}

ArkUI應用生命周期回調相應處理

ArkUI應用進入后臺，觸發對應生命周期事件。

- (void)applicationDidEnterBackground:(UIApplication *)application {
    [StageApplication callCurrentAbilityOnBackground];
}

ArkUI應用進入前臺，觸發對應生命周期事件。

- (void)applicationWillEnterForeground:(UIApplication *)application {
    [StageApplication callCurrentAbilityOnForeground];
}

終止ArkUI應用程序進程。

- (void)applicationWillTerminate:(UIApplication *)application {
    [StageApplication releaseViewControllers];
}

注具體方法使用參考samples示例

Ability與ViewController對應規則

iOS端應用info配置里的bundleName需要與Ability的bundleName一致。

iOS端應用內的viewController的viewControllerName組成規則：Ability的moduleName + Ability的abilityName + “viewController”。

stage_iOS

StageApplication初始化支持以下兩種方式

在didFinishLaunchingWithOptions函數中進行初始化

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 配置hap包路徑
    [StageApplication configModuleWithBundleDirectory:@"arkui-x"];
    // 啟動ability
    [StageApplication launchApplication];

    // APP自啟動,初始化StageViewController子類VC，并設置為APP根視圖控制器
    if (!launchOptions.count) { 
        NSString *instanceName = [NSString stringWithFormat:@"%@:%@:%@",@"com.example.iosabilitystage", @"entry", @"MainAbility"];
        EntryMainViewController *mainView = [[EntryMainViewController alloc] initWithInstanceName:instanceName];
        UINavigationController *navi = [[UINavigationController alloc]initWithRootViewController:mainView];
        self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
        self.window.rootViewController = navi;
        [self.window makeKeyAndVisible];
    }
    return YES;
}

`HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿`

搜狗高速瀏覽器截圖20240326151547.png

在openURL回調函數中進行初始化

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 不在此處進行初始化

    ExampleViewController *mainView = [[ExampleViewController alloc] init];
    UINavigationController *navi = [[UINavigationController alloc]initWithRootViewController:mainView];
    self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
    self.window.rootViewController = navi;
    [self.window makeKeyAndVisible];
    return YES;
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary< NSString *,id > *)options {

    // 初始化StageApplication
    [StageApplication configModuleWithBundleDirectory:@"arkui-x"];
    [StageApplication launchApplication];
    
    /*
    other code
    */
    return YES;
}