- SDK基于Swift开发,因此原生Objective-C语言开发的应用需要新建一个Swift文件用于添加Swift运行环境以及桥接SDK的API,详情可参考UniAppXDemo工程中的
UniAppBridge
SDK 5.24 及以上:iOS 使用
UIScene生命周期。请按照下方SceneDelegate示例接入,不再在AppDelegate中处理窗口和前后台生命周期。
注意:4.81 之前版本请先升级到 4.81 及以上版本,再按照本文集成 SDK。
import DCloudUniappRuntime
// 初始化 SDK
UniAppXSDK.initSDK()
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:)。
配置启动选项的类。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
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 | 指定的视图控制器 |
.auto - 使用系统默认动画.none - 无动画.slideInRight - 从右侧滑入.slideInLeft - 从左侧滑入.slideInTop - 从顶部滑入.slideInBottom - 从底部滑入.fadeIn - 淡入效果.zoomOut - 放大进入.zoomFadeOut - 放大淡入.popIn - 弹出效果.custom - 使用自定义动画代理实现自定义动画效果,示例如下:
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
蒸汽模式 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)")
}
}
}
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
animationType | UniAppXSDKShowOptionsAnimationType | .auto | 与 UniAppXSDKStartOptionsAnimationType 相同,支持上方列出的全部进入动画 |
animationDuration | TimeInterval | 0.35 | 内置动画持续时间,单位为秒 |
customAnimationDelegate | UniAppXSDKCustomAnimationDelegate? | nil | 使用 .custom 时必须设置 |
viewController | UIViewController? | nil | 恢复显示的宿主控制器,默认从首次打开时所在窗口场景查找当前可见控制器 |
show 沿用首次打开时的 push/present 方式和窗口场景。宿主控制器需要已挂载到窗口并可见,push 方式需要导航控制器。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
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
UniAppXSDK.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 创建新实例。
蒸汽模式 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通信,具体实现代码如下:
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)
原生添加通知监听:
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);
注意:消息接收方必须在发送通知前添加监听事件,否则收不到消息
UniAppXVaporDemo 中,unimoduleTesIosNotification 为 UTS 插件,用于演示通信示例,UniAppXSample 为对应的 uni-app-x 源码示例工程UniAppXDemo工程中,__UNI__00DC103为通信示例资源文件,将Info.plist中uniapp-x节点下的appid改为__UNI__00DC103,并添加unimoduleTestIosNotification.xcframework依赖,即可体验通信示例