• SDK基于Swift开发,因此原生Objective-C语言开发的应用需要新建一个Swift文件用于添加Swift运行环境以及桥接SDK的API,详情可参考UniAppXDemo工程中的UniAppBridge

SDK 5.24 及以上:iOS 使用 UIScene 生命周期。请按照下方 SceneDelegate 示例接入,不再在 AppDelegate 中处理窗口和前后台生命周期。

注意:4.81 之前版本请先升级到 4.81 及以上版本,再按照本文集成 SDK。

# UniAppXSDK API

# 初始化 SDK

import DCloudUniappRuntime

// 初始化 SDK
UniAppXSDK.initSDK()

# 打开 SDK 页面

let options = UniAppXSDKStartOptions.init()
options.appScheme = "your-app-scheme"
options.appLink = "your-app-link"
options.openType = .push
options.animationType = .auto

UniAppXSDK.start(options: options)

# 打开并获取应用管理对象

蒸汽模式 SDK 5.36 及以上支持。

使用 UniAppXSDK.open(options:completion:) 打开应用,在完成回调中获取应用管理对象 UniAppXSDKApp,后续通过该对象显示、隐藏或关闭应用。

import UIKit
import DCloudUniappRuntime

class SDKHostViewController: UIViewController {
    private var sdkApp: UniAppXSDKApp?

    func openUniApp() {
        let options = UniAppXSDKStartOptions()
        options.openType = .push // 需要导航控制器,也可以使用 .present
        options.animationType = .auto
        options.viewController = self
        options.enableBackground = true // 返回原生宿主后保留应用
        options.enableGestureClose = true // 开启 SDK 左边缘返回手势

        UniAppXSDK.open(options: options) { [weak self] result in
            switch result {
            case .success(let app):
                self?.sdkApp = app
                app.onClose = { [weak self] in
                    self?.sdkApp = nil
                    print("uni-app x 应用已关闭")
                }
            case .failure(let error):
                print("打开失败:\(error.localizedDescription)")
            }
        }
    }
}

open 的完成回调类型为 (Result<UniAppXSDKApp, UniAppXSDKError>) -> Void。成功表示应用已创建且展示转场已完成,首页仍可能继续渲染。

SDK 同一时间只管理一个应用实例,应用标识使用宿主 Info.plist 中的 uniapp-x.appid。SDK 会持有当前实例,也可通过 UniAppXSDK.currentApp 获取,类型为 UniAppXSDKApp?。已隐藏或正在关闭的实例仍占用该名额,再次调用 open 返回 alreadyRunning,恢复隐藏实例应调用其 show 方法。

原有 start(options:) 入口继续支持;需要获取管理对象及处理打开结果时使用 open(options:completion:)。

# UniAppXSDKStartOptions 参数说明

配置启动选项的类。

属性 类型 默认值 说明
appScheme String? nil 应用 Scheme,用于深度链接
appLink String? nil 应用链接地址
openType UniAppXSDKStartOptionsOpenType .push 打开方式:push 或 present
enableBackground Bool false 返回原生宿主后是否保留应用,详见下方“后台运行”。蒸汽模式 SDK 5.36 及以上支持
enableGestureClose Bool false 是否启用 SDK 左边缘返回手势,支持 push 和 present;返回后按 enableBackground 隐藏或销毁应用。蒸汽模式 SDK 5.36 及以上支持
animationType UniAppXSDKStartOptionsAnimationType .auto 动画类型
animationDuration TimeInterval 0.35 动画持续时间(秒)
customAnimationDelegate UniAppXSDKCustomAnimationDelegate? nil 自定义动画代理
viewController UIViewController? nil 指定的视图控制器
# 动画类型 (UniAppXSDKStartOptionsAnimationType)
  • .auto - 使用系统默认动画
  • .none - 无动画
  • .slideInRight - 从右侧滑入
  • .slideInLeft - 从左侧滑入
  • .slideInTop - 从顶部滑入
  • .slideInBottom - 从底部滑入
  • .fadeIn - 淡入效果
  • .zoomOut - 放大进入
  • .zoomFadeOut - 放大淡入
  • .popIn - 弹出效果
  • .custom - 使用自定义动画代理
# 自定义动画代理 (UniAppXSDKCustomAnimationDelegate)

实现自定义动画效果,示例如下:

class ViewController: UniAppXSDKCustomAnimationDelegate {
    public func customEnterAnimation(fromVC: UIViewController, toVC: UIViewController, completion: @escaping (Bool) -> Void) {
        // Push 模式: 添加到导航控制器
        if let navController = fromVC.navigationController {
            navController.view.addSubview(toVC.view)
            toVC.view.frame = navController.view.bounds

            toVC.view.transform = CGAffineTransform(translationX: navController.view.bounds.width, y: 0)
                .concatenating(CGAffineTransform(scaleX: 0.8, y: 0.8))
            toVC.view.alpha = 0.7

            UIView.animate(withDuration: 0.6, delay: 0, options: .curveEaseInOut) {
                toVC.view.transform = .identity
                toVC.view.alpha = 1.0
            } completion: { finished in
                navController.pushViewController(toVC, animated: false)
                toVC.view.removeFromSuperview()
                completion(finished)
            }
        } else {
            //如果没有导航控制器你可以 用present方式跳转 实现其他动画效果
            completion(true)
        }
    }
    
    
    public func customExitAnimation(currentVC: UIViewController, completion: @escaping (Bool) -> Void) {
        // Push 模式的退出动画:简单翻页效果
        if let navController = currentVC.navigationController {
            let viewControllers = navController.viewControllers
            if viewControllers.count > 1 {
                navController.popViewController(animated: false)
                navController.view.addSubview(currentVC.view)
                currentVC.view.frame = navController.view.bounds

                UIView.animate(withDuration: 0.6, delay: 0, options: .curveEaseInOut) {
                    currentVC.view.transform = CGAffineTransform(translationX: -navController.view.bounds.width, y: 0)
                        .concatenating(CGAffineTransform(scaleX: 0.8, y: 0.8))
                    currentVC.view.alpha = 0.7
                } completion: { finished in
                    currentVC.view.removeFromSuperview()
                    completion(finished)
                }
            } else {
                completion(true)
            }
        } else {
            completion(true)
        }
    }
}

// 使用自定义动画
options.customAnimationDelegate = self
options.animationType = .custom

# 应用管理对象 UniAppXSDKApp

蒸汽模式 SDK 5.36 及以上支持。

通过 open 的成功回调或 UniAppXSDK.currentApp 获取实例。

属性 类型 说明
appID String 应用标识,只读
state UniAppXSDKAppState 当前状态,只读
isVisible Bool 当前状态为 visible 时返回 true,只读
onClose (() -> Void)? 应用完成销毁后的回调,每个实例触发一次

UniAppXSDKAppState 包含 starting(启动中)、visible(已显示)、hiding(隐藏中)、hidden(已隐藏)、showing(恢复显示中)、closing(关闭中)和 closed(已关闭)。

读取 currentApp、实例状态以及设置 onClose 应在主线程进行。open、show、hide、close 可以从任意线程调用,操作和完成回调均在主线程执行。

# 显示与隐藏

蒸汽模式 SDK 5.36 及以上支持。

通过应用实例的 hide 隐藏应用并返回原生宿主,保留页面和 JS 运行状态;通过同一实例的 show 恢复应用。显式调用 hide 时,无论 enableBackground 的值如何,都会保留实例。

以下方法可添加到上方示例中的 SDKHostViewController,通过按钮或业务事件分别调用。

func hideUniApp() {
    guard let app = sdkApp else { return }

    let options = UniAppXSDKHideOptions()
    options.animationType = .slideOutRight
    options.animationDuration = 0.3 // 单位为秒
    app.hide(options: options) { result in
        switch result {
        case .success:
            print("应用已隐藏,页面状态已保留")
        case .failure(let error):
            print("隐藏失败:\(error.localizedDescription)")
        }
    }
}

func showUniApp() {
    guard let app = sdkApp else { return }

    let options = UniAppXSDKShowOptions()
    options.animationType = .slideInRight
    options.animationDuration = 0.3
    options.viewController = self
    app.show(options: options) { result in
        switch result {
        case .success:
            print("应用已恢复显示")
        case .failure(let error):
            print("显示失败:\(error.localizedDescription)")
        }
    }
}

# UniAppXSDKShowOptions 参数说明

属性 类型 默认值 说明
animationType UniAppXSDKShowOptionsAnimationType .auto 与 UniAppXSDKStartOptionsAnimationType 相同,支持上方列出的全部进入动画
animationDuration TimeInterval 0.35 内置动画持续时间,单位为秒
customAnimationDelegate UniAppXSDKCustomAnimationDelegate? nil 使用 .custom 时必须设置
viewController UIViewController? nil 恢复显示的宿主控制器,默认从首次打开时所在窗口场景查找当前可见控制器

show 沿用首次打开时的 push/present 方式和窗口场景。宿主控制器需要已挂载到窗口并可见,push 方式需要导航控制器。

# UniAppXSDKHideOptions 参数说明

属性 类型 默认值 说明
animationType UniAppXSDKHideOptionsAnimationType .auto 隐藏动画,取值见下方列表
animationDuration TimeInterval 0.35 内置动画持续时间,单位为秒
customAnimationDelegate UniAppXSDKCustomAnimationDelegate? nil 使用 .custom 时必须设置

隐藏动画支持 .auto(系统动画)、.none(无动画)、.slideOutRight(向右滑出)、.slideOutLeft(向左滑出)、.slideOutTop(向上滑出)、.slideOutBottom(向下滑出)、.fadeOut(淡出)和 .custom(自定义动画)。

show、hide 的 options 和 completion 均可省略,例如 app.hide()、app.show()。省略 options 时复用首次打开的动画配置;传入配置对象时使用该对象的值。.auto 动画的时长由 UIKit 控制。

使用 .custom 时,宿主代理需要完成与首次打开的 openType 对应的 push/pop 或 present/dismiss,并调用一次完成回调。缺少 customAnimationDelegate 时返回 customAnimationDelegateRequired。

完成回调类型均为 UniAppXSDKCompletion,即 (Result<Void, UniAppXSDKError>) -> Void。成功时对应转场已完成。已显示时再次 show、已隐藏时再次 hide 均直接成功;转场期间调用这两个方法返回 busy。

# 后台运行

蒸汽模式 SDK 5.36 及以上支持。

打开时设置 UniAppXSDKStartOptions.enableBackground,控制宿主返回手势或直接移除 SDK 根控制器后的行为。该配置在首次打开时生效。

enableBackground 返回原生宿主后的行为
false(默认值) 销毁应用,完成后触发实例的 onClose
true 应用进入 hidden 状态,保留页面和 JS Runtime。可通过 show 恢复,或通过 close 销毁

后台运行指返回原生宿主后保留应用实例;宿主应用进入 iOS 系统后台后,执行仍受系统调度及后台能力配置限制。

需要 SDK 左边缘返回手势时,同时设置 enableGestureClose = true。该手势支持 push/present,应用内部页面的返回手势优先。首次打开或当前 show 使用自定义动画时,返回交互由宿主处理。返回手势取消时应用继续保持显示状态。

显式调用 hide 会保留应用;调用 close、UniAppXSDK.exit() 或 uni.exit() 会销毁应用,这些操作的行为独立于 enableBackground。

# 退出 SDK 页面

根据您的需求,选择以下方式调用退出SDK

  • 原生项目中退出调用UniAppXSDK.exit()
  • uni-app x项目中退出调用uni.exit()

# 通过应用管理对象关闭

蒸汽模式 SDK 5.36 及以上支持。

close(completion:) 可以关闭正在显示或已经隐藏的实例。以下方法可添加到上方示例中的 SDKHostViewController。

func closeUniApp() {
    sdkApp?.close { result in
        switch result {
        case .success:
            print("应用已完成销毁,可以重新打开")
        case .failure(let error):
            print("关闭失败:\(error.localizedDescription)")
        }
    }
}

completion 可省略,类型为 UniAppXSDKCompletion。成功回调在页面和 Runtime 完成销毁后触发。启动、显示或隐藏转场期间调用 close,会等待当前转场结束后关闭。

实例销毁后依次触发 onClose 和 close 的完成回调;调用 uni.exit() 或宿主返回导致销毁时,也会触发 onClose。SDK 会在回调前清空 currentApp,可在回调中打开新实例。宿主持有实例并设置闭包时,应使用弱引用避免循环持有。

已关闭的实例保持 closed 状态,重复调用 close 直接成功;调用 show 或 hide 返回 closed。再次启动需通过 UniAppXSDK.open 创建新实例。

# UniAppXSDKError 错误说明

蒸汽模式 SDK 5.36 及以上支持。

通过 open、show、hide、close 完成回调的 failure 分支获取错误。

错误 说明
alreadyRunning 已有实例,包含隐藏或关闭中的实例
closed 实例已经关闭
busy 实例正处于转场中,或已请求关闭
invalidHost 宿主控制器无效、不可见或窗口场景不匹配
navigationControllerRequired push 方式需要导航控制器
customAnimationDelegateRequired 使用 .custom 时缺少自定义动画代理
creationFailed 应用创建失败
transitionCancelled 转场被取消
transitionFailed 控制器层级未达到请求的显示或移除状态

# 生命周期集成

5.24 及以上版本使用 UIScene 生命周期。先在 Info.plist 中声明 scene 配置;SceneDelegate 类名需与下方示例保持一致。

<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <false/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>UIWindowSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneConfigurationName</key>
                <string>Default Configuration</string>
                <key>UISceneDelegateClassName</key>
                <string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
            </dict>
        </array>
    </dict>
</dict>

AppDelegate 中初始化 SDK,并配置 scene delegate;窗口创建、前后台切换、URL Scheme 和 Universal Link 回调转发到 UniAppRootSceneDelegate。如果工程已有自己的 SceneDelegate,请将下面的转发代码合并进去。

// AppDelegate.swift
import UIKit
import DCloudUniappRuntime

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        UniAppXSDK.initSDK()
        UniAppXSDK.applicationDidFinishLaunchingWithOptions(application, launchOptions)
        return true
    }

    @available(iOS 13.0, *)
    func application(_ application: UIApplication,
                     configurationForConnecting connectingSceneSession: UISceneSession,
                     options: UIScene.ConnectionOptions) -> UISceneConfiguration {
        let configuration = UISceneConfiguration(name: "Default Configuration",
                                                  sessionRole: connectingSceneSession.role)
        configuration.delegateClass = SceneDelegate.self
        return configuration
    }

    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        UniAppXSDK.didRegisterForRemoteNotifications(deviceToken)
    }

    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        UniAppXSDK.didFailToRegisterForRemoteNotifications(error)
    }

    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                     fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        UniAppXSDK.applicationDidReceiveRemoteNotificationCompletionHandler(application, userInfo, completionHandler)
    }
}
// SceneDelegate.swift
import UIKit
import DCloudUniappRuntime

@available(iOS 13.0, *)
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?
    private let sdkSceneDelegate = UniAppRootSceneDelegate()

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
               options connectionOptions: UIScene.ConnectionOptions) {
        sdkSceneDelegate.scene(scene, willConnectTo: session, options: connectionOptions)
        guard let windowScene = scene as? UIWindowScene else { return }

        let storyboard = UIStoryboard(name: "Main", bundle: nil)
        let initialViewController = storyboard.instantiateInitialViewController()!
        window = sdkSceneDelegate.window ?? UIWindow(windowScene: windowScene)
        window?.rootViewController = UINavigationController(rootViewController: initialViewController)
        (UIApplication.shared.delegate as? AppDelegate)?.window = window
        window?.makeKeyAndVisible()
    }

    func sceneDidBecomeActive(_ scene: UIScene) { sdkSceneDelegate.sceneDidBecomeActive(scene) }
    func sceneWillResignActive(_ scene: UIScene) { sdkSceneDelegate.sceneWillResignActive(scene) }
    func sceneWillEnterForeground(_ scene: UIScene) { sdkSceneDelegate.sceneWillEnterForeground(scene) }
    func sceneDidEnterBackground(_ scene: UIScene) { sdkSceneDelegate.sceneDidEnterBackground(scene) }
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        sdkSceneDelegate.scene(scene, openURLContexts: URLContexts)
    }
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        sdkSceneDelegate.scene(scene, continue: userActivity)
    }
}

推送相关回调仍在 AppDelegate 中处理;其他生命周期和 URL/Universal Link 回调均在 SceneDelegate 中转发。

# 通信

iOS平台目前不支持直接在uvue页面调用原生API,开发者可通过UTS插件发送/接收 通知消息实现与原生App通信,具体实现代码如下:

# 原生APP向SDK发消息

UTS插件添加监听:

const name = "com.ios.notification.name1"; //通知消息标识
const notificationName = new Notification.Name(name);
const method = Selector("handleReceiveMessage:")//接收通知消息的方法名
NotificationCenter.default.addObserver(this, selector = method, name = notificationName, object = null)
@objc static handleReceiveMessage(notification : Notification) {
	let userInfo = notification.userInfo
	if(userInfo != null){
		const message = userInfo!["msg"];
	}
}

原生发送通知消息:

let name = "com.ios.notification.name1"; //通知消息标识
let message = "消息内容";
let userInfo: [AnyHashable: Any] = [
    "msg": message // 你可以在这里放置任何需要传递的信息
]
NotificationCenter.default.post(name: Notification.Name(name), object: nil, userInfo: userInfo)

# SDK向原生APP发消息

原生添加通知监听:

const name = "com.ios.notification.name2"; //通知消息标识
NotificationCenter.default.addObserver(self, selector: #selector(handleNotification(_:)), name: Notification.Name(name), object: nil)
@objc func handleNotification(_ notification: Notification) {
    if let message = (notification.userInfo?["msg"] as? String) {
        // 使用message
        print(message)
    }
}

UTS插件发送消息:

const name = "com.ios.notification.name2"; //通知消息标识
const message = "消息内容";
const notificationName = new Notification.Name(name);
const userInfo = new Map<string,any>()
userInfo.set("msg", message); // 你可以在这里放置任何需要传递的信息
NotificationCenter.default.post(name = notificationName, object = null, userInfo = userInfo);

注意:消息接收方必须在发送通知前添加监听事件,否则收不到消息

# 运行示例

  • 蒸汽模式 SDK工程 UniAppXVaporDemo 中,unimoduleTesIosNotification 为 UTS 插件,用于演示通信示例,UniAppXSample 为对应的 uni-app-x 源码示例工程
  • VDOM 模式SDK工程 UniAppXDemo工程中,__UNI__00DC103为通信示例资源文件,将Info.plist中uniapp-x节点下的appid改为__UNI__00DC103,并添加unimoduleTestIosNotification.xcframework依赖,即可体验通信示例